Multifactor Authentication in Shibboleth 2.N

One option for enabling multi-factor authentication for Shibboleth is to use the Multi-Context Broker. This framework offers an excellent way to develop different style of 2nd factor modules for Shibboleth.

Second Factor E-mail

GTRI has created one such packaging where the 2nd factor is based on the user's e-mail address, where a code is e-mailed to the user's registered e-mail address and then they type in the code. This 2nd factor verification may be cached for some amount of time as determined by the configuration. This MCB package may be downloaded: File:Secondfactorbyemail.zip.

Second Factor Source Code

This e-mail second factor is in a repository derived from the MCB on github: GTRI Customized MCB. The following installation instructions refer specifically to the zipfile.

Installation Instructions

1. Create a directory in your Shibboleth install directory called templates. Copy each of the *.vm files into this directory.

2. Copy the velocity.properties file and the two xml files into your Shibboleth conf directory /opt/shib-idp/conf

3. Copy the jar file into the Tomcat deployed directory, {tomcat}/webapps/{idp-directory}/WEB-INF/lib

4. Update the web.xml file in the Tomcat deployed directory, {tomcat}/webapps/{idp-directory}/WEB-INF/web.xml Find the line that looks like this (usually around line 10-15):

  <param-value>file:/opt/shib-idp/conf/internal.xml; file:/opt/shib-idp/conf/service.xml; </param-value>

Update it to include the mcb-spring.xml file that you copied into this same directory in step 2:

  <param-value>file:/opt/shib-idp/conf/internal.xml; file:/opt/shib-idp/conf/service.xml; file:/opt/shib-idp/conf/mcb-spring.xml;</param-value>

Additionally add the servlet definition for the MCB to the file :

   <servlet>
       <servlet-name>MCBLoginServlet</servlet-name>
       <servlet-class>edu.internet2.middleware.assurance.mcb.authn.provider.MCBLoginServlet</servlet-class>
       <load-on-startup>3</load-on-startup>
   </servlet>
   <servlet-mapping>
       <servlet-name>MCBLoginServlet</servlet-name>
       <url-pattern>/Authn/MCB</url-pattern>
   </servlet-mapping>

5. The multi-context broker works by authenticating a user and then it resolves the user's attributes to determine if an additional factor is required. We have to add attribute information to the attribute-resolver.xml to cause the 2nd factor requirement to trigger. To do this add the following to the attribute-resolver.xml.

Define an attribute:

   <resolver:AttributeDefinition id="AuthnValues" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad"
       sourceAttributeID="authnvalues">
       <resolver:Dependency ref="staticAttributes" />
   </resolver:AttributeDefinition>

The above simply resolves it statically which is fine if all users will use the same 2nd factor. In that case also add the new attribute to the static attribute data conntector within this file. The value(s) specified are matched against the data within multi-context-broker.xml and must match:

   <resolver:DataConnector id="staticAttributes" xsi:type="Static" xmlns="urn:mace:shibboleth:2.0:resolver:dc">
       <Attribute id="authnvalues">
           <Value>urn:oasis:names:tc:SAML:2.0:ac:classes:EmailTwoFactor</Value>
       </Attribute>
   </resolver:DataConnector>

6. Configure the EmailTwoFactor submodule. To do this edit the mcb-spring.xml file. The main section that must be configured is the mcb.emailcode bean (parameters 1-5 should be set, the first should be correct unless the file was renamed):

   <bean id="mcb.emailcode" class="edu.internet2.middleware.assurance.mcb.authn.provider.EmailCodeSubmodule">
       <constructor-arg index="0" value="emailcode.vm" />  The name of the velocity template used to display the email code input page.
       <constructor-arg index="1" value="60" /> Days that the entered code remains valid
       <constructor-arg index="2" value="EmailAddress" /> Attribute Id that contains the user's Email Address (Attribute Id from attribute-resolver.xml)
       <constructor-arg index="3" value="localhost" /> Hostname of mail server
       <constructor-arg index="4" value="nobody@nohost.com" /> Email Address that codes are shown as From
       <constructor-arg index="5" value="asdkfj" /> A random string to insure cookies set by this login module cannot be hacked.  Please change it from the default!
   </bean>

Additionally verify that all of the paths in this file are correct. There will be multiple references to the other XML configuration files.

7. Customize the multi-context-broker.xml. This may not be needed as the delivered version should prompt for username/password and then require an e-mail code 2nd factor. This file allows a good bit of orchestration of other multi-factor methodologies.

8. Add logging for the MCB by editing the logger.xml file and add:

  <logger name="edu.internet2.middleware.assurance.mcb" level="DEBUG"/>

9. Edit the velocity.properties file. At a minimum the template loader path will need to be set:

  file.resource.loader.path

10. Edit the Shibboleth handler.xml file to set the MCB as the single loginhandler. First update the namespaces and schema locations at the top of the file:

 <ph:ProfileHandlerGroup xmlns:ph="urn:mace:shibboleth:2.0:idp:profile-handler"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                       xmlns:mcb="edu:internet2:middleware:assurance:mcb"
                       xsi:schemaLocation="urn:mace:shibboleth:2.0:idp:profile-handler
                                           classpath:/schema/shibboleth-2.0-idp-profile-handler.xsd
                                           edu:internet2:middleware:assurance:mcb classpath:/schema/mcb-login-handler.xsd">

Then add the MCB as a login handler:

 <ph:LoginHandler xsi:type="mcb:MultiContextBroker" authenticationDuration="PT4H0M0.000S" previousSession="true"
   depends-on="mcb.Configuration">
   <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</ph:AuthenticationMethod>
   <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</ph:AuthenticationMethod>
   <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession</ph:AuthenticationMethod>
   <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:EmailTwoFactor</ph:AuthenticationMethod>
 </ph:LoginHandler>

11. If your system is currently using JAAS to do username/password login,you will need to update the login.config file for use by the MCB. Specifically ShibUserPassAuth will need to be replaced with MCBUserPassAuth.

12. Customize {idp-home}/template/jaaslogin.vm. This is just an HTML file that is processed by the Velocity engine doing minor substitutions and variable resolution.

13. Customize {idp-home}/template/emailcode.vm. This is just an HTML file that is processed by the Velocity engine doing minor substitutions and variable resolution.