Configure user’s default MFA method via the Graph API

As all y’all should know by now, some high profile deprecation/end of support dates are coming later this month, including the beloved MSOnline PowerShell module and the cmdlets therein. Among the scenarios enabled by said module were things like setting the default multi-factor authentication method for users leveraging per-user MFA, which had no matching replacement in the Graph API. Until now that is.

Meet the /users/{id}/authentication/signInPreferences endpoint! Currently available under /beta, the endpoint supports GET queries to fetch the currently configured preferred MFA method, as well as PATCH queries to make changes to the configuration. The corresponding permissions required are UserAuthenticationMethod.Read for the GET method (UserAuthenticationMethod.Read.All if working on another user) and UserAuthenticationMethod.ReadWrite  for the PATCH one (UserAuthenticationMethod.ReadWrite.All if working on another user), respectively, with both delegate and application permissions supported. Like any other PATCH operation, you will need additional permissions when using the delegate permissions method to perform changes on any other admin user.

So let’s see what data the new endpoints expose, and how to make changes to it. We start with a simple GET query, the output of which features three elements: isSystemPreferredAuthenticationMethodEnabled tells us whether the system-preferred MFA feature is enabled for the user, and if so, populates the systemPreferredAuthenticationMethod value to list the set of methods available to the user, whereas the userPreferredMethodForSecondaryAuthentication property gives information of which method the user has set as preferred (if not using the system-preferred one). Here’s an example:

GET https://graph.microsoft.com/beta/users/user@domain.com/authentication/signInPreferences

As you can see from the above, the user in question does not have the system-preferred MFA feature enabled, and has set push notifications as his preferred MFA method. In contrast, when a user falls under the scope of system-preferred MFA policy, the output looks like the below. Note the value of the systemPreferredAuthenticationMethod property!

Of course, the more interesting part of this feature is setting user’s default MFA method, so let’s see how that works. We need to issue a PATCH request against the /users/{id}/authentication/signInPreferences endpoint, and provide a JSON payload with two elements: isSystemPreferredAuthenticationMethodEnabled, to indicate whether the system-preferred MFA feature should be enabled on the user, and/or userPreferredMethodForSecondaryAuthentication, used to set the preferred MFA method directly. The supported values for the latter are: push, oath, voiceMobile, voiceAlternateMobile, voiceOffice, sms, and unknownFutureValue (catch-all for any future methods).

Do note that the value you specify for the property must correspond to a method already configured for the user. You can fetch the list of currently configured methods via a GET query against the /users/{id}/authentication/methods endpoint. For example, if the user has only his mobile device configured, so only sms and voice methods available, we cannot set oauth as his preferred MFA method. Trying to do so will result in an error, as shown below:

PATCH https://graph.microsoft.com/beta/users/user@domain.com/authentication/methods

{
"userPreferredMethodForSecondaryAuthentication": "oath"
}

A “good” request should take into consideration the methods currently available on the user, and configure one of them as the default. For example, we can change the user’s preferred method from sms to voiceMobile by using the following request:

PATCH https://graph.microsoft.com/beta/users/user@domain.com/authentication/signInPreferences

{
"userPreferredMethodForSecondaryAuthentication": "voiceMobile"
}

A successful execution of the request is indicated by “No Content – 204” response, which you can follow up with another GET request to confirm the changes. Another important thing to note is that setting the default MFA method via the userPreferredMethodForSecondaryAuthentication does not automatically toggle off the system-preferred MFA feature, if enabled on the user. This is illustrated on the screenshot below. Thus if you want to make sure that going forward the user will have to use a specific MFA method, the request should take into consideration the value of the isSystemPreferredAuthenticationMethodEnabled property as well, and change it as needed!

And that more or less covers the newly introduced authentication sign-in preferences endpoint and configuring default MFA method for your users via the Graph API. For additional information, you can refer to the official documentation. Remember that the feature is still in /beta, so there might be some rough edges. Also, no corresponding Graph SDK for PowerShell cmdlets are yet available, so if you want to use PowerShell to set this, you will have to leverage the Invoke-MgGraphRequest cmdlet.