MCB Installation

The Multi-Context Broker is installed just as any Shibboleth Login Handler extension is installed.

Install the JAR files into your Shibboleth build environment. This means the lib directory where the Shibboleth install.sh (or install.bat) is located and from where you build the Shibboleth WAR file. The current JAR for the MCB is multi-context-broker-1.1.4.jar.

The MCB uses Spring to load the submodules. To enable this you must add the mcb-spring.xml file to the list of Spring files in the web.xml for the Shibboleth WAR file, i.e., src/main/webapp/WEB-INF/web.xml:

    <!-- Spring 2.0 application context files. Files are loaded in the order they appear with subsequent files overwriting 
        same named beans in previous files. -->
    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value> $IDP_HOME$/conf/internal.xml; $IDP_HOME$/conf/service.xml; $IDP_HOME$/conf/mcb-spring.xml;</param-value>
    </context-param>

The next step is to modify the web.xml for the Shibboleth WAR file to load the necessary servlet:

    <!-- Servlet for MCB Authentication -->
    <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>

Redeploy Shibboleth after editing the web.xml file and installing the JAR files into the build environment. The details depend on how you manage your container but many deployers will be able to simply run install.sh or install.bat again and answer no when prompted whether or not to overwrite the configuration.

Now modify the handler.xml for your copy of Shibboleth to have a reference to the necessary schema files:

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

The two lines that have been inserted are the xmlns:mcb and corresponding schema location value for mcb-login-handler.xsd.

Now replace the existing login handler definitions in handler.xml with the definition for the MCB 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:unspecified</ph:AuthenticationMethod>
        <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</ph:AuthenticationMethod>
        <ph:AuthenticationMethod>http://id.incommon.org/assurance/bronze</ph:AuthenticationMethod>
        <ph:AuthenticationMethod>http://id.incommon.org/assurance/silver</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:TimeSyncToken</ph:AuthenticationMethod>
        <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:OTPDevice</ph:AuthenticationMethod>
        <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession</ph:AuthenticationMethod>
    </ph:LoginHandler>

Note that you must specify all possible authentication context (method) values here that you want to handle. Shibboleth requires that the handler specify which ones it can service. Also note that the standard PreviousSession login handler must be commented out or removed so that the MCB is able to examine each authentication request as they come in from SPs.

The next task is to place the two MCB configuration files in your Shibboleth conf directory: mcb-spring.xml and multi-context-broker.xml. You will edit these files later to configure the MCB.
The MCB uses Apache Velocity to render the HTML for the pages it needs. A sample velocity.properties is included in the distribution and should be placed in your Shibboleth conf directory. The mandatory value to edit in this file is the path to the templates directory for Velocity. The suggested path is $SHIB_HOME/templates (/opt/shibboleth-idp/templates) just to keep all configuration concise.
Once the Velocity templates directory is created, place the sample template files (*.vm) into it. (NOTE: multi-context-broker-1.1.2.zip has the *.vm files mode 640. You'll want to make them 644 or chgrp to your web server user.) There are examples for JAAS login and the context/method selection page. The JAAS examples includes 3 versions that only differ in the labels on them. These were created for testing purposes to distinguish between different authentication methods. You may freely edit and/or rename these to suit your purposes. The JAAS login submodule receives the template name as part of its bean definition.
To add logging for the various MCB classes to the standard Shibboleth logging, add the following to the standard logging.xml file:
```
<logger name="edu.internet2.middleware.assurance.mcb" level="DEBUG"/>
```
It should be placed with the other logger elements in the file. It follows the standard logging levels of INFO, ERROR, DEBUG, and TRACE.

At this point, the base setup is finished for the MCB. The final configuration steps are to modify the two configuration files (mcb-spring.xml and multi-context-broker.xml) to suit your deployment.

Spring Configuration File

Main Configuration File

multi-context-broker-1.1.2.zip

multi-context-broker-1.1.4.zip