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), 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.
Login Flows
Login flows provided with the software are listed below with links to their associated documentation:
Post-Login 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 lookup logic.
This particular use of subject canonicalization (or c14n) is referred to as post-login c14n and the input is an instance of a Java Subject, which is a fairly open-ended object 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 most login flows, the Subject is typically fairly simple and often contains a 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 subflow to do your bidding, or create one of your own design.
The post-login c14n flows provided with the software are listed below:
The first two are enabled by default, while the third requires additional configuration to operate sensibly and the fourth is for specialized use when proxying authentication to a different SAML IdP.
Subject Decorators 4.1
Lastly, V4.1 and above include another hook that can be used to plug in Java 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 easier to write that bit of Java code and have it produce, for example, a UsernamePrincipal, than to create a new c14n flow from scratch. This hook is usable by defining a bean with the signature BiConsumer<ProfileRequestContext,Subject>, and identifying it in conf/authn/authn.properties with a property of the form idp.authn.<flow>.subjectDecorator
Advanced Topics
Reference
V3 Compatibility
Authentication is substantially compatible with V3 except for the removal of some advanced, deprecated features that are replaced by the MFA login flow.
The Password login flow has been enhanced with more flexibility but is designed to be backward-compatible with the simpler options from V3 and in most cases should not require configuration changes, with the possible exception of the LDAP back-end if you have made significant customizations to the ldap-authn-config.xml file.
V4.1 adds a large number of changes that, while backward-compatible, provide alternative property-based ways to configure many standard features without the need for as many XML files. The general section includes material on how to migrate to this approach.