Update: Dec 20 2018. See this post that details the changes to the Azure AD Reports and Events Rest API.
Hybrid Reporting is a great little feature of Microsoft Identity Manager. A small agent installed on the MIM Sync Server will send reporting data to Azure for MIM SSPR and MIM Group activities. See how to install and configure it here.
But what if you want to get the reporting data without going to the Azure Portal and looking at the Audit Reports ? Enter the Azure AD Reports and Events REST API that is currently in preview. It took me a couple of cracks and getting this working, because documentation is a little vague especially when accessing it via PowerShell and oAuth2. So I’ve written it up and hope it helps for anyone else looking to go down this route.
Gotchas
Accessing the Reports via the API has a couple of caveats that I had to work through:
- Having the correct permissions to access the report data. Pretty much everything you read tells you that you need to be a Global Admin. Once I had my oAuth tokens I messed around a little and a was able to also get the following from back from the API when purposely using an identity that didn’t have the right permissions. The key piece is “Api request is not from global admin or security admin or security reader role”. I authorized the WebApp using an account that is in the Security Reader Role, and can successfully access the report data.
- Reading the documentation here on MSDN I incorrectly assumed each category was the report name. Only when I called the “https://graph.windows.net//$metadata?api-version=beta” and looked at the list of reports I noticed each report was plural.The three that I wanted to access (and report on) are obviously the MIM Hybrid Reports;
"Name": "mimSsgmGroupActivityEvents", "Name": "mimSsprActivityEvents", "Name": "mimSsprRegistrationActivityEvents",
Here is the full list of Reports available as of 24 May 2017.
{
"Name": "b2cAuthenticationCountSummary",
"LicenseRequired": "False"
}
{
"Name": "b2cMfaRequestCount",
"LicenseRequired": "False"
}
{
"Name": "b2cMfaRequestEvent",
"LicenseRequired": "False"
}
{
"Name": "b2cAuthenticationEvent",
"LicenseRequired": "False"
}
{
"Name": "b2cAuthenticationCount",
"LicenseRequired": "False"
}
{
"Name": "b2cMfaRequestCountSummary",
"LicenseRequired": "False"
}
{
"Name": "tenantUserCount",
"LicenseRequired": "False"
}
{
"Name": "applicationUsageDetailEvents",
"LicenseRequired": "False"
}
{
"Name": "applicationUsageSummaryEvents",
"LicenseRequired": "True"
}
{
"Name": "b2cUserJourneySummaryEvents",
"LicenseRequired": "False"
}
{
"Name": "b2cUserJourneyEvents",
"LicenseRequired": "False"
}
{
"Name": "cloudAppDiscoveryEvents",
"LicenseRequired": "False"
}
{
"Name": "mimSsgmGroupActivityEvents",
"LicenseRequired": "True"
}
{
"Name": "ssgmGroupActivityEvents",
"LicenseRequired": "True"
}
{
"Name": "mimSsprActivityEvents",
"LicenseRequired": "True"
}
{
"Name": "ssprActivityEvents",
"LicenseRequired": "True"
}
{
"Name": "mimSsprRegistrationActivityEvents",
"LicenseRequired": "True"
}
{
"Name": "ssprRegistrationActivityEvents",
"LicenseRequired": "True"
}
{
"Name": "threatenedCredentials",
"LicenseRequired": "False"
}
{
"Name": "compromisedCredentials",
"LicenseRequired": "False"
}
{
"Name": "auditEvents",
"LicenseRequired": "False"
}
{
"Name": "accountProvisioningEvents",
"LicenseRequired": "False"
}
{
"Name": "signInsFromUnknownSourcesEvents",
"LicenseRequired": "False"
}
{
"Name": "signInsFromIPAddressesWithSuspiciousActivityEvents",
"LicenseRequired": "True"
}
{
"Name": "signInsFromMultipleGeographiesEvents",
"LicenseRequired": "False"
}
{
"Name": "signInsFromPossiblyInfectedDevicesEvents",
"LicenseRequired": "True"
}
{
"Name": "irregularSignInActivityEvents",
"LicenseRequired": "True"
}
{
"Name": "allUsersWithAnomalousSignInActivityEvents",
"LicenseRequired": "True"
}
{
"Name": "signInsAfterMultipleFailuresEvents",
"LicenseRequired": "False"
}
{
"Name": "applicationUsageSummary",
"LicenseRequired": "True"
}
{
"Name": "userActivitySummary",
"LicenseRequired": "False"
}
{
"Name": "groupActivitySummary",
"LicenseRequired": "True"
}
How to Access the Reporting API using PowerShell
What you need to do is;
- Register a WebApp
- Assign a reply to URL of https://localhost
- Assign it Read.Directory permissions
- Get an oAuth2 Authentication Code using an account that is either Global Admin or in the Security Admin or Security Reader Azure Roles
- Use your Bearer and Refresh tokens to query for the reports you’re interested in
Register your WebApp
In the Azure Portal create a new Web app/API app and assign it https://localhost as the Reply URL. Record the Application ID for use in the PowerShell script.
Assign the Read Directory data permission as shown below
Obtain a key from the Keys option on your new Web App. Record it for use in the PowerShell script.
Generate an Authentication Code, get a Bearer and Refresh Token
Update the following script, changing Lines 5 & 6 for the ApplicationID/ClientId and Client Secret for the WebApp you created above.
Run the script and you will be prompted to authenticate. Use an account in the tenant where you created the Web App that is a Global Admin or in the Security Admin or Security Reader Azure Roles. You will need to change the location where you want the refresh.token stored (line 18).
If you’ve done everything correctly you have authenticated, got an AuthCode which was then used to get your Authorization Tokens. The value of the $Authorization variable should look similar to this;
Now you can use the Refresh token to generate new Authorization Tokens when they time out, simply by calling the Get-NewTokens function included in the script above.
Querying the Reporting API
Now that you have the necessary prerequisites sorted you can query the Reporting API.
Here are a couple of simple queries to return some data to get you started. Update the script for the tenant name of your AzureAD. With the $Authorization values from the script above you can get data for the MIM Hybrid Reports.