!!! This article is based on an API endpoint that is now being deprecated !!!
Please check the post below for more information.
https://developer.microsoft.com/en-us/office/blogs/deprecatation-of-the-identityriskevents-api/
One of the security features of Azure Active Directory is the detection of risky sign-ins based on certain event types. You can see these events in the Azure AD portal under Security section and Risky Sign-ins.
If you can check these risk events from the portal, it might not be something that you do regularly and it seems like only Azure AD Premium P2 is offering notification capabilities to users and admins (part of Azure Active Directory Identity Protection).
So the idea is to use the Microsoft Graph API and a PowerShell script to retrieve those risk events and send an email report on a daily basis. And the script will be run from Azure Functions, but you could have it as a schedule task on one of your own Windows machines.
To do this, first we need to create an app in Azure AD and grant it the necessary access to MS Graph API. This is explained in the official documentation along with a sample PowerShell script.
As the process on how to create the app and grant permission is well explained in this article, I will not get into the details here again. But as our PowerShell script will use the Graph API to send email, we need to also grant the access to “Send mail as any user”.
You might not be too comfortable with having granting such permission to an app, in that case you could find another way to send email notification. It could simply bee with Send-MailMessage cmdlet and using your own SMTP server, however if you run the script from Azure Function, you need to be sure to be able to access this SMTP server.
For the Azure Function, you should go to the Azure portal, click create a resource, then search for “function”, select Function App and click create.
Enter an app name (should be unique within Azure), and you can make sure to select the correct subscription and location.
Once the resource created, go to your Function and create a new one and click on “create your own custom function”.
Then enable experimental support and select PowerShell with a Timer trigger.
In this example we set the cron expression for 6AM every day, but you can adjust that.
Once the Function created just copy and paste the code from the following gist.
And you also need to set your environment variables as below in the application settings.
If you need to change the time trigger, click Integrate below your Function name.
You might have noticed that ipinfo.io is also used to retrieve info on the IP, but the risky sign-ins events are already giving some info on the IP so it’s not absolutely necessary but I thought it might be good to have a third party check on this.
You could modify this script if you want change anything like the email subject and body, but also improve things like error handling and output / log.
It might be a good thing to have a second function that runs more frequently and which notifies the users with risk events.
Also I was thinking to add some capability to close directly the events from the email notification, but the Graph API is only offering Read access for now. About that, my first idea was to use the Identity Protection API directly but it doesn’t seem like we have a way to get a valid token for it, and using the token from the XHR request is probably not recommended.
Lastly, if you don’t really have an use for such report, you can still take out of this article and script some useful patterns that can be re-used in different use cases:
- Register an app in Azure AD
- Grant API access and permissions
- Create an Azure Function with a PowerShell and environment variables
- Sign-in as an app and retrieve the access token with PowerShell
- Make GET and POST REST API queries with PowerShell
