AuthenticationConfiguration
File(s): conf/authn/*, conf/c14n/*
Format: Native Spring, Properties
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). Most individual login flows have been converted into modules that can be enabled and disabled. This is addressed within the pages that document all the flows.
There are significant differences in the OOB approach to configuration for new installs of V5 compared to systems upgraded from before V4.1 that remain largely unmodified since that timeframe. The V5 documentation focuses on the newer style of configuration and omits the legacy material, though it remains backwardly compatible. Older reference material can still be found in the original V4 documentation.
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.
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 (now legacy) general-authn.xml file are typically settable now with a 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 other) representations of authentication "classes" 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 more detailed 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 expressed 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.
Login Flows
Login flows provided with the software are listed below with links to their associated documentation:
SAML (i.e. Proxying to other SAML IdP(s))
Post-Login Subject Canonicalization
After a successful login takes place, the IdP needs to be able to establish an "official" username to represent the subject throughout the system in order to disambiguate subjects from each other. Chiefly this is needed so that the IdP can detect when the identity of the subject has changed/switched, usually because of the use of shared computers. It also allows you to build an AttributeResolverConfiguration that can count on the form of the subject's name when looking up entries in directories or databases, essentially offloading some of the complexity that would otherwise end up in the attribute resolver logic/configuration (e.g., more complex LDAP search filters or SQL).
This particular use of subject canonicalization (i.e., c14n) is referred to as post-login c14n and the chief input is an instance of a Java Subject, which is a fairly open-ended class that can contain any number of custom Principal objects and collections of public and/or private credentials. The IdP generally doesn't make much use of the credential collections, but does populate the Principal collection and uses that heavily.
With many login flows, the Subject is often fairly simple and often contains a single UsernamePrincipal that carries a username set by the login flow, often directly or based on something entered by a user. In the simple case, the "right" canonical value may just be that name, and nothing needs to be configured, it will simply happen automatically. In less common cases, you may need to configure a more advanced c14n method to do your bidding.
The overall configuration of these methods and how they are executed after authentication varies by IdP version, and so is discussed in a couple of subtopics.
The post-login c14n flows provided with the software are listed below:
The first two are fairly elementary to use, while the third requires additional configuration to operate sensibly, and the fourth is for specialized use when proxying authentication to a different SAML IdP (and, even then, is often unneeded unless you intend to leverage an incoming <NameID> element as the basis of c14n). The last one is an extension point allowing simpler development of custom methods.
Subject Decorators
There is another hook that can be used to plug in Java or scripting code to perform customization of the Java Subject by a flow before the c14n step occurs. The advantage of this hook is that it's sometimes easier to write that bit of code and have it produce, for example, a UsernamePrincipal, than to create a new c14n feature from scratch, though this is less true in V5.2+.
This hook is usable by defining a bean with the signature BiConsumer<ProfileRequestContext,Subject>, and identifying it in conf/authn/authn.properties via a property of the form idp.authn.<flow>.subjectDecorator
Advanced Topics
Reference
V4 Compatibility
Authentication is substantially compatible with V4 except for the removal of some advanced features that were replaced by the MFA login flow and the LDAP login flow’s configuration. The LDAP wiring that was exposed in older versions is no longer compatible in most cases and has to be removed, essentially be starting over configuring LDAP settings from scratch.
The other major differences between V4 and V5 are reflected in the 4.0 to 4.1 transition and are not new to V5.