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.
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. If that is configured, then a user completing authentication by that method means they have satisfied either context value that uses that method. 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). This is true even if the selection choice was for password (implying bronze is a higher level of authentication).