Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

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.

Compatibility Notes

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 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 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.

General Configuration

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:

Parent bean for Authentication Flow Descriptors
    <bean id="shibboleth.AuthenticationFlow" abstract="true"
        <property name="supportedPrincipals">
                <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" />

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:

  • shibboleth.SAML2AuthnContextClassRef
  • shibboleth.SAML2AuthnContextDeclRef
  • shibboleth.SAML1AuthenticationMethod

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. 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 (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.

Comparison Configuration

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 defaultAuthenticationMethod collection.

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:

  • shibboleth.BetterClassRefMatchFactory
  • shibboleth.MinimumClassRefMatchFactory
  • shibboleth.MaximumClassRefMatchFactory

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

# Settings for internal AES encryption key
idp.sealer.storeType = JCEKS
idp.sealer.storePath = creds/sealer.jks
idp.sealer.storePassword = password
idp.sealer.alias = idpSecretKey
idp.sealer.keyPassword = password

# Set to shibboleth.Conditions.False to disable the IdP session layer
#idp.session.enabled = shibboleth.Conditions.True
# Set to "shibboleth.StorageService" for server-side storage
#idp.session.StorageService = shibboleth.ClientStorageService

# Size of session IDs
#idp.session.idSize = 32
# Bind sessions to IP addresses
#idp.session.consistentAddress = true
# Inactivity timeout
#idp.session.timeout = PT60M
# Extra time to store sessions for logout
#idp.session.slop = 0
# Tolerate storage-related errors
#idp.session.maskStorageFailure = false
# Track information about SPs logged into
#idp.session.trackSPSessions = false
# Support lookup by SP for SAML logout
#idp.session.secondaryServiceIndex = false
# Length of time to track SP sessions
#idp.session.defaultSPlifetime = PT2H
# Select alternate implementation for step that determines what results are active
#idp.session.activeResultExtraction = net.shibboleth.idp.session.impl.ExtractActiveAuthenticationResults

# Regular expression matching login flows to enable
idp.authn.flows = IPAddress|LDAP

# Default lifetime and timeout of various authentication methods
#idp.authn.defaultLifetime = PT60M
#idp.authn.defaultTimeout = PT30M

# Whether to prioritize "active" results when an SP requests more than
# one possible matching login method (V2 behavior was to favor them)
#idp.authn.favorSSO = true



  • No labels