|
| 1 | +--- |
| 2 | +title: Use additional context in multifactor authentication (MFA) notifications (Preview) - Azure Active Directory |
| 3 | +description: Learn how to use additional context in MFA notifications |
| 4 | +services: active-directory |
| 5 | +ms.service: active-directory |
| 6 | +ms.subservice: authentication |
| 7 | +ms.topic: conceptual |
| 8 | +ms.date: 11/16/2021 |
| 9 | + |
| 10 | +ms.author: justinha |
| 11 | +author: mjsantani |
| 12 | +manager: daveba |
| 13 | + |
| 14 | +ms.collection: M365-identity-device-management |
| 15 | + |
| 16 | +# Customer intent: As an identity administrator, I want to encourage users to use the Microsoft Authenticator app in Azure AD to improve and secure user sign-in events. |
| 17 | +--- |
| 18 | +# How to use additional context in multifactor authentication (MFA) notifications (Preview) - Authentication Methods Policy |
| 19 | + |
| 20 | +This topic covers how to improve the security of user sign-in by adding application location based on IP address in Microsoft Authenticator push notifications. |
| 21 | + |
| 22 | +## Prerequisites |
| 23 | + |
| 24 | +Your organization will need to enable Microsoft Authenticator push notifications for some users or groups using the new Authentication Methods Policy API. |
| 25 | + |
| 26 | +>[!NOTE] |
| 27 | +>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. |
| 28 | +
|
| 29 | +## Passwordless phone sign-in and multifactor authentication |
| 30 | + |
| 31 | +When a user receives a Passwordless phone sign-in or MFA push notification in the Microsoft Authenticator app, they'll see the name of the application that requests the approval and the app location based on its IP address. |
| 32 | + |
| 33 | + |
| 34 | + |
| 35 | +The additional context can be combined with [number matching](how-to-mfa-number-match.md) to further improve sign-in security. |
| 36 | + |
| 37 | + |
| 38 | + |
| 39 | +### Policy schema changes |
| 40 | + |
| 41 | +Identify a single target group for the schema configuration. Then use the following API endpoint to change the displayAppInformationRequiredState property to **enabled**: |
| 42 | + |
| 43 | +https://graph.microsoft.com/beta/authenticationMethodsPolicy/authenticationMethodConfigurations/MicrosoftAuthenticator |
| 44 | + |
| 45 | + |
| 46 | +#### MicrosoftAuthenticatorAuthenticationMethodConfiguration properties |
| 47 | + |
| 48 | +**PROPERTIES** |
| 49 | + |
| 50 | +| Property | Type | Description | |
| 51 | +|---------|------|-------------| |
| 52 | +| id | String | The authentication method policy identifier. | |
| 53 | +| state | authenticationMethodState | Possible values are: **enabled**<br>**disabled** | |
| 54 | + |
| 55 | +**RELATIONSHIPS** |
| 56 | + |
| 57 | +| Relationship | Type | Description | |
| 58 | +|--------------|------|-------------| |
| 59 | +| includeTargets | [microsoftAuthenticatorAuthenticationMethodTarget](/graph/api/resources/passwordlessmicrosoftauthenticatorauthenticationmethodtarget.md?view=graph-rest-beta) | |
| 60 | +| collection | A collection of users or groups who are enabled to use the authentication method. | |
| 61 | + |
| 62 | +#### MicrosoftAuthenticator includeTarget properties |
| 63 | + |
| 64 | +**PROPERTIES** |
| 65 | + |
| 66 | +| Property | Type | Description | |
| 67 | +|----------|------|-------------| |
| 68 | +| authenticationMode | String | Possible values are:<br>**any**: Both passwordless phone sign-in and traditional second factor notifications are allowed.<br>**deviceBasedPush**: Only passwordless phone sign-in notifications are allowed.<br>**push**: Only traditional second factor push notifications are allowed. | |
| 69 | +| id | String | Object ID of an Azure AD user or group. | |
| 70 | +| targetType | authenticationMethodTargetType | Possible values are: **user**, **group**.<br>You can only set one group or user for additional context. | |
| 71 | +| displayAppInformationRequiredState | advancedConfigState | Possible values are:<br>**enabled** explicitly enables the feature for the selected group.<br>**disabled** explicitly disables the feature for the selected group.<br>**default** allows Azure AD to manage whether the feature is enabled or not for the selected group. | |
| 72 | + |
| 73 | +>[!NOTE] |
| 74 | +>Additional context can only be enabled for a single group. |
| 75 | +
|
| 76 | +#### Example of how to enable additional context for all users |
| 77 | + |
| 78 | +Change the **displayAppInformationRequiredState** from **default** to **enabled**. |
| 79 | + |
| 80 | +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 do not want to allow passwordless, use **push**. |
| 81 | + |
| 82 | +You need to PATCH the entire includeTarget to prevent overwriting any previous configuration. In that case, do a GET first, update only the relevant fields, and then PATCH. The following example only shows the update to the **displayAppInformationRequiredState**. |
| 83 | + |
| 84 | +```json |
| 85 | +//Retrieve your existing policy via a GET. |
| 86 | +//Leverage the Response body to create the Request body section. Then update the Request body similar to the Request body as shown below. |
| 87 | +//Change the Query to PATCH and Run query |
| 88 | + |
| 89 | +{ |
| 90 | + "@odata.context": "https://graph.microsoft.com/beta/$metadata#authenticationMethodConfigurations/$entity", |
| 91 | + "@odata.type": "#microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration", |
| 92 | + "id": "MicrosoftAuthenticator", |
| 93 | + "state": "enabled", |
| 94 | + "[email protected]": "https://graph.microsoft.com/beta/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets", |
| 95 | + "includeTargets": [ |
| 96 | + { |
| 97 | + "targetType": "group", |
| 98 | + "id": "all_users", |
| 99 | + "authenticationMode": "any", |
| 100 | + "displayAppInformationRequiredState": "enabled", |
| 101 | + "numberMatchingRequiredState": "enabled" |
| 102 | + } |
| 103 | + ] |
| 104 | +} |
| 105 | + |
| 106 | +``` |
| 107 | + |
| 108 | +To confirm this update has applied, run the GET request below using the endpoint below. |
| 109 | +GET - https://graph.microsoft.com/beta/authenticationMethodsPolicy/authenticationMethodConfigurations/MicrosoftAuthenticator |
| 110 | + |
| 111 | + |
| 112 | +#### Example of how to enable additional context for a single group |
| 113 | + |
| 114 | +Change the **displayAppInformationRequiredState** value from **default** to **enabled.** |
| 115 | +Change the **id** from **all_users** to the ObjectID of the group from the Azure AD portal. |
| 116 | + |
| 117 | +You need to PATCH the entire includeTarget 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 example below only shows the update to the **displayAppInformationRequiredState**. |
| 118 | + |
| 119 | +```json |
| 120 | +//Copy paste the below in the Request body section as shown below. |
| 121 | +//Leverage the Response body to create the Request body section. Then update the Request body similar to the Request body as shown below. |
| 122 | +//Change query to PATCH and run query |
| 123 | + |
| 124 | +{ |
| 125 | + "@odata.context": "https://graph.microsoft.com/beta/$metadata#authenticationMethodConfigurations/$entity", |
| 126 | + "@odata.type": "#microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration", |
| 127 | + "id": "MicrosoftAuthenticator", |
| 128 | + "state": "enabled", |
| 129 | + "[email protected]": "https://graph.microsoft.com/beta/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets", |
| 130 | + "includeTargets": [ |
| 131 | + { |
| 132 | + "targetType": "group", |
| 133 | + "id": "1ca44590-e896-4dbe-98ed-b140b1e7a53a”, |
| 134 | + "authenticationMode": "any", |
| 135 | + "displayAppInformationRequiredState": "enabled", |
| 136 | + "numberMatchingRequiredState": "enabled" |
| 137 | + } |
| 138 | + ] |
| 139 | +} |
| 140 | +``` |
| 141 | + |
| 142 | +To verify, RUN GET again and verify the ObjectID |
| 143 | +GET https://graph.microsoft.com/beta/authenticationMethodsPolicy/authenticationMethodConfigurations/MicrosoftAuthenticator |
| 144 | + |
| 145 | + |
| 146 | +#### Example of error when enabling additional context for multiple groups |
| 147 | + |
| 148 | +The PATCH request will fail with 400 Bad Request and the error will contain the following message: |
| 149 | + |
| 150 | +`Persistance of policy failed with error: You cannot enable multiple targets for feature 'Require Display App Information'. Choose only one of the following includeTargets to enable: aede0efe-c1b4-40dc-8ae7-2c402f23e312,aede0efe-c1b4-40dc-8ae7-2c402f23e317.` |
| 151 | + |
| 152 | +### Test the end-user experience |
| 153 | +Add the test user account to the Microsoft Authenticator app. The account **doesn't** need to be enabled for phone sign-in. |
| 154 | + |
| 155 | +See the end-user experience of an Authenticator MFA push notification with additional context by signing into aka.ms/MFAsetup. |
| 156 | + |
| 157 | +### Turn off additional context |
| 158 | + |
| 159 | +To turn off additional context, you'll need to PATCH remove **displayAppInformationRequiredState** from **enabled** to **disabled**/**default**. |
| 160 | + |
| 161 | +```json |
| 162 | +{ |
| 163 | + "@odata.context": "https://graph.microsoft.com/beta/$metadata#authenticationMethodConfigurations/$entity", |
| 164 | + "@odata.type": "#microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration", |
| 165 | + "id": "MicrosoftAuthenticator", |
| 166 | + "state": "enabled", |
| 167 | + "[email protected]": "https://graph.microsoft.com/beta/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets", |
| 168 | + "includeTargets": [ |
| 169 | + { |
| 170 | + "targetType": "group", |
| 171 | + "id": "all_users", |
| 172 | + "authenticationMode": "any", |
| 173 | + "displayAppInformationRequiredState": "enabled", |
| 174 | + "numberMatchingRequiredState": "default" |
| 175 | + } |
| 176 | + ] |
| 177 | +} |
| 178 | +``` |
| 179 | + |
| 180 | +## Enable additional context in the portal |
| 181 | + |
| 182 | +To enable additional context in the Azure AD portal, complete the following steps: |
| 183 | + |
| 184 | +1. In the Azure AD portal, click **Security** > **Authentication methods** > **Microsoft Authenticator**. |
| 185 | +1. Select the target users, click the three dots on the right, and click **Configure**. |
| 186 | + |
| 187 | +  |
| 188 | + |
| 189 | +1. Select the **Authentication mode**, and then for **Show additional context in notifications (Preview)**, click **Enable**, and then click **Done**. |
| 190 | + |
| 191 | +  |
| 192 | + |
| 193 | +## Next steps |
| 194 | + |
| 195 | +[Authentication methods in Azure Active Directory - Microsoft Authenticator app](concept-authentication-authenticator-app.md) |
| 196 | + |
0 commit comments