This page has been superseded by material at https://spaces.internet2.edu/display/InCAssurance/The+Multi-Context+Broker+Model and Configuring the Multi-Context Broker Model in Shibboleth IdPv3. It contains inaccuracies in some areas and may be removed or corrected at a later date TBD. For now please refer to the other material.

The configuration of Multi-Context Broker (MCB) functionality in Shib IdPv3 is accomplished in various of the configuration files. It also may depend on customization of authentication flows. Here is a high-level description of how to map the elements of MCB configuration in multi-context-broker.xml to IdPv3. The potentially affected IdPv3 files are conf/idp.properties, conf/authn/general-authn.xml, and conf/authn/authn-comparison.xml. In many cases, more capability is provided in the IdPv3 files than has existed in the MCB, so perusal of those files and the IdPv3 documentation is recommended.

initialAuthContext

multi-context-broker.xml

    <!--
        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="false">
            <context name="urn:oasis:names:tc:SAML:2.0:ac:classes:Password" />
            <context name="http://id.incommon.org/assurance/bronze" />
    </initialAuthContext>

The initial authentication context is configured in conf/idp.properties as idp.authn.flows.initial, a regular expression matching the possible initial flows:

conf/idp.properties

# Regular expression of forced "initial" methods when no session exists,
# usually in conjunction with the idp.authn.resolveAttribute property below.
#idp.authn.flows.initial = authn/Password | authn/Bronze

where authn.flows.initial = urn:oasis:names:tc:SAML:2.0:ac:classes:Password and http://id.incommon.org/assurance/bronze are Principal types supported by authn/Password and authn/Bronze. See authnContexts, below.

Note that if you specify more than one "initial" method, one will be picked at random, unless you configure shibboleth.AuthenticationPrincipalWeightMap in general-authn.xml, as described in AuthenticationConfiguration. Also note that the requestedOnly option is not supported. One of the initial flows will be selected, independent of the SP's request.

attributeResolverID

multi-context-broker.xml

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

The attribute containing a user's allowed authentication contexts is configured in conf/idp.properties:

conf/idp.properties

# Set to an attribute ID to resolve prior to selecting authentication flows;
# its values are used to filter the flows to allow.
#idp.authn.resolveAttribute = assurance

We should figure out when this attribute is resolved. If it's resolved for every SP request, then a scripted attribute should solve Scott Koranda's use case of having different allowed contexts for users, depending on the SP they're using.

principalAuthnContextRequired

multi-context-broker.xml

    <!--
        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 configuration option is not supported in IdPv3. The IdP always behaves as if principalAuthnContextRequired were set to true.

showSatisfiedContexts

multi-context-broker.xml

    <!--
        Show satisfied contexts for upgrade authentications. Defaults to false if not defined.
    -->
    <showSatisfiedContexts>false</showSatisfiedContexts>

IdPv3 does not present choices to the end user when multiple authentication flows are feasible, so this configuration option is not supported.

This will need to be part of the flow definition that presents authentication method choices to users, assuming we create a template for that.

maxFailures

multi-context-broker.xml

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

In the MCB, this is the number of times the MCB would allow a user to select another authentication method, when a previously-selected method had failed. Since IdPv3 does not support selection, this configuration option is not supported.

IdPv3 does allow a flow to signal that another feasible flow should be attempted, but once a flow is rejected, it cannot be retried. Individual flows, of course, can be coded to allow an arbitrary number of attempts for a particular authentication method.

This will need to be part of the flow definition that presents authentication method choices to users, assuming we create a template for that.

authnContexts

In the MCB, Authentication Contexts are defined in multi-context-broker.xml and their Authentication Methods are properties of the Context. In IdPv3, the approach is different. The analog of an Authentication Method is an Authentication Flow, and the Contexts it supports are properties of the Flow. The concept of a Context is embodied as a type of Principal that can be returned by the Flow.

multi-context-broker.xml

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

        <!-- Additional <context>'s...  -->

    </authnContexts>

Authentication flows are listed in conf/authn/general-authn.xml:

