Skip to end of metadata
Go to start of metadata
  • The multi-factor-login-handler is similar to the UsernamePassword login handler, but can be configured to require more than one authentication factor.
  • The first factor is likely your existing password solution (like Kerberos or LDAP) and the second factor a hardware token, such as an OATH-HOTP token.

Installation and configuration

Download and install the login handler


Login pages

Two factor login

  • You can use multifactor-login-handler/examples/login.jsp as an example.
  • Place it in $IDP_INSTALL_DIR/src/main/webapp/
    • The example provided can be used with both this and the UsernamePassword login handler without changes, so replacing the default one seems easiest. If you have customized the IdP login page you'd need to redo the customization again to this version, or simply add the changes between this example and the upstream login.jsp to your customized version.

Web application

Enable the the Multi Factor login servlet in $IDP_INSTALL_DIR/src/main/webapp/WEB-INF/web.xml or in your copy outside the WAR file in $IDP_HOME/conf/web.xml:


Note that using the MultiFactor login handler as the only login handler practically restricts the entire IdP to uses with Tokens. This is because once this login handler runs (whether requested by a relying party or by IdP configuration) it will unconditionally assert a SAML Authentication Context Class of "urn:oasis:names:tc:SAML:2.0:ac:classes:Token", even if the underlying JAAS module stack is configured to make use of a Token fully optional (i.e., only username and password have been provided).


Using MultiFactor and UsernamePassword together

So it seems best to use the UsernamePassword login handler as well, for any uses that don't require a token. This limits the use of the MultiFactor login handler to those cases where provding an OTP token is in fact strictly required and requested by a Relying Party. Note that I had to add a defaultAuthenticationMethod="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" on the <rp:DefaultRelyingParty> element in $IDP_HOME/conf/relying-party.xml as the MultiFactor login handler took precedence. If you have custom <rp:DefaultRelyingParty> elements defined that may also be necessary for those.

For that change the jaasConfigName parameter for this login handler so that both JAAS configurations do not conflict even when using the same JAAS config file. This is again accomplished in $IDP_INSTALL_DIR/src/main/webapp/WEB-INF/web.xml or your copy in $IDP_HOME/conf/web.xml: (see IdPAuthUserPass#IdPAuthUserPass-AdvancedConfigurationOptions):

Do not forget to propagate this change in your JAAS configuration file referenced by jaasConfigurationLocation below, as per the examples. You may re-use the existing login.config and simply add another ShibMultiFactorAuth stanza to it (after the ShibUserPassAuth one), or reference a different file.

Handler configuration

In $IDP_HOME/conf/handler.xml, add the xsd schema in the <ProfileHandlerGroup> :

Also in $IDP_HOME/conf/handler.xml, add the new Login Handler :

As mentioned above you can re-use the same jaasConfigurationLocation as for the UsernamePassword login handler ( $IDP_HOME/conf/login.config) by including a named section for each use in that file. See the YubiKey example below.

JAAS configuration

OATH-HOTP example


This example adds a second authentication factor that lets you use any OATH-HOTP token by validating that the token provided by the user can be used to access a OATH-HOTP basic auth protected web page.

  • Get and install the HttpOathOtpLoginModule JAAS module.
  • Create /var/www/oath-protected/index.html with some known content, like "Authenticated OK.".
  • Set up a two-factor JAAS configuration mf-login.conf (making sure the name matches the cnofigured jaasConfigName in your web.xml):

See yubico-java-client/src/main/java/com/yubico/jaas/README for further details about HttpOathOtpLoginModule configuration.

YubiKey example


This example adds a second authentication factor that lets you use a YubiKey OTP token by validating that the token provided by the user (1) may be used by the authenticated subject and (2) can be validated by a YubiKey OTP validation service (one you run yourself or the "cloud" service Yubico provides.)

  • Get and install the YubikeyLoginModule JAAS module.
  • Set up a two-factor JAAS configuration in the referenced jaasConfigurationLocation file, e.g. when re-using login.config for both login handlers:

See for all parameters and their use. Change the clientId to your "API key" provided by Yubico. As per get_username_for_id() from the referenced id2name_textfile needs to contain a mapping from subject (i.e. "username" provided during authentication) to YubiKey public_id in the following format, one per line:

yk.<token-id>.user = <username>
yk.<token-id>.user = <username>
yk.<token-id>.user = <username>

All lines not starting with "yk." will be ignored, so could be used for comments, if needed.
Make sure the user your Java servlet container runs as has read permission for this file.

Logging configuration


In $IDP_HOME/conf/logging.xml, add logging configuration for the multi factor login handler :

And for the OATH OTP or YubiKey JAAS module:


Backup your IdP configuration before re-deploying the IdP web app

Known issues, bugs & comments

As indicated above, this login handler SHOULD ONLY be used when making the Yubi JAAS module "required". The IdP will send incorrect assertions otherwise, claiming the use of a Token when that has not been ensured.

Send bugs & comments to Klas Lindfors.

  • No labels

1 Comment

  1. It works! (smile) I'll edit the page regarding how to use the MultiFactorAuthLoginHandler and the UsernamePasswordLoginHandler at the same time.