Installation and configuration
Download and install the login handler
Two factor login
- You can use
multifactor-login-handler/examples/login.jspas an example.
- Place it in
- 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.
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
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:RelyingParty> 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.
$IDP_HOME/conf/handler.xml, add the xsd schema in the
$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.
- You can read about how JAAS works at http://download.oracle.com/javase/1.5.0/docs/api/javax/security/auth/login/Configuration.html
- Multi factor JAAS is similar to UsernamePassword JAAS
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
- Set up an OATH-HOTP basic auth protected web page somewhere using the Apache mod_authn_otp.
See this page for more details.
/var/www/oath-protected/index.htmlwith some known content, like "
- Set up a two-factor JAAS configuration
mf-login.conf(making sure the name matches the cnofigured
jaasConfigNamein your web.xml):
yubico-java-client/src/main/java/com/yubico/jaas/README for further details about
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
- Set up a two-factor JAAS configuration in the referenced
jaasConfigurationLocationfile, e.g. when re-using
login.configfor both login handlers:
See https://github.com/Yubico/yubico-java-client/tree/master/jaas for all parameters and their use. Change the
clientId to your "API key" provided by Yubico. As per
get_username_for_id() from YubikeyToUserMapImpl.java 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:
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.
$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.