The purpose of this guide is to lay out the steps for configuring security alerts in a Microsoft Teams channel which is supported through the Microsoft Security Graph API. These alerts cover ALL SECURITY ALERTS that are reported in 365 and Azure. In this guide, I will be showing you how to configure the alerts gathered through the graph with a webhook in Teams. The steps outlined were derived from ideas conceived originally by a blogger known as The Lazy Administrator. You can check out his site here for some great articles.
The Microsoft Graph Security API connects multiple security solutions to enable easier correlation of alerts, provide access to rich contextual information, simplify automation and investigations. Here are some of the benefits to MSPs for when using Microsoft Graph:
- Streamlined integration with security operations tools, workflows, and reporting.
- Security alerts spanning across both Microsoft 365 and Azure
- Reduced deployment and maintenance time and efforts.
- Automated response to alerts by taking action on threats.
- Ability to deliver more value to customers.
- Real-time alerts in Microsoft Teams
Creating your Registered App for Authentication
The Microsoft Graph API uses a registered app to generate tokens for authentication into our tenants. The first step of our process is creating this app and giving it the necessary permissions to read security data in our tenant.
Go to https://aad.portal.azure.com, sign-in with a global admin to the tenant, and click on the Azure Active Directory tab
New App Registration
Click on App Registrations and click +New Registration
Configure App
Name you App and then scroll down to the Redirect URI section. Select Public Client from the dropdown and paste the following in the txt field: urn:ietf:wg:oauth:2.0:oob
Grab AppID
Take note of the Application (Client) ID. Paste in a notepad somewhere
Add Permissions
Click on API Permissions> Add Permissions
Choose Microsoft Graph
Choose Microsoft Graph, then Delegated Permissions
Choose Security Permissions
From here, we will scroll down to the Security Section and select all permissions
Grant Consent
Click Grant Consent and view success message
Grant Consent
Click Grant Consent and view success message
Creating Powershell Webhook
The powershell webhook to Teams give us the following benefits:
- Real-time security alerts spanning across our tenants M365 and Azure Subscriptions
- No cost to us to run
- Name, Description, Severity, and names of users causing the alerts if applicable
Create/Choose Microsoft Teams Channel
The first thing we need to do is configure the webhook in a Microsoft Teams Channel. Ideally, you would want this as either a helpdesk channel or security channel, specifically for monitoring security alerts. There are two ways you could manage these alerts:
- In one Teams channel, using the same webhook url across all of your customers. We gather the tenantIDs in the output so you would be able to differentiate customers
- In a Teams channel per tenant. This would separate out alerts across different orgs rather than that all going through one. This is more ideal if you have many customers or many alerts coming through. You can use the multi-tenant functionality in teams to toggle between tenants
Add the App
Once the team is created, click the + icon and then More Apps
Select Incoming Webhook
From here, search for Webhook and then select Incoming Webhook
Install
Click Install then Setup
Grab Url
Add a name and custom image if you want then click Create. On the page that follows copy the URL given
Grab Script
Now that we have the webhook created, we can run my script to ensure alerts are successfully going to push to our teams channel. Go to Github here to grab my script
Modify Script
1.Line 73: Enter your app id for the App we created in the first section
2.Line 247: Enter your webhook you copied in this section
Install Modules
Open Powershell as Admin and run the script. Install the two modules if you don’t already have them:
- Install-Module AzureAD
- Install-Module MicrosoftGraphSecurity
Run Script
Run the script you modified from Github. You will be prompted to enter your UPN. Enter a global admin upn
Review Results
The Script will give you a new commandline when complete. From here, you can pop back over to your Teams channel and you should see the alert messages in your feed
Create Scheduled Task
Now all we have to do is use Task scheduler to run the command at certain intervals. You can set this to once a day, every 30 min, or whatever you feel is best. You will want to save a new file name for each customer so we capture the different AppIDs across tenants
