Docs

Execute an Authorization Code Grant Flow

Multi-factor Authentication and Resource Owner Password

Highly-trusted applications can use the Resource Owner Password Grant to access an API. The flow typically involves prompting the user for username and password as credentials to be submitted to Auth0. In some scenarios, however, stronger authentication may be required. This document outlines using scopesmulti-factor authentication (MFA) with the Resource Owner Password Grant.

1. Get the User's Authorization

Prerequisites

Before you continue, make sure that you've met the following prerequisites:

  1. MFA is enabled on the Auth0 dashboard. Duo Security is not supported as a factor with this flow.

  2. An Application is configured to execute the Resource Owner Password Grant (either password or password-realm grant types). For details on how to implement this, refer to Execute the Resource Owner Password Grant.

  3. End users are enrolled in MFA.

2. Exchange the Authorization Code for an Access Token

Initiate Multi-factor Authentication

The flow starts by collecting end-user credentials and sending them to Auth0, as described in Resource Owner Password Grant. Both password and password-realm flows are available.

  1. The user enters their credentials into the Application.

  2. The Application forwards the credentials to Auth0.

  3. Auth0 validates the credentials and executes any applicable rules.

  4. If any rule triggers MFA for the current user, an error code of mfa_required is returned. The error will additionally contain an mfa_token property.

  1. The Application will then make a request to the MFA challenge endpoint, specifying the challenge types it supports. Valid challenge types are: OTP, OOB with binding method prompt, and OOB with no binding method. If you already know that otp is supported by the end-user and you don't want to request a different factor, you can skip this and the next steps an go directly to Challenge Type OTP below.

  2. Auth0 sends a response containing the challenge_type derived from the types supported by the Application and the specific user. Additionally, extra information, such as binding_method may be included to assist in resolving the challenge and displaying the correct UI to the user.

The supported challenge types are:

  • otp: A one-time password generated by an app setup with a seed or by token generation hardware. This mechanism does not require an extra channel to prove possession; you can get it directly from the app / hardware device.

  • oob: The proof of possession is done 'out of band' via a side channel. There are several different channels, including push notification-based authenticators and SMS-based authenticators. Depending on the channel and the authenticator chosen at enrollment, you may need to provide a binding_code used to bind the side channel and the channel used for authentication.

To execute MFA, follow the next steps according to the challenge type you will use:

  • OTP: for this challenge type, your application must prompt the end-user for an OTP code and continue the flow using the mfa-otp grant type.

  • OOB and binding method prompt: the challenge will be sent through a side channel (such as SMS), and your application will need to prompt the user for the binding_code that was included as part of the challenge sent, as well as the oob_code received as response to this request to prove possession.

  • OOB with no binding method: in this case, the proof of possession will be driven entirely in a side channel (such as a push notification-based authenticator). The response will include an oob_code that the Application will use to periodically check for the resolution of the transaction. Continue the flow using the mfa-oob grant type.

3. Call the API

Execute Multi-factor Authentication

The following sections cover how to execute MFA based on the challenge type used.

4. Verify the Token

Challenge Type: OTP

Resource Owner MFA OTP

For this type of challenge, the Application must get an one-time password (otp) code from a OTP Generator app, such as Google Authenticator or Microsoft Authenticator.

If you already know that the user supports OTP, then steps 5 and 6 above of the Initiate Multi-factor Authentication section are optional.

  1. The Application prompts the end user to enter an OTP code.

  2. The end user enters their OTP into the Application.

  3. The Application forwards the OTP code to Auth0 using grant_type=http://auth0.com/oauth/grant-type/mfa-otp and includes the mfa_token obtained in step 4 above.

  4. Auth0 validates the provided OTP and returns the Access Token and the Refresh TokenRefresh Token.

  5. The Application can use the Access Token to call the API on behalf of the end user.

Optional: Customize the Tokens

Challenge Type: OOB with Binding Method prompt

Resource Owner MFA OOB Prompt

This challenge type, together with prompt binding method, indicates that the challenge will be delivered to the user using a side channel (such as SMS) and that a binding_code is needed to bind the side channel to the one being authenticated. The binding code is sent as part of the challenge message and it is usually an OTP-like code composed of 6 numeric digits.

  1. The Application prompts the user for the binding_code and stores the oob_code from step 6 for future use.

  2. The end user receives the challenge on the side channel and enters the binding_code into the Application.

  3. The Application forwards the binding_code to Auth0 using grant_type=http://auth0.com/oauth/grant-type/mfa-oob and includes the mfa_token (from step 4) and oob_code (from step 6).

  4. Auth0 validates the binding_code and oob_code and returns the Access Token and the Refresh Token.

  5. The Application can use the Access Token to call the API on behalf of the end user.

Keep Reading

Challenge Type: OOB with No Binding Method

Resource Owner MFA OOB

In this scenario, the challenge will be sent using a side channel, however, there is no need for a binding_code. Currently, the only mechanism supported for this scenario is Push Notification with the Guardian Provider.

  1. The Application asks the user to accept the delivered challenge and keeps the oob_code from step 6 for future use.

  2. The Application polls Auth0 using grant_type=http://auth0.com/oauth/grant-type/mfa-oob and includes the mfa_token (from step 4) and oob_code (from step 6).

  3. Auth0 validates the provided oob_code, the mfa_token and returns:

    • authorization_pending error: if the challenge has not been accepted nor rejected.
    • slow_down error: if the polling is too frequent.
    • an access_token and a refresh_token: if the challenge has been accepted; polling should be stopped at this point.
    • invalid_grant error: if the challenge has been rejected; polling should be stopped at this point.
  4. The Application can use the Access Token to call the API on behalf of the end user.

Using Recovery Codes

This flow is not available when the user uses provider = google-authenticator or provider = duo.

Resource Owner MFA Recovery

Some providers support using a recovery code to login in case the enrolled device is not available, or if lack of connectivity prevents receiving an OTP code or push notification.

Using a recovery code is similar to using an OTP code to login. The main difference is that a new recovery code will be generated, and that the application must display this new recovery code to the user for secure storage.

Steps 1-4 are the same as above.

  1. End user chooses to use the recovery code.

  2. The Application prompts the end user to enter recovery code.

  3. The end user enters their recovery code into the Application.

  4. The Application forwards the recovery code to Auth0 using grant_type=http://auth0.com/oauth/grant-type/mfa-otp and includes the mfa_token from step 4.

  5. Auth0 validates the recovery code and returns the Access Token and the Refresh Token.

  6. The Application can use the Access Token to call the API on behalf of the end user.

Samples

The following are sample implementations involving MFA.

Resource Owner Password Grant Request

Challenge Request

MFA OTP Grant Request

MFA OOB Grant Request

MFA Recovery Grant Request

MFA API

Please see the MFA API section for detailed information on Auth0's MFA API endpoints.