System-preferred MFA feature and how to control it via the Graph API

Being able to configure a default method to be used as part of an MFA challenge is a common ask. In the per-user MFA scenario, customers were able to exert some controls over this by adjusting the StrongAuthenticationMethods property via the Set-MsolUser cmdlets. As Microsoft is moving away from the per-user MFA controls and replacing them with Conditional access policies and the authentication method policy, this method is no longer relevant. In fact, the /authentication/methods endpoints documentation lists the inability to set a default MFA method as a known limitation.

To address some of the concerns around this, Microsoft is now introducing the system-preferred multi-factor authentication feature. In a nutshell, the feature ensures that the user will be prompted via the most secure method configured for his account, whenever a MFA challenge is issued. The current set of supported MFA methods is accordingly prioritized and published in the official documentation, so we can have a predictable experience. Here are the methods, in order of descending priority:

1. Temporary Access Pass
2. Certificate-based authentication
3. FIDO2 security key
4. Microsoft Authenticator notification
5. Companion app notification
6. Microsoft Authenticator time-based one-time password (TOTP)
7. Companion app TOTP
8. Hardware token based TOTP
9. Software token based TOTP
10. SMS over mobile
11. OnewayVoiceMobileOTP
12. OnewayVoiceAlternateMobileOTP
13. OnewayVoiceOfficeOTP
14. TwowayVoiceMobile
15. TwowayVoiceAlternateMobile
16. TwowayVoiceOffice
17. TwowaySMSOverMobile

While TAP is certainly not the most secure method, it’s position on top of the list is governed by its nature – to be used for initial setup or recovery scenarios. Additional methods will be added as they become available, and the overall arrangement is totally in Microsoft’s control – the only thing we as customers can control is whether the feature is enabled, and to which users it will apply. Let’s see what the available options are.

The configuration of the system-preferred MFA feature is done as part of the authentication methods policy, available under the /policies/authenticationMethodsPolicy Graph API endpoint. Within said policy, the settings corresponding to the system-preferred MFA feature are part of the systemCredentialPreferences resource type. Currently, only the /beta endpoint will return said resource type, but as the feature matures to GA, it will become available under /v1.0 as well. The Policy.ReadWrite.AuthenticationMethod permission is required for both read and edit operations (as in, there is no read-only scope?), and both application and delegate permissions are supported. Here’s how the default configuration looks like:

GET https://graph.microsoft.com/beta/authenticationMethodsPolicy

As you can see from the screenshot above, the feature is disabled by default, while at the same time scoped to cover all users within the tenant. To enable the feature, you need to toggle the state property’s value to enabled, or if you prefer, set it to default in order to automatically toggle it when Microsoft decides the feature is ready for the general public. Optionally, you can also scope the feature to cover only a subset of the users within your tenant. Two types of configuration are available here: inclusive filter via the includeTargets property’s value or scope the feature to everyone, except excludeTargets‘s value. For both controls, only a single entry can be specified and the supported types are: group, role, or administrative unit.

With that information at hand, here’s how to toggle this feature on and scope it to members of a specific group. First, we need to prepare a JSON payload with the systemCredentialPreferences‘s representation. Set the state property’s value to enabled and under includeTargets, provide the id of the group you wish to use as a scoping filter. Set the targetType value to group. Then, issue a PATCH request against the /beta/authenticationMethodsPolicy endpoint. Something like this should do:

{
    "systemCredentialPreferences": {
        "state": "enabled",
        "excludeTargets": [],
        "includeTargets": [
        {
            "id": "e1381039-a9e7-464a-94c1-e0b8e665842e",
            "targetType": "group"
        }
        ]
    }
}

PATCH https://graph.microsoft.com/beta/authenticationMethodsPolicy

If everything went OK, a 204 No Content response will be returned. We can then re-query the current policy’s settings:

GET https://graph.microsoft.com/beta/authenticationMethodsPolicy

And that’s more or less all there is to the system-preferred MFA feature. The Graph API’s documentation is yet to be published it seems, but a raw copy can be found on GitHub, and some examples here. In addition, no support for managing the feature is currently available in the Graph SDK for PowerShell. Well, you can always use the Invoke-MgGraphRequest cmdlet as a workaround:

Connect-MgGraph -Scopes Policy.ReadWrite.AuthenticationMethod

Invoke-MgGraphRequest -Method GET -Uri 'https://graph.microsoft.com/beta/authenticationMethodsPolicy' | select -ExpandProperty systemCredentialPreferences

Name Value
---- -----
includeTargets {e1381039-a9e7-464a-94c1-e0b8e665842e}
state enabled
excludeTargets {}

Until next time!