Edit

Share via

How to use additional context in Microsoft Authenticator notifications - Authentication methods policy

  • Article

This topic covers how to improve the security of user sign-in by adding the application name and geographic location of the sign-in to Microsoft Authenticator passwordless and push notifications.

Prerequisites

  • Your organization needs to enable Microsoft Authenticator passwordless and push notifications for some users or groups by using the new Authentication methods policy. You can edit the Authentication methods policy by using the Microsoft Entra admin center or Microsoft Graph API.

    Note

    The policy schema for Microsoft Graph APIs has been improved. The older policy schema is now deprecated. Make sure you use the new schema to help prevent errors.

  • Additional context can be targeted to only a single group, which can be dynamic or nested. On-premises synchronized security groups and cloud-only security groups are supported for the Authentication method policy.

Passwordless phone sign-in and multifactor authentication

When a user receives a passwordless phone sign-in or MFA push notification in Microsoft Authenticator, they'll see the name of the application that requests the approval and the location based on the IP address where the sign-in originated from.

Screenshot of additional context in the MFA push notification.

The additional context can be combined with number matching to further improve sign-in security.

Screenshot of additional context with number matching in the MFA push notification.

Policy schema changes

You can enable and disable application name and geographic location separately. Under featureSettings, you can use the following name mapping for each feature:

  • Application name: displayAppInformationRequiredState
  • Geographic location: displayLocationInformationRequiredState

Note

Make sure you use the new policy schema for Microsoft Graph APIs. In Graph Explorer, you'll need to consent to the Policy.Read.All and Policy.ReadWrite.AuthenticationMethod permissions.

Identify your single target group for each of the features. Then use the following API endpoint to change the displayAppInformationRequiredState or displayLocationInformationRequiredState properties under featureSettings to enabled and include or exclude the groups you want:

GET https://graph.microsoft.com/v1.0/authenticationMethodsPolicy/authenticationMethodConfigurations/MicrosoftAuthenticator

For more information, see microsoftAuthenticatorAuthenticationMethodConfiguration resource type.

Example of how to enable additional context for all users

In featureSettings, change displayAppInformationRequiredState and displayLocationInformationRequiredState from default to enabled.

The value of Authentication Mode can be either any or push, depending on whether or not you also want to enable passwordless phone sign-in. In these examples, we'll use any, but if you don't want to allow passwordless, use push.

You might need to PATCH the entire schema to prevent overwriting any previous configuration. In that case, do a GET first, update only the relevant fields, and then PATCH. The following example shows how to update displayAppInformationRequiredState and displayLocationInformationRequiredState under featureSettings.

Only users who are enabled for Microsoft Authenticator under Microsoft Authenticator’s includeTargets will see the application name or geographic location. Users who aren't enabled for Microsoft Authenticator won't see these features.

//Retrieve your existing policy via a GET. 
//Leverage the Response body to create the Request body section. Then update the Request body similar to the Request body as shown below.
//Change the Query to PATCH and Run query
 
{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",
    "@odata.type": "#microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration",
    "id": "MicrosoftAuthenticator",
    "state": "enabled",
    "featureSettings": {
        "displayAppInformationRequiredState": {
            "state": "enabled",
            "includeTarget": {
                "targetType": "group",
                "id": "all_users"
            },
            "excludeTarget": {
                "targetType": "group",
                "id": "00000000-0000-0000-0000-000000000000"
            }
        },
        "displayLocationInformationRequiredState": {
            "state": "enabled",
            "includeTarget": {
                "targetType": "group",
                "id": "all_users"
            },
            "excludeTarget": {
                "targetType": "group",
                "id": "00000000-0000-0000-0000-000000000000"
            }
        }
    },
    "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",
    "includeTargets": [
        {
            "targetType": "group",
            "id": "all_users",
            "isRegistrationRequired": false,
            "authenticationMode": "any",
        }
    ]
}

Example of how to enable application name and geographic location for separate groups

In featureSettings, change displayAppInformationRequiredState and displayLocationInformationRequiredState from default to enabled. Inside the includeTarget for each featureSetting, change the id from all_users to the ObjectID of the group from the Microsoft Entra admin center.

You need to PATCH the entire schema to prevent overwriting any previous configuration. We recommend that you do a GET first, and then update only the relevant fields and then PATCH. The following example shows an update to displayAppInformationRequiredState and displayLocationInformationRequiredState under featureSettings.

