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 NameIdentifier of type handle . Forms of identity may then be sent via the SAML attribute assertion as individual attributes, such as eduPersonPrincipalName .
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

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.

<NameID nameMapping="id"/>

Individual RelyingParty elements may contain this element. The set of NameID elements within a RelyingParty element serve as an ordered list of valid name mappings that are supported for interactions with this relying party. During SSO transactions, the IdP determines the appropriate mapping to use by negotiating between what the SP would like to receive as indicated by metadata and what the IdP can offer. In attribute queries, the IdP will reject queries that don't contain a name identifier format that is configured for the relying party. If this element is not present, default Shibboleth handles will be used.

<NameMapping xmlns="urn:mace:shibboleth:namemapper:1.0" format="URI" handleTTL="seconds" id="string" type="type" class="javaclass"/>

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.

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

`urn:mace:shibboleth:1.0:nameIdentifier`	Traditional Shibboleth handles are specified using this URN, and should never be used for access control decisions.
`urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName`	X.509 distinguished names, such as would be found in the subject of a certificate. GridShib utilizes this format.
`urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`	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.
`http://schemas.xmlsoap.org/claims/UPN`	The identifier is a MS UPN as used for ADFS Integration.

handleTTL specifies 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. format is
urn:mace:shibboleth:1.0:nameIdentifier . Consult your
federation guidelines for guidance on the population of this field.
id is used by NameID elements to refer to this element and must
be unique.
type dictates 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 KeyStorePath element, one KeyStoreKeyAlias element, one KeyStorePassword element, and optionally a KeyStoreKeyPassword element.
- 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:

<Location /shibboleth/SSO>
	 AuthType Basic
	 AuthName "Supervillain University Login"
	 AuthUserFile /usr/local/apache/conf/user.db
	 require valid-user
</Location>

Note that .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 shibboleth-idp's web.xml .

<!-- Define a security constraint on this application -->
<security-constraint>
  <!-- the list of URL patterns that needs to be protected -->
  <web-resource-collection>
	 <web-resource-name>SSO servlet</web-resource-name>
	 <url-pattern>/SSO</url-pattern>
  </web-resource-collection>
  <auth-constraint>
	 <!-- allow all roles, a role has to be specified from Tomcat v5.5.15 and higher -->
	 <role-name>*</role-name>
  </auth-constraint>
  <!-- force all data to use SSL for transport -->
<!--
  <user-data-constraint>
	 <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
-->
</security-constraint>

<!-- Login configuration using basic authentication -->
<!--
<login-config>
  <auth-method>BASIC</auth-method>
  <realm-name>Shibboleth authentication required</realm-name>
</login-config>
-->

<!-- Login configuration using form-based authentication -->
<login-config>
  <auth-method>FORM</auth-method>
  <realm-name>Shibboleth form-based authentication</realm-name>
  <form-login-config>
	 <form-login-page>/login.jsp</form-login-page>
	 <form-error-page>/error.jsp</form-error-page>
  </form-login-config>
</login-config>

(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 shibboleth-idp 's 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).

<!-- Security roles referenced by this web application -->
<security-role>
		  <description>All Users</description>
		  <role-name>person</role-name>
</security-role>

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:

<Realm className="org.apache.catalina.realm.JNDIRealm"
	 connectionURL="ldap://example-ldap-server.be"
	 connectionName="uid=<bind-uid>,ou=people,dc=domain,dc=be"
	 connectionPassword="hahaha"
	 userBase="ou=people,dc=domain,dc=be"
	 userSubtree="true"
	 userSearch="(mail={0})"
/>

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 $SHIB_HOME/webAppConfig/origin-client-cert.xml .

To enable the filter, add the following to the deployment descriptor (=web.xml=):

<filter>
	<filter-name>
		Client Cert AuthN Filter
	</filter-name>
	<filter-class>
		edu.internet2.middleware.shibboleth.utils.ClientCertTrustFilter
	</filter-class>
</filter>

<filter-mapping>
	<filter-name>
		Client Cert AuthN Filter
	</filter-name>
	<url-pattern>
		/SSO
	</url-pattern>
</filter-mapping>

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:

regex: '.*CN=([^,/]+).*' match group: 1

The servlet filter will accept two initialization parameters, regex and matchGroup , that can be used to extract the principal name differently.