The configuration of The Multi-Context Broker Model in Shib IdPv3 is accomplished in various configuration files.  It also may depend on customization of authentication flows, though the project team is aware of some of the limitations and is working to improve the system for future releases.

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 and conf/authn/general-authn.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, particularly the page on flow selection.

Authentication Contexts and Authentication Methods

The analog of an Authentication Method in idPv3 is an Authentication Flow, and the SAML 2 concept of an AuthnContextClassRef (and the SAML 1 concept of an AuthenticationMethod) is represented by special type of Java custom Principal object, which keeps the SAML-specific concept abstracted from the rest of the authentication layer. Authentication flows produce Java Subjects, and the Principals carried in a Subject will include the SAML AuthnContextClassRef(s) associated with that Subject.

Authentication flows are enumerated to the system in conf/authn/general-authn.xml. For example, the following defines two Authentication Flows for example.org, "authn/standard" for http://id.example.org/standard, and authn/strong for http://id.example.org/strong. By site policy, http://id.example.org/strong satisfies the requirements of http://id.example.org/standard for the purpose of requiring that certain services and/or users use stronger (e.g., two-factor) authentication methods, while other situations require username/password only.

<util:list id="shibboleth.AvailableAuthenticationFlows">
    ...
    <bean id="authn/standard" parent="shibboleth.AuthenticationFlow">
        <property name="supportedPrincipals">
            <list>
                <bean parent="shibboleth.SAML2AuthnContextClassRef"
                    c:classRef="http://id.example.org/standard" />
            </list>
        </property>
    </bean>
    <bean id="authn/strong" parent="shibboleth.AuthenticationFlow">
        <property name="supportedPrincipals">
            <list>
                <bean parent="shibboleth.SAML2AuthnContextClassRef"
                    c:classRef="http://id.example.org/strong" />
                <bean parent="shibboleth.SAML2AuthnContextClassRef"
                    c:classRef="http://id.example.org/standard" />
            </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.

Authentication Context Hierarchy

Note in the example above that authn/standard lists only http://id.example.org/standard as a supportedPrincipal, but auth/strong lists both http://id.example.org/standard and http://id.example.org/strong. This is because http://id.example.org/strong satisfies http://id.example.org/standard, so authn/strong can be used for either Authentication Context.

Authentication Method Selection Preference

The order that Authentication Flows are listed in conf/authn/general-authn.xml determines the preference of which method will be invoked when more than one is able to satisfy the SP's request.  In the example above, this means that authn/standard will be invoked to satisfy requests for http://id.example.org/standard, even though authn/strong would also satisfy the request, unless the user is not certified to use http://id.example.org/standard, forcing that user to use authn/strong.  Requests for http://id.example.org/strong will always invoke authn/strong, or return an error if the user is not certified for http://id.example.org/strong.  See below for information on users' certified contexts.

Users' Certified Contexts

The IdP attribute containing a user's certified authentication types 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 produced in the same manner as other Shibboleth attributes, by configuring the attribute resolver.

# 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

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 with the idp.authn.flows.initial property, 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 = Password

Note that if you specify more than one "initial" method, they will be tried in the order listed in authn/general-authn.xml.

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 satisfies the requirements of a username/password. 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 via the Password flow's "extended flows" feature.

Second Factor Only Technologies

If your site supports more authentication methods, however, you may want to create a custom second factor only flow that does the following:

1. Check to see if the first factor method has already invoked.  If yes, use the Principal you already have.  If no, invoke the first factor flow as a subflow.
2. Perform the second factor processing.

For extra credit, make the second factor flow configurable for the following:

• a list of Principal types that can be used for the first factor, and
• the authentication flow that will be invoked as a subflow if non of the acceptable Principal types are available.

Initial Authentication Flow and the UserName Principal

If you use a Password Initial Authentication Flow, that will establish a net.shibboleth.idp.authn.principal.UsernamePrincipal, with that becoming the canonicalized username. 2FA plugins for the IdP often rely on that canonicalized username to identify the user to the 2FA service.  Some institutions configure their login to accept more than one form of username, and if that username was used directly to identify the user to the 2FA technology, the user could end up as "multiple users" in the 2FA service user database, one record per form of username they enter. One solution to that problem would be to leverage the Attribute-based Canonicalization (c14n) flow to specify a specific user attribute to serve as the username, in place of the username entered in the login form. An example of how to configure this can be found on the AttributePostLoginC14NConfiguration page.

Default Authentication Context (method) for an SP

Default authentication context(s) can be configured for an SP in the conf/relying-party.xml configuration file. It's actually specified by setting the SSO profile property of defaultAuthenticationMethods to a list of Principals identified by the associated SAML AuthnContextClassRef. If the SP does not specify a RequestedAuthnContext, then this default will be used as if the SP did request this specific AuthnContext.

Here is an example of defining a template bean for the SAML2.SSO profile that sets the defaultAuthenticationMethods to the Principal associated with a context identified as http://www.duosecurity.com/, and then a sample of using that template bean in a RelyingPartyByName override.

    <bean id="SAML2.SSO.requireDuo" parent="SAML2.SSO"> 
       <property name="defaultAuthenticationMethods">
           <list>
               <bean parent="shibboleth.SAML2AuthnContextClassRef"
                   c:classRef="http://www.duosecurity.com/" />
           </list>
       </property>
    </bean>
 
....
 
    <!--
    Override that identifies a list of RPs by name and configures it
    for SAML 2 SSO that requires 2FA with Duo
    -->
    <bean parent="RelyingPartyByName"
      c:relyingPartyIds="https://examplesp.campus.edu/shibboleth">
        <property name="profileConfigurations">
            <list>
                <bean parent="SAML2.SSO.requireDuo" />
            </list>
        </property>
    </bean>