Only users who are enabled for Microsoft Authenticator under Microsoft Authenticator’s includeTargets will see the application name or geographic location. Users who aren't enabled for Microsoft Authenticator won't see these features.

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",
    "@odata.type": "#microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration",
    "id": "MicrosoftAuthenticator",
    "state": "enabled",
    "featureSettings": {
        "displayAppInformationRequiredState": {
            "state": "enabled",
            "includeTarget": {
                "targetType": "group",
                "id": "44561710-f0cb-4ac9-ab9c-e6c394370823"
            },
            "excludeTarget": {
                "targetType": "group",
                "id": "00000000-0000-0000-0000-000000000000"
            }
        },
        "displayLocationInformationRequiredState": {
            "state": "enabled",
            "includeTarget": {
                "targetType": "group",
                "id": "a229e768-961a-4401-aadb-11d836885c11"
            },
            "excludeTarget": {
                "targetType": "group",
                "id": "00000000-0000-0000-0000-000000000000"
            }
        }
    },
    "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",
    "includeTargets": [
        {
            "targetType": "group",
            "id": "all_users",
            "isRegistrationRequired": false,
            "authenticationMode": "any",
        }
    ]
}

To verify, run GET again and verify the ObjectID:

GET https://graph.microsoft.com/v1.0/authenticationMethodsPolicy/authenticationMethodConfigurations/MicrosoftAuthenticator

Example of how to disable application name and only enable geographic location

In featureSettings, change the state of displayAppInformationRequiredState to default or disabled and displayLocationInformationRequiredState to enabled. Inside the includeTarget for each featureSetting, change the id from all_users to the ObjectID of the group from the Microsoft Entra admin center.

You need to PATCH the entire schema to prevent overwriting any previous configuration. We recommend that you do a GET first, and then update only the relevant fields and then PATCH. The following example shows an update to displayAppInformationRequiredState and displayLocationInformationRequiredState under featureSettings.

Only users who are enabled for Microsoft Authenticator under Microsoft Authenticator’s includeTargets will see the application name or geographic location. Users who aren't enabled for Microsoft Authenticator won't see these features.

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",
    "@odata.type": "#microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration",
    "id": "MicrosoftAuthenticator",
    "state": "enabled",
    "featureSettings": {
        "displayAppInformationRequiredState": {
            "state": "disabled",
            "includeTarget": {
                "targetType": "group",
                "id": "44561710-f0cb-4ac9-ab9c-e6c394370823"
            },
            "excludeTarget": {
                "targetType": "group",
                "id": "00000000-0000-0000-0000-000000000000"
            }
        },
        "displayLocationInformationRequiredState": {
            "state": "enabled",
            "includeTarget": {
                "targetType": "group",
                "id": "a229e768-961a-4401-aadb-11d836885c11"
            },
            "excludeTarget": {
                "targetType": "group",
                "id": "00000000-0000-0000-0000-000000000000"
            }
        }
    },
    "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",
    "includeTargets": [
        {
            "targetType": "group",
            "id": "all_users",
            "isRegistrationRequired": false,
            "authenticationMode": "any",
        }
    ]
}

Example of how to exclude a group from application name and geographic location

In featureSettings, change the states of displayAppInformationRequiredState and displayLocationInformationRequiredState from default to enabled. Inside the includeTarget for each featureSetting, change the id from all_users to the ObjectID of the group from the Microsoft Entra admin center.

In addition, for each of the features, you'll change the id of the excludeTarget to the ObjectID of the group from the Microsoft Entra admin center. This change excludes that group from seeing application name or geographic location.

You need to PATCH the entire schema to prevent overwriting any previous configuration. We recommend that you do a GET first, and then update only the relevant fields and then PATCH. The following example shows an update to displayAppInformationRequiredState and displayLocationInformationRequiredState under featureSettings.

Only users who are enabled for Microsoft Authenticator under Microsoft Authenticator’s includeTargets will see the application name or geographic location. Users who aren't enabled for Microsoft Authenticator won't see these features.

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",
    "@odata.type": "#microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration",
    "id": "MicrosoftAuthenticator",
    "state": "enabled",
    "featureSettings": {
        "displayAppInformationRequiredState": {
            "state": "enabled",
            "includeTarget": {
                "targetType": "group",
                "id": "44561710-f0cb-4ac9-ab9c-e6c394370823"
            },
            "excludeTarget": {
                "targetType": "group",
                "id": "5af8a0da-5420-4d69-bf3c-8b129f3449ce"
            }
        },
        "displayLocationInformationRequiredState": {
            "state": "enabled",
            "includeTarget": {
                "targetType": "group",
                "id": "a229e768-961a-4401-aadb-11d836885c11"
            },
            "excludeTarget": {
                "targetType": "group",
                "id": "b6bab067-5f28-4dac-ab30-7169311d69e8"
            }
        }
    },
    "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",
    "includeTargets": [
        {
            "targetType": "group",
            "id": "all_users",
            "isRegistrationRequired": false,
            "authenticationMode": "any",
        }
    ]
}

