AuthenticationConfiguration

File(s): conf/authn/*, conf/c14n/*
Format: Native Spring, Properties

1 Overview
2 General Configuration
3 Login Flows
4 Post-Login Canonicalization
5 Advanced Topics
6 Reference
7 V3 Compatibility

Overview

The files in conf/authn/ collectively configure authentication both generally and the specific mechanisms that are built-in to the software. Authentication is heavily based on Spring Web Flow; selection of the mechanisms to invoke and each individual mechanism are implemented as "subflows" that run inside of the top-level web flows that service requests.

Login subflows make use of SWF's support for presentation views and state transitions instead of a servlet-based design. However, because of SWF's handling of URLs, there are cases in which use of a subflow exclusively is problematic, and so a defined External method for branching out to a servlet design is also provided. Some methods are built on top of that same approach when necessary.

Complex SP-driven mechanism selection criteria are supported; assuming prior configuration, all of the SAML 2 operators (exact, minimum, maximum, better) for requesting authentication context types can be supported, though exact matching is obviously much cleaner and is preferred.

While fully decoupled from the authentication layer, session management is obviously a related topic. Most session management configuration is automatic, and the properties that can override the defaults are documented in the SessionConfiguration topic. It's possible to fully disable the session mechanism and turn off SSO globally with a single property. The default session mechanism is a client-side storage option using encrypted HTML Local Storage or cookies. This mechanism depends on the configuration of a secret key shared by all IdP servers.

Authentication configuration is divided into general and mechanism-specific parts. Separate topics exist for each mechanism included with the software and certain other subtopics.

You should also review the AuthenticationFlowSelection topic for an explanation of how the system actually decides which mechanism to use if you enable more than one at a time. Most modern deployments tend to enable only a single mechanism, or use the MFA flow to combine other methods, but it's still important to understand the underlying design.

The Authentication topic contains a more extensive discussion of the design of this layer, and how to use and extend it (e.g. how to build a custom login flow of your own design).

This is the longest and most complex part of the documentation and it should be, because authentication is the most important thing the IdP does.

General Configuration

Each mechanism for authentication is called an authentication flow (or login flow), and each flow has a corresponding bean defined inside the system. These beans are of a specific class, AuthenticationFlowDescriptor, and include a number of settings that influence whether a mechanism can be used for specific requests and control other behavior.

There are significant differences in the OOB approach to configuration for new installs of V4.1 compared to V4.0 or upgraded systems (in succinct terms, older versions required explicit, visible definition of AuthenticationFlowDescriptor beans to allow customizations while V4.1 hides the beans and relies on properties for many customizations). The tabs below (and elsewhere in the page) provide the relevant information for each version, and where applicable information on taking advantage of new approaches after upgrading.

The authn/general-authn.xml file is where all supported login flows are described to the system. They can be enabled and disabled with a property, so even when defined they can be globally activated or deactivated without editing this file.

The file contains a Spring list bean named shibboleth.AvailableAuthenticationFlows containing a bean for each flow.

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.

Even if a flow is defined to the system, it is not necessarily available for use at runtime. The overall list of enabled flows is controlled using the idp.authn.flows property that expresses the flows to enable. Any flow not enabled will be ignored, except in special cases such as direct use from within the MFA flow.

The parent bean for all flows is defined in a system file and looks like this:

Parent bean for Authentication Flow Descriptors

    <bean id="shibboleth.AuthenticationFlow" abstract="true"
            class="net.shibboleth.idp.authn.AuthenticationFlowDescriptor"
            p:resultSerializer-ref="shibboleth.DefaultAuthenticationResultSerializer"
            p:passiveAuthenticationSupported="false"
            p:forcedAuthenticationSupported="false"
            p:nonBrowserSupported="true"
            p:lifetime="%{idp.authn.defaultLifetime:PT60M}"
            p:inactivityTimeout="%{idp.authn.defaultTimeout:PT30M}"
			p:principalWeightMap="#{getObject('shibboleth.AuthenticationPrincipalWeightMap')}">
        <property name="supportedPrincipals">
            <list>
                <bean parent="shibboleth.SAML2AuthnContextClassRef"
                    c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" />
                <bean parent="shibboleth.SAML2AuthnContextClassRef"
                    c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:Password" />
                <bean parent="shibboleth.SAML1AuthenticationMethod"
                    c:method="urn:oasis:names:tc:SAML:1.0:am:password" />
            </list>
        </property>
    </bean>

The comments in general-authn.xml and the system bean above describe some of the defaults, and illustrate how to define a non-password-based mechanism (IPAddress or X509), which requires overriding the supportedPrincipals property to prevent misuse.

This property is used to associate a flow with any number of custom objects that represent, in the specific case of SAML, SAML 1 AuthenticationMethod or SAML 2 <AuthnContextClassRef> or <AuthnContextDeclRef> constants. These are URI constants that represent different kinds of authentication. They can also be used to represent more advanced concepts such as identity proofing and auditing requirements which go beyond just technology choices.

To associate these constants with a flow, beans are used that inherit from one of the following built-in beans:

shibboleth.SAML2AuthnContextClassRef
shibboleth.SAML2AuthnContextDeclRef
shibboleth.SAML1AuthenticationMethod

As a caution, if you add a custom flow or make use of one of the technology-independent flows in a way that is not password-based, don't forget to override the supportedPrincipals property, or you will create problems for any SPs that are attempting to request stronger authentication methods. It's very easy to accidentally "lie" to the world by misconfiguring the IdP, because the software can't read your mind to understand your intentions, and it only knows what you tell it. The AuthenticationFlowSelection topic contains a full explanation of the selection process.

Note that if you associate more than one such constant/bean with a flow, the IdP will ordinarily pick one at random to use as a SAML "result" when it builds an assertion, assuming the SP didn't request a specific one. If you need to guarantee that a particular one will be used as a default, you can assign "weights" to them in a map bean that's defined in the general-authn.xml file named shibboleth.AuthenticationPrincipalWeightMap.

V4.1 introduces Modules, and the individual login flows have been converted into modules that can be enabled and disabled. This approach is addressed within the pages that document all the flows.

The primary means of configuring authentication, and particular login flows, is via the file authn/authn.properties. Most of the settings in this file are commented out and defaulted, so setting the ones you need generally involves uncommenting them. There are also many more advanced properties possible to define that are not present in the default file and are described in the various Reference sections for each login flow. Essentially, any bean property that used to be settable via the general-authn.xml file are typically settable now with a Java property.

Even though a login flow exists, it is not necessarily available for use at runtime. The overall list of enabled flows is controlled using the idp.authn.flows property that expresses the flows to enable as a regular expression (usually of the form "Method1|Method2|Method3"). Any flow not enabled will be ignored, except in the case of direct use from within the MFA flow.

Every login flow known to the system auto-registers itself with defaults that can be overridden by setting corresponding properties, generally with the naming convention "idp.authn.Method.setting".

For reference or for those whose understanding may be aided by seeing the actual wiring, you can see the XML that allows all the properties to slot in here, and in the Reference section of each individual login flow's documentation page, but it's not essential to using the properties or understanding what they do.

Generally the settings that are supported by properties have simple syntaxes that lend themselves to property use, or will identify the name of a bean that provides more complex behavior. A notable exception to this simple syntax are the "supportedPrincipals" properties, which are used to attach SAML (or in theory other) representations of authentication "types" to the login flows so that the system is able to abstractly recognize when a particular login flow can be used to satisfy a particular request (e.g., how to tell that a request for certificate-based authentication should not attempt to use the Password flow).

To avoid the need for Java beans, a string-based parsing trick is used to consume this property in the form of a comma-delimited list of strings, typically expressed as a multi-line property for readability. The syntax for this should be apparent from the commented examples, but each value is a prefix (typically "saml2" or "saml1") and a principal value separated by a slash. This will attach the corresponding AuthnContextClassRefPrincipal or AuthenticationMethodPrincipal beans in the configuration.

As a caution, if you add a custom flow or make use of one of the technology-independent flows in a way that is not password-based, don't forget to override the corresponding supportedPrincipals property, or you will create problems for any SPs that are attempting to request stronger authentication methods. It's very easy to accidentally "lie" to the world by misconfiguring the IdP, because the software can't read your mind to understand your intentions, and it only knows what you tell it. A complete explanation of how the selection process works is here.

Note that if you associate more than one supportedPrincipal value with a flow, the IdP will ordinarily pick one at random to use as a SAML "result" when it builds an assertion, assuming the SP didn't request a specific one. If you need to guarantee that a particular one will be used as a default, you can assign "weights" to them in a map bean that's defined in the authn-comparison.xml file named shibboleth.AuthenticationPrincipalWeightMap

Finally, note that in the rare case that multiple flows are enabled without making use of the MFA flow to control order, the various properties with the "order" suffix can be used to attach a non-default order value to particular flows, with lower values sorted before higher. You usually won't need to bother with this.

Upgrading from V4.0 and Earlier

The information above focuses on the "as-delivered" V4.1 defaults, which are considerably changed from earlier versions, and apply out of the box only to new installs. Upgraded systems, while they may contain combinations of old and new files, by design function the same as they used to for compatibility, and the new bits are generally ignored/overridden by the older settings.

With V4.1, the use of XML to configure many basic features has been minimized and replaced by simpler properties, with a new file (authn/authn.properties) added. Most of the properties in this file are commented out and largely ignored because they are superseded by the beans in the original authn/general-authn.xml file, which has been removed from new installations (but is still processed when present).

A handful of authentication-related properties that were in idp.properties in older releases have been moved to the new authn.properties file in this version for better locality of reference, but they are commented and authn.properties is not automatically processed by upgraded configurations, preventing any conflicts.

With this release, all beans of type AuthenticationFlowDescriptor are automatically recognized, obviating the need to define them by hand, which was the main purpose of the XML file. Instead, all of the built-in login flows are wired up internally with properties used to control settings rather than XML.

For compatibility and for those who favor XML, any flow descriptor bean inside a list named shibboleth.AvailableAuthenticationFlows with a particular p:id will supersede the internally wired bean for that flow (and the log notes this at startup). A bean defined stand-alone outside the named list will not reliably replace the internal version.

For those wishing to migrate from the older approach to the newer approach (though this is not required), removing authn/general-authn.xml, setting idp.searchForProperties to "true" in idp.properties, and setting any properties corresponding to non-default settings applied in the XML will provide equivalent behavior (and hopefully be easier to understand and adjust down the road).

Another generally minor function of the XML file was to establish the order by which the IdP would attempt to use any methods applicable to a request. If this matters, a property for each method with the "order" suffix (e.g., idp.authn.Password.order) can be set to a value other than the default to sort methods relative to each other. Lower values are tried first.

As a minor note, the bean named shibboleth.AuthenticationPrincipalWeightMap was moved from general-authn.xml (which was removed) to authn-comparison.xml (which remains). It doesn't matter which file it's in (and any given system when appropriate install/upgrade procedures are followe