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.
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 comments in the file 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 is discussed further below.
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.