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.

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
    }
}