User Authentication and Subject Identifiers in Shibboleth
This section deals with end-user authentication at the IdP and the various means through which this may occur and be transmitted to the SP. For information regarding server components identifying each other, please refer to the PKI & Credentials and Relying Parties & Federations sections for more information.
Shibboleth handles user authentication by identifying users through protection of the SSO handler via Apache or Tomcat, then translating this identity into a useful inter-realm context. Various forms of identity may be passed either as SAML subject identifiers or as attribute name/value pairs. Each may be necessary in some cases. SAML 2.0 and Shibboleth together support 3 different subject identification methods, each representing a different form of identity. Support of various subject identifiers must be stated in metadata for interoperability.
- Handle: Traditional Shibboleth functionality involves passing of a temporary, non-identifying opaque handle that is used to associate a browser user accessing the SP with a principal at the IdP. The initial SAML authentication assertion will contain a
handle. Forms of identity may then be sent via the SAML attribute assertion as individual attributes, such as
- Persistent Identifier: This special type of identifier is intended to provide a way to repeatedly and consistently identify a user at a SP without revealing any identity information regarding that user's identity or allowing that SP to share this information in a useful way. This means that each persistentID is unique to the combination of three entities, but that the IdP is expected to send the same persistentID to any given SP when the same principal is accessing it. There may be intricate auditing issues involved with use of persistentID's because mappings from pseudonyms to identifiable principals is only possible at the IdP, while some SP's may wish to retain access information for a period of time. This is not possible unless the corresponding IdP retains these mappings for that same period of time. Your federation may define additional rules defining the policy surrounding use of this type of name identifier.
- Principal Name: The most straightforward form of identity may also be the most useful for SAML interoperation with other products. The user's principal name scoped to the security domain is sent in the Subject field of the initial Authentication Assertion. It is also the least private mechanism, as anyone who can be issued an authentication assertion under this name mapping will by definition know the username. There may be situations where it is important to preserve the user's privacy by not releasing their principal name in the initial SAML authentication assertion, passed from the SSO handler to the SP, or a form of identity different from principal name is necessary, such as EPPN. This may be done by using handle-based flows and later supplying the principal name in a separate attribute.
Name identifiers passed in the subject of the SAML assertion can also be used as attributes for access control decisions. The
format defined in the name mapping element can be mapped by an attribute acceptance policy to a header.
Shibboleth does not include a bundled authentication system as of 1.3. One that supports some form of single sign-on and is capable of populating
REMOTE_USER must be used to protect the SSO handler. Everything from Apache's included mod_auth to sophisticated WebISO systems such as Pubcookie and CAS will work. Shibboleth 2.0 will provide authentication functionality as well as an API for use of other authentication mechanisms.
Name mappings allow definition of different subject name generation and passing mechanisms for different sets of relying parties. They are defined in individual
NameMapping elements and referenced by placing an
HSNameFormat element within
RelyingParty elements. These URN's are passed to the service provider to allow it to decide how to handle the authentication assertion and subsequent session generation and management.
This element defines a name mapping system to create SAML assertion subject names for users; in standard Shibboleth, this will be the creation of a handle to be given to the SP and understood by the assertion query handler. Separate Java classes may be defined for customized name mappers.
formatspecifies the type of subject identifier that is being passed in this assertion to inform the SP how to handle the assertion. There is a set of common name identifiers listed below, but arbitrary new name identifiers may be defined for local identifiers as long as the SP and IdP agree on the semantics.
Traditional Shibboleth handles are specified using this URN, and should never be used for access control decisions.
X.509 distinguished names, such as would be found in the subject of a certificate. GridShib utilizes this format.
It is recommended that email addresses not be used as identifiers except for compatibility with commercial products; they can be improper identifiers and should be passed as attributes.
The identifier is a MS UPN as used for ADFS Integration.
handleTTLspecifies in seconds how long a given
handle will be considered valid; an expired handle will require the user to
obtain a new handle and possibly re-authenticate. This field is only valid if
Shibboleth handles are being used, e.g.
urn:mace:shibboleth:1.0:nameIdentifier. Consult your
federation guidelines for guidance on the population of this field.
idis used by
NameIDelements to refer to this element and must
typedictates how name identifiers are passed in back channels from the SSO handler to the attribute authority. The valid types are:
CryptoHandleGenerator: Shibboleth handles will be passed using symmetric encryption. If this is specified, keystore information must be specified using one
KeyStorePasswordelement, and optionally a
Principal: Shibboleth will use the primary unique identifier for the individual and not generate a handle.
SharedMemoryShibHandle: Shibboleth will use a shared in-memory repository.
Apache-based User Authentication
In Shibboleth 1.3, the interaction between the IdP and an Apache-based local authentication system is implemented by providing the SSO handler with the identity of the browser user through
REMOTE_USER . Any authentication system that is capable of protecting a block of webspace using
httpd.conf for the SSO handler and populating the
REMOTE_USER header variable is compatible with Shibboleth. This associates the appropriate authentication mechanism with the URL of the SSO handler servlet, ensuring users must authenticate and that the principal name is passed to Shibboleth. The following example demonstrates use of a very basic authentication method with the IdP:
.htaccess files cannot be used for this purpose because URL's are "virtualized" by Tomcat.
It is critical to ensure that principal names are being successfully passed between Apache and Tomcat via mod_jk or mod_jk2. For mod_jk2, the parameter
request.tomcatAuthentication="false" must be present in either
workers2.properties or as an attribute of the proper
<Connector> element in the main Tomcat
server.xml file. For mod_jk,
tomcatAuthentication="false" must be present in the
<Ajp13Connector> configuration element to ensure that the user's identity is passed from Apache to the servlet environment.
Java-based User Authentication
Specific information is available for deploying an IdP entirely within Tomcat.
There are many user-interface issues associated with using built-in Java-based authentication, particularly in Tomcat 5.5. Some session features and proper behavior in situations such as users pressing the back button are lacking.
It bears mentioning that this does not imply getting rid of Apache entirely for several reasons. Most Java-based webservers are relatively immature and slow. For Shibboleth 1.3 and below, Apache and mod_jk(and usually port 8443) are still recommended for SSL protection of the attribute query handler in order to pass SP credential information to the IdP for proper attribute release.
mod_ssl is a good deal faster than Java at processing credentials, and there is no guarantee of the ability to detach JSSE credential processing sufficiently to allow multi-federation support. Loads have not been witnessed in production deployments that would make this an issue yet.
The default Tomcat user authentication will work in some deployments, but this is not generally useful because these principals aren't necessarily linked to a attribute source.
In order to protect the SSO servlet using Tomcat authentication, you need to put a security-constraint and matching login-config on the SSO servlet in
(FORM-based authentication is preferred because of security reasons: it is session-based and not browser-based)
Tomcat 5.5.15 and later have "fixed a bug" that previously allowed any authenticated server without a
role to access a resource if there were no constraints in the associated
web.xml . This has been changed to default deny, so now the following might have to be added to
web.xml as a workaround. Additionally,
<role-name> has to be set to
Person . Also
userRoleName="objectclass" must be added as an attribute to the
<Realm> element so the realm returns the
objectclass es as the user's roles (see below).
You should also attach a realm to the security constraint by commenting out the
<Realm className="org.apache.catalina.realm.UserDatabaseRealm" debug="0" resourceName="UserDatabase"/> element in Tomcat's
server.xml . If you wan to use LDAP-based Tomcat authentication, add a new
Realm element utilizing
JNDIRealm such as the following:
There are many deployment-specific values that will need to be changed here to fit your own environment, most of which are self-explanatory. In this particular example, users login using their e-mail address as a principal name. Also note the value of the
debug attribute, which defines how detailed logging of authentication events is. A value of
99 is most appropriate for production use.
If LDAP over SSL is used, make sure that the URL is
ldaps:// . No other configuration details need to be changed.
End-user Certificate-based Authentication
Shibboleth supports client certificate authentication by utilization of a filter that relies on the web server to do all processing to ensure that the certificate is both valid and appropriate for the application. An example deployment descriptor is included with the Shibboleth distribution at
To enable the filter, add the following to the deployment descriptor (=web.xml=):
By default, the filter pulls the principal name out of the
CN of the cert's
Subject by using regular expression grouping. This may be done using patterns such as:
The servlet filter will accept two initialization parameters,
matchGroup , that can be used to extract the principal name differently.