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.<\/p>\n
Today we use enumerated types to represent the riskType<\/strong> property in both the riskDetections API<\/strong> and riskyUserHistoryItemAPI<\/strong> (in preview). We also use enumerated types for the riskEventTypes<\/strong> property in the signIns API <\/strong>(also in preview).\u00a0 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.\u00a0 To that end:<\/p>\n We have introduced a new riskEventType<\/strong> (string) property to the riskDetections API<\/strong> and riskyUserHistoryItemAPI<\/strong> and will be retiring the current riskType<\/strong> (enum) property on September 9th<\/sup>, 2020.<\/p>\n We have introduced a new riskEventsTypes_v2 (string)<\/strong> property to the signIns API<\/strong> and will be retiring the current riskEventTypes (enum)<\/strong> property on September 9th<\/sup>, 2020.<\/p>\n Note that at an appropriate future date we plan to re-introduce riskEventTypes<\/strong> as a string typed property in the signIns API <\/strong>and will provide the community with timely updates.<\/p>\n Please update any existing processes or integrations that use either of these APIs to use the new riskEventType<\/strong> or riskEventTypes_v2<\/strong> 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.<\/p>\n The riskDetection<\/strong> APIs<\/strong> are still in preview (beta). However, if you are using the signIns API<\/strong>, you may need to update queries on either the preview (beta) or production (v1.0) endpoint.<\/p>\n Example 1 (riskDetections)<\/strong><\/p>\n Old query:<\/p>\n GET https:\/\/graph.microsoft.com\/beta\/riskDetections?$filter=riskType eq ‘unfamiliarFeatures’<\/p>\n New query:<\/p>\n GET https:\/\/graph.microsoft.com\/beta\/riskDetections?$filter=riskEventType eq ‘unfamiliarFeatures’ or riskLevel eq ‘medium’<\/p>\n Example 2 (signIns)<\/strong><\/p>\n Old query:<\/p>\n GET https:\/\/graph.microsoft.com\/beta\/auditLogs\/signIns?$filter=riskEventTypes eq ‘unfamiliarFeatures’<\/p>\n New query:<\/p>\n GET https:\/\/graph.microsoft.com\/beta\/auditLogs\/signIns?$filter=riskEventTypes_v2 eq ‘unfamiliarFeatures’<\/p>\n 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<\/sup>, 2020.<\/p>\n 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.<\/p>\n Example <\/strong><\/p>\n Old query:<\/p>\n GET https:\/\/graph.microsoft.com\/beta\/riskDetections<\/p>\n New query:<\/p>\n GET https:\/\/graph.microsoft.com\/beta\/identityProtection\/riskDetections<\/p>\n riskEventTypes_v2<\/p>\n<\/td>\n Path to transition to <\/strong><\/p>\n<\/td>\n <\/p>\n 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.<\/p>\nWhat action do I need to take?<\/h4>\n
Introducing a new \/identityProtection segment in preview<\/h3>\n
What action do I need to take?<\/h4>\n
Summary of changes<\/h3>\n
Property Changes<\/h4>\n
\n\n
\n API<\/strong><\/td>\n Version<\/strong><\/td>\n Old Property (enum)<\/strong><\/td>\n New <\/strong>(string)<\/strong><\/td>\n Retirement date<\/strong><\/td>\n<\/tr>\n \n riskDetection<\/td>\n beta<\/td>\n riskType<\/td>\n riskEventType<\/td>\n 9\/9\/2020<\/strong><\/td>\n<\/tr>\n \n riskyUsers (userRiskHistoryItem)<\/td>\n beta<\/td>\n riskType<\/td>\n riskEventType<\/td>\n 9\/9\/2020<\/strong><\/td>\n<\/tr>\n \n signIns<\/td>\n beta<\/td>\n riskEventTypes<\/td>\n \n 9\/9\/2020<\/strong><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n Path Changes<\/h4>\n
\n\n
\n API<\/strong><\/td>\n Version<\/strong><\/td>\n Old Path<\/strong><\/td>\n \n Old path retirement date<\/strong><\/td>\n<\/tr>\n \n riskDetection<\/td>\n beta<\/td>\n ~\/riskDetections<\/td>\n ~\/identityProtection\/riskDetections<\/td>\n 9\/9\/2020<\/strong><\/td>\n<\/tr>\n \n riskyUsers<\/td>\n beta<\/td>\n ~\/riskyUsers<\/td>\n ~\/identityProtection\/riskyUsers<\/td>\n 9\/9\/2020<\/strong><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n