In my latest blog, ‘Azure AD Identity Protection Integrations with Microsoft security solutions’ I covered how AADIP / IPC integrates with other security solutions and described data flows. Inspired by the research, I decided to write a short blog post about different APIs that provide IPC data to provide a better understanding of where the IPC data can be found.

Background

In the picture below, you can find IPC integrations and data flows underneath the hood. The APIs are not highlighted in the picture, more information about the APIs is found in the next chapter.

It’s important to know that AADIP alerts are found from multiple solutions and might cause confusion when investigating alerts or raw data. Depending on the configuration you can see AADIP detection alerts in the following solutions:

  • Azure AD Identity Protection
  • Microsoft 365 Defender
  • Microsoft Defender for Cloud Apps
  • Microsoft Sentinel
  • Azure Log Analytics (raw data)

The Available APIs

Azure AD Identity Protection (IPC) detections are found from several APIs. In this chapter, I describe the APIs with example queries that can be used to get IPC-related data.

Microsoft Security Graph Legacy API (v1.0 & Beta)

Microsoft Security Graph has v1.0 and Beta endpoints available. This API and its endpoints have been available for several years already.

Sample Queries

With the following commands, you can query alerts from both v1.0 & beta endpoints using the legacy API. 

$data = Invoke-RestMethod -Method Get -Uri "https://graph.microsoft.com/v1.0/security/alerts?$filter=vendorInformation/provider eq 'IPC'&$top=5" -ContentType "application/json" -Headers $h

$data = Invoke-RestMethod -Method Get -Uri "https://graph.microsoft.com/beta/security/alerts?$filter=vendorInformation/provider eq 'IPC'&$top=5" -ContentType "application/json" -Headers $h

New Beta API aka M365 Defender API

Microsoft announced a while ago a new beta API which is also known as M365 Defender API. Complete documentation – Microsoft Graph security API beta.

The main difference from the alerts point of view is the following:

Alerts (alerts_v2) endpoint: 

  • The Microsoft 365 Defender unified alerts API serves alerts from Microsoft 365 Defender, Microsoft Defender for Endpoint, Microsoft Defender for Office 365, Microsoft Defender for Identity, Microsoft Defender for Cloud Apps, and Microsoft Purview Data Loss Prevention (and any future new signals integrated into M365D).
    • Note: Sentinel is not included anymore as a provider
  • Integrating with this API will support the entire scope of Microsoft 365 Defender.
  • As part of the alerts schema, in addition to the alert severity, containing was added – this allows the SOC team to be aware of the overall severity of the incident when triaging an alert, so they can prioritize effectively.

The new alert schema expands and enriches supported evidence entities at parity and beyond with the native service Alert APIs. In the picture below you can find a comparison of the legacy & new Beta API schema for the IPC-generated detection alert.

Sample Query

With the following sample query, you can query all Azure AD Identity Protection detection alerts from the M365 Defender API. Note – the provider has changed from ‘IPC’ to ‘azureAdIdentityProtection’.

https://graph.microsoft.com/beta/security/alerts_v2?$filter=serviceSource eq 'azureAdIdentityProtection'

Azure AD Identity Protection (AADIP) APIs

The AADIP has two active endpoints at the time of writing. These are ‘riskDetections & ‘riskyUsers’ APIs. Below you can find samples for both APIs.

RiskDetections API

This API has information about risks detected in Azure AD. Below are a few examples for getting all risk detections or individual risk detection (alert) by provider id.

## Get risk all risk detections
GET https://graph.microsoft.com/beta/riskDetections
GET https://graph.microsoft.com/beta/identityProtection/riskDetections

##Get risk detection by ID
GET https://graph.microsoft.com/beta/identityProtection/riskDetections/95e5dfce563e36241b90b8b4727ef52d01708a9f222b8089fcd91e52d11ff5cb

Reference

RiskyUsers API

Represents Azure AD users who are at risk. Azure AD continually evaluates user risk based on various signals and machine learning. This API provides programmatic access to all at-risk users in your Azure AD.

You can get users from the following endpoints and also individuals by the user object id:

GET https://graph.microsoft.com/beta/riskyUsers

GET https://graph.microsoft.com/beta/identityProtection/riskyUsers

GET https://graph.microsoft.com/beta/identityProtection/riskyUsers/c2b6c2b9-dddc-acd0-2b39-d519d803dbc3

RiskyUsers API supports also the following actions

  • Dismiss a riskyUser
  • Confirm a riskyUser as compromised

ServicePrincipalRiskDetections

Represents information about detected at-risk service principals in an Azure AD tenant. Azure AD continually evaluates risks based on various signals and machine learning. This API provides programmatic access to all service principal risk detections in your Azure AD environment.

You can query all service principals risk detections with the following sample query:

GET /identityProtection/servicePrincipalRiskDetections

riskyServicePrincipal

Represents Azure AD service principals that are at risk. Azure AD continually evaluates service principal risk based on various signals and machine learning. This API provides programmatic access to all at-risk service principals in your Azure AD tenant.

RiskyServicePrincipal API supports also the following actions

  • List History
  • Confirm service principal compromised
  • Dismiss service principal risk

Sample queries for service principals:

GET /identityProtection/riskyServicePrincipals

GET /identityProtection/riskyServicePrincipals/{riskyServicePrincipalId}

GET /identityProtection/riskyServicePrincipals/{riskyServicePrincipalId}/history

POST /identityProtection/riskyServicePrincipals/confirmCompromised

POST /identityProtection/riskyServicePrincipals/dismiss

Resources

Azure AD Identity Protection API overview

AADIP Risk Detection API

AADIP Risky User API