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
Add
acr_valuesto the authorization request with one of the two values Sovrain issues:&acr_values=https%3A%2F%2Frefeds.org%2Fprofile%2FmfaThe 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
acrin theclaimsparameter instead (URL-encode the JSON), a request that names only values Sovrain never issues fails withunmet_authentication_requirementsinstead of succeeding without a second step:claims={"id_token":{"acr":{"essential":true,"values":["https://refeds.org/profile/mfa"]}}}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 withinteraction_requiredinstead of showing a page.In the ID token, check that
amrcontainsmfa. After a password alone it is["pwd"]. The other values, which tell which second step was used, are in Claims and attributes ›amrvalues.Check
acr. It is present only after a second step, and then it is the first value you asked for, orhttp://schemas.openid.net/pape/policies/2007/06/multi-factorif you asked for none. A token withoutacrcomes 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
Add a
RequestedAuthnContextto the AuthnRequest with one of the two second-step classes Sovrain recognizes,https://refeds.org/profile/mfaorhttp://schemas.microsoft.com/claims/multipleauthn:<samlp:RequestedAuthnContext Comparison="exact"> <saml:AuthnContextClassRef>https://refeds.org/profile/mfa</saml:AuthnContextClassRef> </samlp:RequestedAuthnContext>exactandminimumboth work. Do not add a password class next to it: a request that a password alone can satisfy does not force a second step.In the assertion, check that the
AuthnContextClassRefof theAuthnStatementis the class you asked for. After a password-only sign-in it isurn: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.