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.

Understand the MCB Model

This document will be difficult to understand if you have not read The Multi-Context Broker Model, as it introduces the concepts of the MCB Model.

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.

Excerpted from authn/general-authn.xml

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

Don't violate authnContext definitions

Note that not all authnContexts are defined to be satisfied by other contexts. In particular, the SAML-defined contexts mean exactly what they say, and they can't be satisfied by some other authentication method without violating the spec. For example, urn:oasis:names:tc:SAML:2.0:ac:classes:Password cannot be satisfied by "urn:oasis:names:tc:SAML:2.0:ac:classes:X509". In contrast, http://id.example.org/standard in our example is defined by example.org policy so that its requirements are satisfied by http://id.example.org/strong. Therefore, http://id.example.org/strong can be configured to satisfy http://id.example.org/standard without violating the expectations of the community using those values.

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

Note that the idp.auth.flows.initial and idp.authn.resolveAttribute properties are deprecated and will be removed from V4. See AuthenticationConfigurationfor details

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.

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

Initial Authentication Flow

Note that the idp.auth.flows.initial and idp.authn.resolveAttribute properties are deprecated and will be removed from V4. See AuthenticationConfigurationfor details

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:

Excerpt from 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 = 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

Second factor only technologies like U2F and Duo are not full-fledged Authentication Methods, as described in this document. The MCB Model, and IdPv3, consider an Authentication Method as something that tells you who the current user is. Second factor only technologies do not do this; you tell them who you think the current user is, and they tell you if they agree with that (increasing your confidence in who the current user is).

For this reason, the user must have been authenticated with a first factor before a second factor method can succeed. For now, this requires configuration of an Initial Authentication Method, as described above, and/or custom authentication flow scripting. If your site supports only two authentication methods, and one is the first factor for the other (second factor only) method, then configuring an Initial Authentication Flow will likely satisfy your needs, and the second factor only flow can perform only the second factor, knowing that the first factor's Principal is already available.

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

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

Please Share

If you build such a second factor flow, configurable or otherwise, please share it with the community. We'll immortalize you on this wiki page.

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.

Excerpt from relying-party.xml

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

Browser not supported