Example of removing the excluded group

In featureSettings, change the states of displayAppInformationRequiredState from default to enabled. You need to change the id of the excludeTarget to 00000000-0000-0000-0000-000000000000.

You need to PATCH the entire schema to prevent overwriting any previous configuration. We recommend that you do a GET first, and then update only the relevant fields and then PATCH. The following example shows an update to displayAppInformationRequiredState and displayLocationInformationRequiredState under featureSettings.

Only users who are enabled for Microsoft Authenticator under Microsoft Authenticator’s includeTargets will see the application name or geographic location. Users who aren't enabled for Microsoft Authenticator won't see these features.

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",
    "@odata.type": "#microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration",
    "id": "MicrosoftAuthenticator",
    "state": "enabled",
    "featureSettings": {
        " displayAppInformationRequiredState ": {
            "state": "enabled",
            "includeTarget": {
                "targetType": "group",
                "id": "1ca44590-e896-4dbe-98ed-b140b1e7a53a"
            },
            "excludeTarget": {
                "targetType": "group",
                "id": " 00000000-0000-0000-0000-000000000000"
            }
        }
    },
    "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",
    "includeTargets": [
        {
            "targetType": "group",
            "id": "all_users",
            "isRegistrationRequired": false,
            "authenticationMode": "any"
        }
    ]
}

Turn off additional context

To turn off additional context, you'll need to PATCH displayAppInformationRequiredState and displayLocationInformationRequiredState from enabled to disabled/default. You can also turn off just one of the features.

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodConfigurations/$entity",
    "@odata.type": "#microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration",
    "id": "MicrosoftAuthenticator",
    "state": "enabled",
    "featureSettings": {
        "displayAppInformationRequiredState": {
            "state": "disabled",
            "includeTarget": {
                "targetType": "group",
                "id": "44561710-f0cb-4ac9-ab9c-e6c394370823"
            },
            "excludeTarget": {
                "targetType": "group",
                "id": "00000000-0000-0000-0000-000000000000"
            }
        },
        "displayLocationInformationRequiredState": {
            "state": "disabled",
            "includeTarget": {
                "targetType": "group",
                "id": "a229e768-961a-4401-aadb-11d836885c11"
            },
            "excludeTarget": {
                "targetType": "group",
                "id": "00000000-0000-0000-0000-000000000000"
            }
        }
    },
    "includeTargets@odata.context": "https://graph.microsoft.com/v1.0/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",
    "includeTargets": [
        {
            "targetType": "group",
            "id": "all_users",
            "isRegistrationRequired": false,
            "authenticationMode": "any",
        }
    ]
}

Enable additional context in the Microsoft Entra admin center

To enable application name or geographic location in the Microsoft Entra admin center, complete the following steps:

  1. Sign in to the Microsoft Entra admin center as at least an Authentication Policy Administrator.

  2. Browse to Protection > Authentication methods > Microsoft Authenticator.

  3. On the Basics tab, click Yes and All users to enable the policy for everyone, and change Authentication mode to Any.

    Only users who are enabled for Microsoft Authenticator here can be included in the policy to show the application name or geographic location of the sign-in, or excluded from it. Users who aren't enabled for Microsoft Authenticator can't see application name or geographic location.

    Screenshot of how to enable Microsoft Authenticator settings for Any authentication mode.

  4. On the Configure tab, for Show application name in push and passwordless notifications, change Status to Enabled, choose who to include or exclude from the policy, and click Save.

    Screenshot of how to enable application name.

    Then do the same for Show geographic location in push and passwordless notifications.

    Screenshot of how to enable geographic location.

    You can configure application name and geographic location separately. For example, the following policy enables application name and geographic location for all users but excludes the Operations group from seeing geographic location.

    Screenshot of how to enable application name and geographic location separately.

Known issues

  • Additional context isn't supported for Network Policy Server (NPS) or Active Directory Federation Services (AD FS).

  • Users can modify the location reported by iOS and Android devices. As a result, Microsoft Authenticator is updating its security baseline for Location Based Access Control (LBAC) Conditional Access policies. Authenticator will deny authentications where the user may be using a different location than the actual GPS location of the mobile device where Authenticator installed.

    In the November 2023 release of Authenticator, users who modify the location of their device will see a denial message in Authenticator when doing an LBAC authentication. Beginning January 2024, any users that run older Authenticator versions will be blocked from LBAC authentication with a modified location:

    • Authenticator version 6.2309.6329 or earlier on Android
    • Authenticator version 6.7.16 or earlier on iOS

    To find which users run older versions of Authenticator, use Microsoft Graph APIs.

Next steps

Authentication methods in Microsoft Entra ID - Microsoft Authenticator app