How to Use Number Matching in Multifactor Authentication (MFA) Notifications – Authentication Methods Policy

Posted on by Summa Lai

This topic covers how to enable number matching in Microsoft Authenticator push notifications to improve user sign-in security.

Number matching is a key security upgrade to traditional second-factor notifications in the Authenticator app that will be enabled by default for all tenants a few months after general availability (GA).
We highly recommend enabling number matching in the near-term for improved sign-in security.

Prerequisites

Your organization will need to enable Authenticator (traditional second factor) push notifications for some users or groups using the new Authentication Methods Policy API. If your organization is using ADFS adapter or NPS extensions, please upgrade to the latest versions for a consistent experience.

Number matching

Number matching 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.

Number matching is available for the following scenarios. When enabled, all scenarios support number matching.

 Note

For passwordless users, enabling or disabling number matching has no impact because it’s already part of the passwordless experience.

Multifactor authentication

When a user responds to an MFA push notification using the Authenticator app, they will be presented with a number. They need to type that number into the app to complete the approval.

Screenshot of user entering a number match.

SSPR

During self-service password reset, the Authenticator app notification will show a number that the user will need to type in their Authenticator app notification. This number will only be seen to users who have been enabled for number matching.

Combined registration

When a user is goes through combined registration to set up the Authenticator app, the user is asked to approve a notification as part of adding the account. For users who are enabled for number matching, this notification will show a number that they need to type in their Authenticator app notification.

AD FS adapter

The AD FS adapter supports number matching after installing an update. Earlier versions of Windows Server don’t support number matching. On earlier versions, users will continue to see the Approve/Deny experience and won’t see number matching until you upgrade.

VersionUpdate
Windows Server 2022October 26, 2021—KB5006745 (OS Build 20348.320) Preview
Windows Server 2019October 19, 2021—KB5006744 (OS Build 17763.2268) Preview
Windows Server 2016October 12, 2021—KB5006669 (OS Build 14393.4704)

NPS extension

Make sure you run the latest version of the NPS extension. NPS extension versions beginning with 1.0.1.40 support number matching.

Because the NPS extension can’t show a number, a user who is enabled for number matching will still be prompted to Approve/Deny. However, you can create a registry key that overrides push notifications to ask a user to enter a One-Time Passcode (OTP). The user must have an OTP authentication method registered to see this behavior. Common OTP authentication methods include the OTP available in the Authenticator app, other software tokens, and so on.

If the user doesn’t have an OTP method registered, they will continue to get the Approve/Deny experience. A user with number matching disabled will always see the Approve/Deny experience.

To create the registry key that overrides push notifications:

  1. On the NPS Server, open the Registry Editor.
  2. Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\AzureMfa.
  3. Set the following Key Value Pair: Key: OVERRIDE_NUMBER_MATCHING_WITH_OTP Value = TRUE
  4. Restart the NPS Service.

Policy schema changes

 Note

In Graph Explorer, ensure you’ve consented to the Policy.Read.All and Policy.ReadWrite.AuthenticationMethod permissions.

Identify your single target group for the schema configuration. Then use the following API endpoint to change the numberMatchingRequiredState property to enabled:

https://graph.microsoft.com/beta/authenticationMethodsPolicy/authenticationMethodConfigurations/MicrosoftAuthenticator

MicrosoftAuthenticatorAuthenticationMethodConfiguration properties

PROPERTIES

PropertyTypeDescription
idStringThe authentication method policy identifier.
stateauthenticationMethodStatePossible values are: enabled
disabled

RELATIONSHIPS

RelationshipTypeDescription
includeTargetsmicrosoftAuthenticatorAuthenticationMethodTarget
collectionA collection of users or groups who are enabled to use the authentication method.

MicrosoftAuthenticator includeTarget properties

PROPERTIES

PropertyTypeDescription
authenticationModeStringPossible values are:
any: Both passwordless phone sign-in and traditional second factor notifications are allowed.
deviceBasedPush: Only passwordless phone sign-in notifications are allowed.
push: Only traditional second factor push notifications are allowed.
idStringObject ID of an Azure AD user or group.
targetTypeauthenticationMethodTargetTypePossible values are: user, group.
Please note: You will be able to only set one group or user for number matching.
numberMatchingRequiredStateadvancedConfigStatePossible values are:
enabled explicitly enables the feature for the selected group.
disabled explicitly disables the feature for the selected group.
default allows Azure AD to manage whether the feature is enabled or not for the selected group.

 Note

