Changes to risk event properties and Identity Protection APIs on Microsoft Graph
Hi folks! To make the user and event risk information presented by our signIns and Identity Protection APIs on Microsoft Graph more intuitive, we are announcing a few significant changes, detailed in this blog post.
New risk event type and property changes
Today we use enumerated types to represent the riskType property in both the riskDetections API and riskyUserHistoryItemAPI (in preview). We also use enumerated types for the riskEventTypes property in the signIns API (also in preview). Going forward we will represent these properties as strings. This change will simplify the process of adding signals to our schema, but more importantly it will provide typing consistency across our API surface so that in the future, all new risk event types we add to the Identity Protection or Sign In logs will appear as strings. To that end:
We have introduced a new riskEventType (string) property to the riskDetections API and riskyUserHistoryItemAPI and will be retiring the current riskType (enum) property on September 9th, 2020.
We have introduced a new riskEventsTypes_v2 (string) property to the signIns API and will be retiring the current riskEventTypes (enum) property on September 9th, 2020.
Note that at an appropriate future date we plan to re-introduce riskEventTypes as a string typed property in the signIns API and will provide the community with timely updates.
What action do I need to take?
Please update any existing processes or integrations that use either of these APIs to use the new riskEventType or riskEventTypes_v2 properties. We will only add new risk event types to these new properties and risk detection type information will only show up under the new property names. If you have existing queries that filter on the old properties, they will fail once the properties are removed from the API schema.
The riskDetection APIs are still in preview (beta). However, if you are using the signIns API, you may need to update queries on either the preview (beta) or production (v1.0) endpoint.
Example 1 (riskDetections)
Old query:
GET https://graph.microsoft.com/beta/riskDetections?$filter=riskType eq ‘unfamiliarFeatures’
New query:
GET https://graph.microsoft.com/beta/riskDetections?$filter=riskEventType eq ‘unfamiliarFeatures’ or riskLevel eq ‘medium’
Example 2 (signIns)
Old query:
GET https://graph.microsoft.com/beta/auditLogs/signIns?$filter=riskEventTypes eq ‘unfamiliarFeatures’
New query:
GET https://graph.microsoft.com/beta/auditLogs/signIns?$filter=riskEventTypes_v2 eq ‘unfamiliarFeatures’
Introducing a new /identityProtection segment in preview
The Identity Protection APIs that are currently available in the beta endpoint are at the root level of Microsoft Graph, ~/riskDetections and ~/riskyUsers. To make these APIs more discoverable and clustered with Identity Protection, we are moving them under a new /identityProtection segment that will be introduced in beta on June 22nd, 2020.
What action do I need to take?
If you are currently using these APIs, you must move to the new path for these endpoints. Both paths, at the root level and under the /identityProtection segment, will work in parallel until September 9, 2020. Once the retirement date is passed, the old path at the root level will no longer return data.
Example
Old query:
GET https://graph.microsoft.com/beta/riskDetections
New query:
GET https://graph.microsoft.com/beta/identityProtection/riskDetections
Summary of changes
Property Changes
| API | Version | Old Property (enum) | New (string) | Retirement date |
| riskDetection | beta | riskType | riskEventType | 9/9/2020 |
| riskyUsers (userRiskHistoryItem) | beta | riskType | riskEventType | 9/9/2020 |
| signIns | beta | riskEventTypes |
riskEventTypes_v2 |
9/9/2020 |
Path Changes
| API | Version | Old Path |
Path to transition to |
Old path retirement date |
| riskDetection | beta | ~/riskDetections | ~/identityProtection/riskDetections | 9/9/2020 |
| riskyUsers | beta | ~/riskyUsers | ~/identityProtection/riskyUsers | 9/9/2020 |
Thank you in advance for transitioning to the new properties and segment to improve the navigability and consistency of our Microsoft Graph APIs. We are excited about these improvements to our APIs and extending the ability to developers to leverage the value of Azure AD Identity Protection detections.
If you aren’t yet using Azure AD Identity Protection, check it out here– it’s a powerful tool for protecting your identities!
-Sarah Handler and Ben Siler, on behalf of the Identity Protection and IAM teams
Light
Dark