The REFEDS MFA Profile: https://refeds.org/profile/mfa is the vendor-agnostic approach to signalling Multi-Factor Authentication in R&E identity federations like Tuakiri (and among such federations when connected to eduGAIN).
A Service Provider (SP) can signal the MFA requirement by including an AuthnContextClassRef with value of
[https://refeds.org/profile/mfa](https://refeds.org/profile/mfa) in the SAML SSO requests.
An Identity Provider (IdP) responds to such requests by enforcing an MFA login - and confirming that by including the REFEDS MFA AuthnContextClassRef in the SAML response.
The SP still needs to check the response AuthnContextClassRef - as in many cases, it would be possible to alter the login flow and bypass MFA.
This page (drawing on the upstream MFA documentation) documents the configuration steps required on Shibboleth SP.
Requesting a specific authentication method depends on how the session is initiated - whether explicitly (by redirecting to the Session Initiator) or implicitly (by accessing a page requiring a Shibboleth session).
In the redirect to the Session Initiator (typically
/Shibboleth/Login ), include the query string parameter
authnContextClassRef=https://refeds.org/profile/mfa in the URL.
In your Apache config requesting a Shibboleth session, include the
authnContextClassRef content setting with value
<Location /auth/login> AuthType shibboleth require shibboleth ShibRequestSetting requireSession true ShibRequestSetting authnContextClassRef https://refeds.org/profile/mfa </Location>
The above so far only includes REFEDS MFA in the SSO request sent to the IdP. It is important to also check that it is included in the IdP response.
This can be done with the Apache
require directive - in the simplest case replacing the stub
require shibboleth used in the example above. (If multiple
require directives were needed, they’d have to be wrapped in a
RequireAll block to join them with a logical and , otherwise Apache would default to a logical or ).
If the session is established with a different
authnContextClassRef value (which, if REFEDS MFA was requested in the SSO request would be a misconfiguration of the IdP, or deliberate tinkering with the session setup), Apache will block further access with an HTTP 401 Authorization Required error page.
We recommend customising the error response page to make it clear login was rejected because MFA was not used.
The following example extends the above sample code requesting MFA to also check REFEDS MFA and overrides the 401 error message:
<Location /auth/login> AuthType shibboleth require authnContextClassRef https://refeds.org/profile/mfa ShibRequestSetting requireSession true ShibRequestSetting authnContextClassRef https://refeds.org/profile/mfa ErrorDocument 401 "<b>Access denied</b>: Multi-Factor Authentication is required to access this resource" </Location>
When a SAML SSO request asking for REFEDS MFA (via an
authContextClassRef ) is sent to an IdP not supporting the specific authentication method, the IdP will send back a SAML response indicating a login failure, which will be rendered by the SP as a generic error message.
To improve the user experience, we recommend to customise the error handler. The easiest way is to replace the
/etc/shibboleth/sessionError.html template with a customised one provided here: https://raw.githubusercontent.com/REANNZ/Tuakiri-public/master/shibboleth-sp/mfa/sessionError.html
This template customises the original one by:
/etc/shibboleth/sessionError.html will work well for simple sites that request REFEDS MFA for all sessions. The missing support for MFA will be the most likely cause for an IdP to report an error back to the SP.
It is also possible to apply this template only for specific URLs, or use a custom error handling page that the SP would redirect to. For further information, please see the upstream documentation on error handling or contact email@example.com .
Please get in touch with firstname.lastname@example.org to request further advice with your planned deployment.