Number matching can only be enabled for a single group.

Example of how to enable number matching for all users

You will need to change the numberMatchingRequiredState from default to enabled.

Note that 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 will use any, but if you do not want to allow passwordless, use push.

 Note

For passwordless users, enabling or disabling number matching has no impact because it’s already part of the passwordless experience.

You might 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 numberMatchingRequiredState.

JSONCopy

//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/beta/$metadata#authenticationMethodConfigurations/$entity",
    "@odata.type": "#microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration",
    "id": "MicrosoftAuthenticator",
    "state": "enabled",
    "[email protected]": "https://graph.microsoft.com/beta/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",
    "includeTargets": [
        {
            "targetType": "group",
            "id": "all_users",
            "authenticationMode": "any",
            "displayAppInformationRequiredState": "enabled",
            "numberMatchingRequiredState": "enabled"
        }
    ]
}

To confirm this has applied, please run the GET request below using the endpoint below. GET – https://graph.microsoft.com/beta/authenticationMethodsPolicy/authenticationMethodConfigurations/MicrosoftAuthenticator

Example of how to enable number matching for a single group

We will need to change the numberMatchingRequiredState value from default to enabled. You will need to change the id from all_users to the ObjectID of the group from the Azure AD portal.

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 numberMatchingRequiredState.

JSONCopy

//Copy paste the below in the Request body section as shown below.
//Leverage the Response body to create the Request body section. Then update the Request body similar to the Request body as shown below.
//Change query to PATCH and run query
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#authenticationMethodConfigurations/$entity",
    "@odata.type": "#microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration",
    "id": "MicrosoftAuthenticator",
    "state": "enabled",
    "[email protected]": "https://graph.microsoft.com/beta/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",
    "includeTargets": [
        {
            "targetType": "group",
            "id": "1ca44590-e896-4dbe-98ed-b140b1e7a53a",
            "authenticationMode": "any",
            "displayAppInformationRequiredState": "enabled",
            "numberMatchingRequiredState": "enabled"
        }
    ]
}

To verify, RUN GET again and verify the ObjectID GET https://graph.microsoft.com/beta/authenticationMethodsPolicy/authenticationMethodConfigurations/MicrosoftAuthenticator

Example of error when enabling number matching for multiple groups

The PATCH request will fail with 400 Bad Request and the error will contain the following message:

Persistance of policy failed with error: You cannot enable multiple targets for feature 'Require Number Matching'. Choose only one of the following includeTargets to enable: aede0efe-c1b4-40dc-8ae7-2c402f23e312,aede0efe-c1b4-40dc-8ae7-2c402f23e317.

Test the end user experience

Add the test user account to the Authenticator app. The account does not need to be enabled for phone sign-in.

See the end user experience of an Authenticator MFA push notification with number matching by signing into aka.ms/MFAsetup.

Turn off number matching

To turn number matching off, you will need to PATCH remove numberMatchingRequiredState from enabled to disabled/default.

JSONCopy

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#authenticationMethodConfigurations/$entity",
    "@odata.type": "#microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration",
    "id": "MicrosoftAuthenticator",
    "state": "enabled",
    "[email protected]": "https://graph.microsoft.com/beta/$metadata#authenticationMethodsPolicy/authenticationMethodConfigurations('MicrosoftAuthenticator')/microsoft.graph.microsoftAuthenticatorAuthenticationMethodConfiguration/includeTargets",
    "includeTargets": [
        {
            "targetType": "group",
            "id": "all_users",
            "authenticationMode": "any",
            "displayAppInformationRequiredState": "enabled",
            "numberMatchingRequiredState": "default"
        }
    ]
}

Enable number matching in the portal

To enable number matching in the Azure AD portal, complete the following steps:

  1. In the Azure AD portal, click Security > Authentication methods > Microsoft Authenticator.
  2. Select the target users, click the three dots on the right, and click Configure.Screenshot of configuring number match.
  3. Select the Authentication mode, and then for Require number matching (Preview), click Enable, and then click Done.Screenshot of enabling number match.

 Note

Least privileged role in Azure Active Directory – Multifactor authentication

Number matching is not supported for Apple Watch notifications. Apple Watch need to use their phone to approve notifications when number matching is enabled.

Next steps

Authentication methods in Azure Active Directory

Ref: https://docs.microsoft.com/en-us/azure/active-directory/authentication/how-to-mfa-number-match