conf/authn/general-authn.xml

    <util:list id="shibboleth.AvailableAuthenticationFlows">
        <bean id="authn/Password" parent="shibboleth.AuthenticationFlow">
            <property name="supportedPrincipals">
                <util:list>
                    <bean parent="shibboleth.SAML2AuthnContextClassRef"
                        c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:Password" />
                </util:list>
            </property>
        </bean>

        <!-- Additional Flows...  -->

    </util:list>

The actual Authentication Flow and its beans are defined in separate files named according to the id of the Flow's bean above. As stated in AuthenticationConfiguration:

The id property of each descriptor is not arbitrary. It MUST be prefixed by "authn/" and it corresponds to a web flow definition. The predefined beans correspond to built-in flows. Creating a new flow involves not only describing the flow in this list, but ensuring the id matches a flow definition created inside flows/authn/. Specifically, creating the custom login flow "authn/foo" requires that the flow definition file be named flows/authn/foo/foo-flow.xml.

Note that while it is possible to associate an Authentication Flow with many different supportedPrincipals, the results can be confusing if the Principle types supported by a single Authentication Flow are not, essentially, equivalent. In many cases, it may be more effective to configure multiple flows with copies of the same bean when their supportedPrincipals differ in ways other than the authentication method, for example when they require different values from the idp.authn.resolveAttribute, as described above.

allowedContexts

The MCB can be configured to specify which Contexts are allowed to satisfy the requirements of other contexts. For example, assuming that the InCommon Bronze assurance profile satisfies the requirements of Password, and InCommon Silver satisfies all requirements of InCommon Bronze.

multi-context-broker.xml

        <context name="Password" method="password">
            <allowedContexts>
                <context name="http://id.incommon.org/assurance/bronze" />
            </allowedContexts>
        </context>        
        <context name="http://id.incommon.org/assurance/bronze" method="bronze">
            <allowedContexts>
                <context name="http://id.incommon.org/assurance/silver" />
            </allowedContexts>
        </context>
        <context name="http://id.incommon.org/assurance/silver" method="silver"/>

In IdPv3, this is configured in conf/authn/authn-comparison.xml.

conf/authn/authn-comparison.xml

   <bean id="shibboleth.BetterClassRefMatchFactory" parent="shibboleth.InexactMatchFactory">
        <property name="matchingRules">
            <map>
                <entry key="Password">
                    <list>
                        <value>http://id.incommon.org/assurance/bronze</value>
                        <value>http://id.incommon.org/assurance/silver</value>
                    </list>
                </entry>
                <entry key="http://id.incommon.org/assurance/bronze">
                    <list>
                        <value>http://id.incommon.org/assurance/silver</value>
                    </list>
                </entry>
            </map>
        </property>
    </bean>

Note that while allowed contexts are inherited in the MCB, they must all be listed explicitly for each context in IdPv3. (Is this true?)

After defining the shibboleth.BetterClassRefMatchFactory, it is also necessary to configure it for use in "exact" matching further down in the same file. You probably also want to configure it for "better" matching:

conf/authn/authn-comparison.xml

    <!-- Registry of matching rules. -->
    <util:map id="shibboleth.AuthnComparisonRules">
       ...
    <!-- Exact matching. -->
        <entry key-ref="shibboleth.SAMLAuthnMethodExact" value-ref="shibboleth.BetterClassRefMatchFactory"/>
        <entry key-ref="shibboleth.SAMLACClassRefExact" value-ref="shibboleth.BetterClassRefMatchFactory"/>
        <entry key-ref="shibboleth.SAMLACDeclRefExact" value-ref="shibboleth.BetterClassRefMatchFactory"/>
       ...
    <!-- Better matching -->
        <entry key-ref="shibboleth.SAMLACClassRefBetter" value-ref="shibboleth.BetterClassRefMatchFactory"/>
        <entry key-ref="shibboleth.SAMLACDeclRefBetter" value-ref="shibboleth.BetterClassRefMatchFactory"/>
    </util:map>

SPs that request no context will bypass all of this. This will prevent a site from requiring, for example, certain people to use MFA. Is it possible to configure the default relying party to require a context that is satisfied by all others, thereby triggering the comparison matching?

Browser not supported