DRAFT - Under Construction - DRAFT

The configuration of Multi-Context Broker (MCB) Model in Shib IdPv3 is accomplished in various of the configuration files.  It also may depend on customization of authentication flows.  This is a high-level description of how to map the elements of the MCB Model 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.

Authentication Contexts and Authentication Methods

The analog of an Authentication Method in idPv3 is an Authentication Flow, and the Authentication Contexts it supports are the types of Principals that can be returned by the Flow.

Authentication flows are listed in conf/authn/general-authn.xml.  For example, the following defines the urn:oasis:names:tc:SAML:2.0:ac:classes:Password Authentication Context, using authn/Password for its Authentication Method.

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

        ...

    </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 Principal 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 user certifications, as described in the next section.  Watch for future enhancements to IdPv3 to improve its ability to handle these circumstances.

Users' Certified Contexts

The Shibboleth attribute containing a user's certified authentication contexts is configured in conf/idp.properties.  The following declares that the "assurance" attribute will contain the current user's certifications.  The "assurance" attribute itself is defined in the same manner as other Shibboleth attributes.

# 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

Authentication Context Hierarchy

IdPv3 can be configured to specify which Contexts are allowed to satisfy the requirements of other Contexts.  This is done in conf/authn/authn-comparison.xml. The basic approach is to define a shibboleth.<MatchFactory> bean with matchingRules that list the Principal types that satisfy each of the other Principal types.

The following example illustrates how three Contexts; Password, Bronze, and Silver; can be defined such that

• Bronze and Silver satisfy the requirements of Password, and
• Silver satisfies the requirements of Bronze.

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

After defining the shibboleth.<MatchFactory> bean, it is also necessary to configure it for use in "exact" matching in the <util:map id="shibboleth.AuthnComparisonRules"> object, further down in the same file.  You probably also want to configure it for "better" matching:

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

Initial Authentication Flow

An initial authentication flow can be used to gather information about the current user at the start of the session with the IdP, prior to processing any SP requests.  Uses include

• supporting second-factor-only technologies like U2F and Duo, and
• determining the current user's allowed contexts.

The initial authentication flow is configured in conf/idp.properties as idp.authn.flows.initial, a regular expression matching the possible initial flows.  For example, the following will configure the initial authentication flow to be authn/Password.

# 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

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. 

Over time, you may find that your site supports multiple authentication flows that can be used as an initial authentication flow. Consider an example where either username/password or a hardware token might be used as an initial authentication flow, and the hardware token's Context satisfies the requirements of the username/password Context. A user with a hardware token might prefer to use it, even when it is not required by the first SP's request, as the hardware token would likely satisfy the requirements of later SP requests. Modifying the username/password login screen to include a button to invoke hardware token authentication (and training users with hardware tokens to use that button instead of typing their username and password) can accomplish this.  Watch for future improvements in IdPv3 to facilitate these kind of flows.