Step-up Authentication

With Step-Up Authentication, applications that allow access to different types of resources can require users to authenticate with a stronger authentication mechanism to access sensitive resources.

For example, Fabrikam's Intranet can require users to authenticate with their username and password to access customer data. However, a request for access to employee data (which may contain sensitive salary information) can trigger a stronger authentication mechanism like multifactor authentication.

You can add step-up authentication to your app with Auth0's extensible multifactor authentication support. Your app can verify that the user has logged in using multifactor authentication and, if not, require the user to step-up to access certain resources.

Step-up flow

Step-up Authentication with Auth0

There are three core concepts used when addressing authentication level at Auth0.

  • acr is used to specify the 'class' of authentication that was performed on the current session. Look to Authentication Context Class Reference page for more detail and specific policies. Currently, Auth0 utilizes the 'Multi-Factor Authentication' policy, http://schemas.openid.net/pape/policies/2007/06/multi-factor.

  • amr is the list of methods that were used to authenticate the current session. See the Authentication Methods References page for more details.

  • acr_values can be used to request the class of acr above when authentication is to be performed. See here for more details.

acr and amr are both available on the id_token of the current session, when appropriate. The acr_values field is added to the request for authentication.

Example

To request that Auth0 require a multifactor authentication, add the field acr_values to the authentication along with the acr level desired. For example, with Auth0.js it would work like the following code snippet.

// Use acr_values to indicate this user needs a step-up with MFA
auth0.signin({
  connection: 'google-oauth2',
  acr_values: 'http://schemas.openid.net/pape/policies/2007/06/multi-factor'
});

With Lock, the following would indicate the need for MFA.

// Use acr_values to indicate this user needs a step-up with MFA
var options = {
  ...
  auth: {
    acr_values: 'http://schemas.openid.net/pape/policies/2007/06/multi-factor'
  }
};

lock = new Auth0Lock('clientID', 'account.auth0.com', options);

To confirm that a session has had multifactor authentication, the id_token can be checked for its acr and amr claims.

var decoded = jwt.verify(id_token, AUTH0_CLIENT_SECRET, { algorithms: ['HS256'] });

// Confirm that the acr has the expected value
if (Array.isArray(decoded.amr) && decoded.amr.indexOf('mfa') >= 0) {
  throw new Error('Step-up authentication failed');
}

// We also expect to have the amr claim
if(decoded.acr !== 'http://schemas.openid.net/pape/policies/2007/06/multi-factor'){
  throw new Error('Step-up authentication failed');
}

More example code with the step-up functionality can be found here.

Further reading