title | description | author | ms.author | ms.reviewer | ms.topic | ms.localizationpriority | ms.custom | ms.subservice | ms.date |
---|---|---|---|---|---|---|---|---|---|
Manage application authenticationBehaviors |
Manage application authentication behaviors to adopt new breaking changes. |
FaithOmbongi |
ombongifaith |
medbhargava |
how-to |
high |
scenarios:getting-started |
entra-applications |
06/10/2024 |
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.
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
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
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
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
You can also use the appId property as follows:
GET https://graph.microsoft.com/beta/applications(appId='37bf1fd4-78b0-4fea-ac2d-6c82829e9365')/authenticationBehaviors
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.
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
}
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
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
}
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
PATCH https://graph.microsoft.com/beta/applications/03ef14b0-ca33-4840-8f4f-d6e91916010e/authenticationBehaviors
Content-Type: application/json
{
"removeUnverifiedEmailClaim": false
}
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
PATCH https://graph.microsoft.com/beta/applications/03ef14b0-ca33-4840-8f4f-d6e91916010e
Content-Type: application/json
{
"authenticationBehaviors": {
"removeUnverifiedEmailClaim": false
}
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
PATCH https://graph.microsoft.com/beta/applications/03ef14b0-ca33-4840-8f4f-d6e91916010e/authenticationBehaviors
Content-Type: application/json
{
"removeUnverifiedEmailClaim": null
}
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
PATCH https://graph.microsoft.com/beta/applications/03ef14b0-ca33-4840-8f4f-d6e91916010e/
Content-Type: application/json
{
"authenticationBehaviors": {
"removeUnverifiedEmailClaim": null
}
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]