Manage application authenticationBehaviors

The authenticationBehaviors property of the application object allows you to configure breaking change behaviors related to token issuance. Applications can adopt new breaking changes by enabling a behavior or continue using pre-existing behavior by disabling it.

The following behaviors are configurable:

Note

The authenticationBehaviors property of the application object is currently available in beta only.

Read the authenticationBehaviors setting for an application

The authenticationBehaviors property is returned only on $select requests.

To read the property and other specified properties of all apps in the tenant, run the following sample request. The request returns a 200 OK response code and a JSON representation of the application object that shows only the selected properties.

GET https://graph.microsoft.com/beta/applications?$select=id,displayName,appId,authenticationBehaviors

To read only the authenticationBehaviors property for a single app, run the following sample request.

GET https://graph.microsoft.com/beta/applications/03ef14b0-ca33-4840-8f4f-d6e91916010e/authenticationBehaviors

You can also use the appId property as follows:

GET https://graph.microsoft.com/beta/applications(appId='37bf1fd4-78b0-4fea-ac2d-6c82829e9365')/authenticationBehaviors

Prevent the issuance of email claims with unverified domain owners

As described in the Microsoft security advisory Potential Risk of Privilege Escalation in Microsoft Entra Applications, apps should never use the email claim for authorization purposes. If your application uses the email claim for authorization or primary user identification purposes, it's subject to account and privilege escalation attacks. This risk of unauthorized access is especially identified in the following scenarios:

  • When the mail attribute of the user object contains an email address with an unverified domain owner
  • For multitenant apps where a user from one tenant could escalate their privileges to access resources from another tenant through modification of their mail attribute

For more information about identifying these cases in your tenant, see Migrate away from using email claims for user identification or authorization.

Today, the default behavior is to remove email addresses with unverified domain owners in claims, except for single-tenant apps and for multitenant apps with previous sign-in activity with unverified emails. If your app falls into either of these exceptions and you wish to remove unverified email addresses, set the removeUnverifiedEmailClaim property of authenticationBehaviors to true as illustrated in the following examples. The request returns a 204 No Content response code.

Remove email addresses with unverified domain owners from claims

Option 1

This pattern for specifying the property in the request URL allows you to update only the specified property in the request.

PATCH https://graph.microsoft.com/beta/applications/03ef14b0-ca33-4840-8f4f-d6e91916010e/authenticationBehaviors
Content-Type: application/json

{
    "removeUnverifiedEmailClaim": true
}

Option 2

This pattern for specifying the property in the request body allows you to update other peer properties in the same request.

PATCH https://graph.microsoft.com/beta/applications/03ef14b0-ca33-4840-8f4f-d6e91916010e
Content-Type: application/json

{
    "authenticationBehaviors": {
        "removeUnverifiedEmailClaim": true
    }
}

Accept email addresses with unverified domain owners in claims

Option 1

PATCH https://graph.microsoft.com/beta/applications/03ef14b0-ca33-4840-8f4f-d6e91916010e/authenticationBehaviors
Content-Type: application/json

{
    "removeUnverifiedEmailClaim": false
}

Option 2

PATCH https://graph.microsoft.com/beta/applications/03ef14b0-ca33-4840-8f4f-d6e91916010e
Content-Type: application/json

{
    "authenticationBehaviors": {
        "removeUnverifiedEmailClaim": false
    }
}

Restore the default behavior

Option 1

PATCH https://graph.microsoft.com/beta/applications/03ef14b0-ca33-4840-8f4f-d6e91916010e/authenticationBehaviors
Content-Type: application/json

{
    "removeUnverifiedEmailClaim": null
}

Option 2

PATCH https://graph.microsoft.com/beta/applications/03ef14b0-ca33-4840-8f4f-d6e91916010e/
Content-Type: application/json

{
    "authenticationBehaviors": {
        "removeUnverifiedEmailClaim": null
    }
}

Allow extended Azure AD Graph access until June 30, 2025

By default, applications created after August 31, 2024 will receive a 403 Unauthorized error when making requests to Azure AD Graph APIs, unless they're configured to allow extended Azure AD Graph access. Additionally, existing apps created before August 31, 2024 and making requests to Azure AD Graph APIs must be configured to allow extended Azure AD Graph access by February 1, 2025. This extended access is available only until June 30, 2025, when Azure AD Graph is fully retired. After this date, all apps will receive a 403 Unauthorized error when making requests to Azure AD Graph APIs, regardless of their extended access configuration. For more information, see June 2024 update on Azure AD Graph API retirement.

The following request shows how to update an app to enable extended Azure AD Graph access. The request returns a 204 No Content response code.

Option 1

PATCH https://graph.microsoft.com/beta/applications/5c142e6f-0bd3-4e58-b510-8a106704f44f/authenticationBehaviors
Content-Type: application/json

{
    "blockAzureADGraphAccess": false
}

Option 2

PATCH https://graph.microsoft.com/beta/applications/5c142e6f-0bd3-4e58-b510-8a106704f44f
Content-Type: application/json

{
    "authenticationBehaviors": {
        "blockAzureADGraphAccess": false
    }
}