Sovrain
  1. Documentation
  2. Identity provider
  3. For developers

How-to guide

Require two-step sign-in from your app

Ask Sovrain for a second step in the sign-in request, and check in the token or assertion that it happened.

This guide makes Sovrain ask for a second step before it signs a person in to your app, and shows how your app checks that the second step really took place.

There are two ways to get a second step. An admin can turn on Require two-step sign-in for the app (see Require two-step sign-in); then Sovrain asks for it on every sign-in to the app. Or your app asks for it in the request, as below, for example only before a sensitive action. In both cases, check the result in your app.

With OpenID Connect

  1. Add acr_values to the authorization request with one of the two values Sovrain issues:

    &acr_values=https%3A%2F%2Frefeds.org%2Fprofile%2Fmfa
    

    The other value is http://schemas.openid.net/pape/policies/2007/06/multi-factor. Either one makes Sovrain ask for a second step.

    Sovrain does not let the sign-in through without a second step when you ask for one of these values. If you ask with an essential acr in the claims parameter instead (URL-encode the JSON), a request that names only values Sovrain never issues fails with unmet_authentication_requirements instead of succeeding without a second step:

    claims={"id_token":{"acr":{"essential":true,"values":["https://refeds.org/profile/mfa"]}}}
    
  2. Sovrain handles the rest. If the person’s session has only a password, Sovrain asks for their second step, or asks them to set one up if they have none. If the session already has a second step, Sovrain does not ask again. With prompt=none, the request fails with interaction_required instead of showing a page.

  3. In the ID token, check that amr contains mfa. After a password alone it is ["pwd"]. The other values, which tell which second step was used, are in Claims and attributes › amr values.

  4. Check acr. It is present only after a second step, and then it is the first value you asked for, or http://schemas.openid.net/pape/policies/2007/06/multi-factor if you asked for none. A token without acr comes from a password-only sign-in.

Check the ID token, not userinfo: userinfo never returns amr or acr. A refreshed ID token carries amr and acr as the session has them: if the person adds their first second step in this session, a refreshed token shows it.

If you need the second step to be recent, also send max_age and check auth_time.

With SAML

  1. Add a RequestedAuthnContext to the AuthnRequest with one of the two second-step classes Sovrain recognizes, https://refeds.org/profile/mfa or http://schemas.microsoft.com/claims/multipleauthn:

    <samlp:RequestedAuthnContext Comparison="exact">
      <saml:AuthnContextClassRef>https://refeds.org/profile/mfa</saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
    

    exact and minimum both work. Do not add a password class next to it: a request that a password alone can satisfy does not force a second step.

  2. In the assertion, check that the AuthnContextClassRef of the AuthnStatement is the class you asked for. After a password-only sign-in it is urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport.

If Sovrain cannot meet the request, your app receives a response with the status NoAuthnContext. If the request has IsPassive="true" and a page would be needed, the status is NoPassive.

Without a RequestedAuthnContext, a sign-in with a second step carries the class the admin chose under Two-step sign-in signal (REFEDS MFA by default). If the admin chose Password only, such a sign-in looks like a password-only one, so ask for the class explicitly.

Why Sovrain signals the second step this way: About two-step sign-in. All claim values: Claims and attributes.