The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.

Main Configuration File

The main configuration file for the MCB controls the logic used to provide the assurance levels requested by each Service Provider. This file is loaded by the MCB configuration bean from the Spring configuration file. Each section of the file is detailed below and a complete example is attached for reference.

velocityPropertiesFile

    <velocityPropertiesFile>/opt/shibboleth-idp/conf/velocity.properties</velocityPropertiesFile>

This is the Velocity configuration file used by the MCB. It controls where the templates are loaded from and how often the Velocity engine checks for modifications.

initialAuthContext

    <!--
        Show this list of choices for initial authentication to establish a session. Optionally limit the choices
        to those also requested by the SP. If no choices match the SP request, then show the entire list just as if
        the SP had not requested any.
    -->
    <initialAuthContext requestedOnly="true">
            <context name="urn:oasis:names:tc:SAML:2.0:ac:classes:Password" />
            <context name="http://id.incommon.org/assurance/bronze" />
    </initialAuthContext>

On the initial authentication of a user, some choice must be made about how to authenticate the user. This option is a list of the authentication context values you as the administrator wish to present to the user. If there is only a single choice, then the user will immediately be sent to that method. If there are more than one, then the user will be presented with a list to choose from. This process can be modified by setting the requestedOnly value to true. If it is set to true, then the list of choices will be filtered by the requested values sent by the SP. However, if the SP sends no matching context values, the MCB will default to the list as given. Once initial authentication has occurred successfully, then the MCB will validate the other rules about which context values which users are allowed.

idms

    <!-- 
        This value identifies the ID of the attribute in the Shibboleth attribute-resolver.xml file that contains the user's allowed context values.
    -->
    <idms attributeResolverID="assurance" />

In order to validate that a given user is allowed to use a certain context level, the MCB must be able to obtain the list from some source. This is done by tying in with the standard Shibboleth attribute-resolver.xml file. The value given here is the ID value of an attribute resolver rule that contains those choices. Once a user is authenticated, the attribute resolver will be called to resolve those values and use them in the decision making process.

principalAuthnContextRequired

    <!--
        If set to FALSE, then if the user has no assigned contexts and the SP does not request one, then
        successful authentication via the initial authentication will be returned to the SP as
        successful. This in effect mimics the current Shibboleth behavior.
        If set to TRUE, then a valid context for the user is always required.
     -->
    <principalAuthnContextRequired>true</principalAuthnContextRequired>

This option allows the administrator to allow a user to successfully authenticate to a SP if the user does not have a context assigned to their identity in the IDMS and the SP does not request any context value. By setting this value to false, the behavior of regular Shibboleth authentication will be used. If the SP requests a context value, this option is ignored. If the user has a context assigned, this option is ignored.

maxFailures

    <!-- 
        The maximum number of failures allowed a user before returning a SAML failure to the
        relying party. Must be specified according to schema definition. Set to a value of -1
        to allow an unlimited number of login failures.
     -->
    <maxFailures>3</maxFailures>

The maximum number of times a user may fail login before being redirected back to the Service Provider with a SAML error response. A value of -1 disables the option.

authnContexts

    <!-- 
        authContexts is the list of configured contexts the MCB will honor.
     -->
    <authnContexts>
        <!-- 
            For each context, the name attribute is used to match up with the values returned by the IdMS and also
            used to match the requested authentication context sent by the SP.
            The method attribute corresponds to the authentication method this context uses.
         -->
        <context name="urn:oasis:names:tc:SAML:2.0:ac:classes:Password" method="password">
            <allowedContexts>
                <context name="http://id.incommon.org/assurance/bronze" />
            </allowedContexts>
        </context>
        <context name="http://id.incommon.org/assurance/bronze" method="bronze">
            <!--
                Note that since the bronze level allows silver and silver allows gold, means gold is acceptable here. Contexts
                are inherited. Since two levels of silver have been configured, either is acceptable for authenticating at the
                bronze level (but only because both are listed).
            -->
            <allowedContexts>
                <context name="http://id.incommon.org/assurance/silver" />
                <context name="http://id.incommon.org/assurance/silver-token" />
            </allowedContexts>
        </context>

This section is the heart of the MCB. It defines which authentication contexts the MCB knows about, how it authenticates a user for that context, and how these context values relate to one another in terms of strength and precedence. Each context node gives the authentication context name it represents. It also specifies which authentication method is to be used to authenticate for that context. The allowedContexts list is a list of higher strength context values which can be substituted for this context. So in the above example, the password context can also be satisfied by the bronze context. The bronze context itself can be satisfied by the silver or silver-token contexts. So if a user authenticates via bronze and later accesses a SP that only requires password, they would be allowed access without re-authentication. If however, they then access a SP that requires silver, they would be prompted to re-authenticate via the silver context and its configured method.

Any number of context values may be specified.

You may NOT define a circular reference within the context section. The MCB will check for circular dependencies on start up and throw a fatal exception if one is found.

authnMethods

    <!-- 
        authMethods is the list of authentication methods supported by the MCB
     -->
    <authMethods>
        <!-- 
            A method defines one authentication method. The name attribute corresponds to the method value
            used in the context definition. The bean attribute is the name of the submodule bean loaded by
            the Spring framework during Shibboleth startup. The value of the method node is the friendly name
            used for display purposes.
        -->
        <method name="password" bean="mcb.usernamepassword">
            Username/Password Only
        </method>
        <method name="bronze" bean="mcb.usernamepasswordbronze">
            Bronze Level Password
        </method>
        <method name="silver" bean="mcb.usernamepasswordsilver">
            Silver Assurance Level
        </method>

Authentication methods are implemented by the submodules defined in the Spring configuration file. Each method has a name which corresponds to the method attribute of the context definitions (tying them together). Each method also has a bean name which ties back to the Spring definition. Finally, each method has a value that is used as the friendly display name during the authentication selection process by the user. Each context defined must have a method that can be used to satisfy it. Note that multiple context values may use the same method. In that case, a user completing authentication by that method is satisfying all context values the user is allowed to use that have that method configured. As an example, if you define the password and bronze contexts to both use the password method, then the user will have completed both authentication contexts (password and bronze), assuming the user is allowed to use both password and bronze. This is true even if the selection choice was for password (implying bronze is a higher level of authentication).