The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.


Configuring User Authentication

In order to support SAML 2 authentication request features like passive and forced authentication and authentication contexts, the IdP must do some amount of processing prior to invoking whatever mechanism(s) are in place to authenticate users. This is different than previous versions of Shibboleth where the user was authenticated prior to the request reaching the IdP.

Before proceeding it would be beneficial to understand the relationship between authentication methods and the user's session.

Define the Login Handler

Each authentication mechanism is configured differently, as each has different requirements. The following authentication methods are supported:



Remote User

Sets the principal name in the IdP to REMOTE_USER as determined by the web server or container's authentication, similar to Shibboleth 1.3.

External Authn

Login handler that delegates to another authentication system to perform the actual user authentication and identification.


Presents the user with an authentication page and then checks the entered username and password against an LDAP directory or Kerberos 5 domain.

IP Address

Checks the user's IP address against a given range to identify the user as a pre-determined principal.

Previous Session

Called when the user's existing session is used as the authentication mechanism (i.e., when the IdP is performing an SSO-based sign-on.)

Authentication Method Selection

The IdP supports the use of multiple authentication methods at one time. When using SAML 2.0, a service provider may require one of numerous authentication methods be used by supplying a list of acceptable methods in its request. In SAML terms, these methods are expressed as <AuthnContextClassRef> or <AuthnContextDeclRef> elements.

If the IdP is configured for one or more of the methods requested by the SP, then that method may be used. If the Service Provider does not specify a particular method, and the user does not have an existing session, then the default method identified on the relying party's configuration is used. If no default is identified there, the IdP will choose one of the available methods; the way this choice is made is unspecified and you should not rely on it being the same from release to release.

If the user has an existing session, and that session indicates that there is an active authentication method that meets the SP's requirements, then the PreviousSession login handler is used if it is configured. This is what gives Shibboleth its SSO support. If the SP does not request a particular method in its request, note that the default method in the configuration is NOT consulted when determining whether to honor active methods. In this case, any active method can be used to satisfy the request.

If the SP requests more than one possible matching class or declaration to use, then (assuming the PreviousSession handler is enabled for SSO), the IdP will check for an active method in the user's session that satisfies one of the requested values and will use that if possible. Otherwise it will select a matching handler to use for authentication.

A note about the built-in handlers: for security reasons, the handlers are configured to cross-check that the method they supply to the user's session matches the method that an SP asked for. This results in a limitation for the built-in handlers such that they support only a single method type in a given configuration, rather than allowing for more than one at a time. A custom login handler can circumvent this limitation by supporting multiple methods at the same time (even if those methods are really just different ways of expressing the same underlying behavior by the handler). This is important for scenarios in which different SPs are expressing or expecting different values for the same underlying mechanism.

Session Lifetime

The session lifetime is configured in the IDP_HOME/conf/internal.xml file. Locate the shibboleth.SessionManager bean. Its second constructor argument is the inactivity timeout, in milliseconds, for the session. By default it is 30 minutes.

Admittedly, this is a totally confusing and poorly represented setting. It will be changed in a future release.