Microsoft Entra ID

Authentication & Authorization

Credentials

• Microsoft Entra ID (previously called Azure Active Directory) connects via OAuth 2.0 with Authorization Code Grant Flow.
• DataGrail owns a Microsoft Entra ID OAuth 2.0 App that provides the credentials to authenticate customers allowing the integration to connect by simply logging into their Azure Active Directory account with their admin credentials and accepting to install the app. See Microsoft Entra ID Connection Instructions.
• DataGrail uses Refresh Token Flow to periodically update Access Token after it expires to keep the connection alive.

Scopes

Microsoft Entra ID API requires specific scopes that need to be approved by you in order to grant DataGrail read on certain objects necessary to complete system detection:

• offline_access
• Application.Read.All
• User.Read.All

Endpoints Utilized

• Request authorization:
  • GET https:​///login.microsoftonline.com/common/oauth2/v2.0/authorize
• Get and refresh access token:
  • POST https​/://login.microsoftonline.com/common/oauth2/v2.0/token

Version

DataGrail Microsoft Entra ID integration currently supports Microsoft Graph REST API version 1.0.

Limits

Microsoft Entra ID rate-limit policy prevents API usage spikes on a per subscription basis by limiting the call rate to a specified number per a specified time period. When DataGrail exceed a rate limit, the API request will fail and return a HTTP 429 status code.

DataGrail processes API responses with HTTP 429 status to interrupt requests, waiting and retrying (using an exponential backoff strategy).

System Detection

DataGrail reads service principals (applications) to detect new systems added in your Microsoft Entra ID instance and identify application owners emails.

For an system detection requests, DataGrail will take the following actions:

• Retrieve a list of servicePrincipal objects to build a list of detected systems (applications).
• List appRoleAssignments granted to each of detected service principals (applications) do define their owners (by application ID).
• Retrieve the properties of the user to define application owners' emails (by user ID).

Endpoints Utilized

• GET https:​//graph.microsoft.com/v1.0/servicePrincipals
• GET https:​//graph.microsoft.com/v1.0/servicePrincipals/{APP_ID}/appRoleAssignedTo
• GET https:​//graph.microsoft.com/v1.0/users/{USER_ID}

Access

DataGrail supports only the Direct Contact Access workflow for Microsoft Entra ID.

Deletion

DataGrail supports only the Direct Contact Deletion workflow for Microsoft Entra ID.