Legacy File(s): conf/handler.xml, login.jsp, others
Current File(s): conf/authn/*, views/login.vm
Format: Native Spring
Authentication has been substantially redesigned in 3.0 to make customization easier and add more capability, but significant compatibility has been maintained when using JAAS (UsernamePassword) or container-based (RemoteUser) authenticaton.
The files in conf/authn/ collectively configure authentication generally, and the specific mechanisms that are built-in to the software. Authentication is heavily Web Flow-based; selection of the mechanism to invoke and each individual mechanism are implemented as flows.
Authentication flows are the equivalent to 2.x LoginHandler plugins and these flows are better integrated into the overall IdP architecture and make use of Web Flow's support for views and state transitions instead of the servlet-based design of 2.x.
More comprehensive support for complex mechanism selection criteria has been implemented; assuming prior configuration, all of the SAML operators (exact, minimum, maximum, better) for requesting authentication context types are now supported.
While fully decoupled from the authentication layer, session management is obviously related. Most of the session management configuration is automatic, and the properties that can override the defaults are shown below. It's possible to fully disable the session mechanism and turn off SSO globally with a single property. Note that unlike 2.x, the default session mechanism in 3.0 is a client-side storage solution using a cookie. This mechanism depends on the configuration of a local secret key in a keystore.
The 2.x handler.xml file that defined login handlers and authentication "methods" is no longer supported. Compatibiliy is provided instead for specific aspects of integrating authentication with the local environment.
If the 2.x "UsernamePassword" login handler is used, the 3.0 equivalent is the "authn/JAAS" flow, and the same JAAS configuration can of course be used. By convention this configuration is placed in conf/authn/jaas.config and the legacy "ShibUserPassAuth" login configuration name is used (though this can be changed). Unlike 2.x, the UI for password-based login is no longer strictly JSP-based, but is now a Web Flow view, which can be Velocity or JSP. Using an older login.jsp file will generally require some changes.
If the 2.x "RemoteUser" login handler is used, the 3.0 equivalent is the "authn/RemoteUser" flow, and for compatibility this has been architected to use the same protected endpoint (/Authn/RemoteUser) as in 2.x. This allows for reuse of existing container authentication configuration.
In most cases, existing relying-party.xml
defaultAuthenticationMethod settings will result in the expected login flows running, once the flow to use for password-based authentication is established. Generally this will require setting an idp.property to activate the right flow(s) (see below).
So in short, activate flows with the "idp.authn.flows" property, transfer JAAS or web.xml and container configuration over, and you should have basic compatibility working, apart from the actual login UI for JAAS-based authentication.
Authentication configuration is divided into general and mechanism/flow-specific parts. Separate topics exist for each mechanism included.
General configuration is in conf/authn/general-authn.xml and conf/authn/authn-comparison.xml.
The former is where all possible login flows are described to the system. They can be enabled and disabled with an idp.property so even if defined, they can be deactivated without editing the XML. The latter is used to describe relationships between mechanisms to support protocols like SAML that can include requests for specific authentication methods.
The conf/authn/general-authn.xml file contains a Spring list bean called shibboleth.AvailableAuthenticationFlows. Each mechanism for authentication is called an authentication flow, and each flow has a descriptor bean inside this list. Descriptors are of a specific class, and include a number of properties that control whether a mechanism will be used for specific requests.
The parent bean for all flows is defined in a system file and looks like this:
The comments in the file and the example above describe some of the defaults, and illustrate how to define a non-password-based mechanism (IPAddress), 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 URIs that represent different kinds of authentication. They can also be used to represent more advanced concepts like "Assurance" which go beyond just the technology.
To associate these constants with a flow, beans are used that inherit from one of the following built-in beans:
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 (described elsewhere) involves not only describing the flow in this list, but ensuring the
id matches a flow definition created inside flows/authn/.
Even if a flow is defined to the system, it is not necessarily available for use at runtime. The overall list of flows is controlled using an idp.property (see below) that lists the actual flows to enable. In addition, a list of flow IDs can be configured per-profile, per-relying-party using the
authenticationFlows property on a profile configuration bean. Any flow not enabled is simply ignored.
The conf/authn/authn-comparison.xml file is an advanced configuration file used to support the matching process that allows a request or a default configuration to indicate which mechanism to use. In 2.x, only "exact" matching was supported, and each login handler typically supported only a single hardwired "method" value for comparison purposes. In 3.0, this has been generalized to support "inexact" matching. The purpose of this file is to define the relationships between authentication types in order to support this inexact matching.
The support for this is not limited to SAML in the design, but since SAML is the only implemented case, there are classes and beans defined to manage the relationships and support the operators that are specific to that case.
Exact matching is automatic; this is used to restrict the flow selected when a SAML 2 request specifies "exact" matching in an
<RequestedAuthnContext> element, or if nothing is requested but the profile configuration includes a
To make inexact matching possible, you have to define the matching rules. These rules apply only to SAML 2 requests. While you can define matching rules for AuthnContextDeclRef constants, these are rarely used in practice, and you will generally only want to define rules for class references. There are beans predefined and registered for each of the matching types possible:
The latter two, if not modified, still allow degenerate support by treating the request as equivalent to "exact", but "better" matching won't succeed without comparison rules added. The file includes an example of how to define such rules. Each bean contains a property to set with a map of values that might be requested and a corresponding list of values that satisfy the request.
Note that any values you map to in these beans MUST be associated with one or more flows in the general-authn.xml file. Flows must be able to satisfy a requirement, and they must produce a result that carries a required value, or the end result will fail anyway.
Flows provided with the alpha software include:
Because there are different types of login methods, most actual configuration is in per-method Spring configuration files, but there are a couple of general properties used, and a larger set of properties that control the management of sessions, which are of course tightly related to authentication.
Worthy of note, you can switch to server-side storage of user sessions (essentially similar to the 2.x default) using the "idp.session.StorageService" property. Also, we do not have installation support yet for generating the random encryption key for client-side session storage, so be aware that unless you change the key yourself, it's a dummy key.
The most important property to note, and the only one that MUST be set is the "idp.authn.flows" property. This is a regular expression that identifies the flows in general-authn.xml to enable. The expression applies only to the suffix of each flow ID (omitting the authn/ prefix), and the simplest way to express this is with an | separated list of the flow names, e.g., flow1|flow2|flow3