Two Factor Authentication with Shibboleth

About

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 *.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 like 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" />
       <constructor-arg index="1" value="60" /> 
       <constructor-arg index="2" value="EmailAddress" /> 
       <constructor-arg index="3" value="localhost" /> 
       <constructor-arg index="4" value="nobody@nohost.com" /> 
       <constructor-arg index="5" value="asdkfj" /> 
   </bean>

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. 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.

9. 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.