In order to make your application use MIT Touchstone, or Shibboleth, for authentication, several steps have to be performed. MIT Information Services offers consulting services to make this process easier. However, many people at MIT are able to perform each of these simple steps with minimal intervention from IS&T.

The information below is intended to help guide you through your configuration.

Shibboleth SP version information

IS&T currently supports new customers intending to use Shibboleth 2.x. New installations must use Shibboleth 2.x based SPs.

As of June 30, 2010, the Internet2 Shibboleth development team no longer promises to supply security updates for version 1.3x. The 1.3x version is now considered end of life.

We strongly recommend that any sites still running Shibboleth 1.3 in production plan to upgrade to the current version of Shibboleth as soon as possible. This will protect against the possibility of a forced but unplanned migration from 1.3 should a security issue or incompatibility be discovered.

Information about migrating an existing Shibboleth SP 1.3x installation to version 2.x can be found at
https://wikis.mit.edu/confluence/display/TOUCHSTONE/Migrating+a+Shibboleth+1.3+SP+to+2.x

Using installers:

The most current installers from Internet2 can always be found at http://shibboleth.internet2.edu/downloads.html

The link provided above should be used if you are installing a 2.x Service Provider (SP). It is not necessary to download the -debuginfo, -devel, or -docs RPMs.

Some other Linux distributions also maintain binary installers available from the OS distribution point. If you have questions about other distributions please contact touchstone-support and indicate what operating distribution and version you are using.

Building from source:

The Touchstone team strongly recommends that you use the installers available from Internet2 or your operating system vendor.

However, if you need to build from source, please read the following pages:

Once you have built the software successfully, you will need to configure and customize it for use.

Certificate request and configuration

Before proceeding to "Configuration and customization for use" you should obtain a server certificate.

A server certificate, issued either by the MIT CA or a commercial CA, is required for SSL (https) traffic to your server; we strongly recommend using SSL for all Shibboleth-protected content. Please make sure that you use lower case server names in your certificate request. The server name within the certificate is case sensitive.

Information about how to generate a certificate request and where to send the request can be found in https://wikis.mit.edu/confluence/display/WSWG/How+to+acquire+and+verify+a+M.I.T.+x509+Server+Certificate

An MIT-issued server certificate can also be used by the Shibboleth SP when it authenticates to an IdP, though we will be transitioning to using a self-signed certificate for that purpose.

Ensure your system clock is accurate

The authentication request by the SP includes a timestamp, and the IdP verifies that the timestamp is current, to prevent replay attempts. Requests with an invalid timestamp (either too far in the past, or too far in the future), will be rejected by the IdP, resulting in an error. Therefore, it is essential that your server's system clock is accurate. On Linux servers, this is typically accomplished by running ntpd, the Network Time Protocol daemon. Please make sure that such time synchronization is configured on your server.

Configure the SP software for Touchstone

On a Linux server, the quickest way to get started is to copy the following files from the Touchstone locker (/mit/touchstone/config/shibboleth2-sp) into /etc/shibboleth:

  • attribute-map.xml
  • gen-shib2.sh
  • shibboleth2.xml.in

Note: If you do not have AFS installed on your server, then you can access the above files via http, either from a browser or using wget. The URL is http://web.mit.edu/touchstone/config/shibboleth2-sp/

Then run the gen-shib2.sh script, and answer the prompts, to generate shibboleth2.xml. For example:

# cd /etc/shibboleth
# cp /mit/touchstone/config/shibboleth2-sp/* .
# sh gen-shib2.sh

Note that any changes to the shibboleth2.xml, attribute-map.xml, and attribute-policy.xml files will be detected automatically, i.e. without requiring a restart of shibd.

Note: The gen-shib2.sh procedure described above is currently supported on Linux systems only; it should be portable to other UNIX-based systems with minimal effort. Please contact touchstone-support if you are using another operating system and having problems with the gen-shib2.sh script.

The $prefix/etc/shibboleth directory will contain apache.config, apache2.config, and apache22.config, which contain needed and example directives for Apache 1.3, Apache 2.0, and Apache 2.2, respectively; copy and/or include the appropriate file in your Apache config, and customize as needed.

The directory also contains a shibd init script for Red Hat (shibd-redhat) and Debian (shibd-debian) systems. The current Red Hat RPMs also install the init script into /etc/init.d/shibd, and adds it as a managed service.

On Solaris machines, the gen-shib.sh script will generate a shibd init script (from shibd.in); this should be installed into /etc/init.d, and configured to start at boot time, after httpd has started.

NOTE: shibd is a daemon that must be running, so make sure it is started at boot time, after Apache httpd has been started.

On Windows/IIS machines, the shibboleth2.xml.windows-example file in the locker is a good starting point for the shibboleth2.xml file. You will need to edit the file for it to work on your server; please see the comments at the top of the file for the details. The attribute-map.xml file in the locker should work without modification.

Log Files

The Shibboleth Apache module logs by default to $prefix/var/log/httpd/native.log.

This file must be writable by Apache, which may require that you set its directory's ownership and/or permissions to allow write access by the user Apache is configured to run under. You may also choose to change the location of the file (for example to /var/log/shibboleth/httpd/native.log), by modifying the log4j.appender.native_log.fileName setting in $prefix/etc/shibboleth/native.logger, and appropriately creating the containing directory.

The Shibboleth daemon logs to shibd.log and transaction.log in $prefix/var/log/shibboleth/.

Protecting Content

For information on configuring Shibboleth to protect content, see the Shibboleth wiki at Internet2, as well as the information in the sections below.

Customize the error pages

This is optional, but recommended.

You will probably also want to customize the error pages and support contact information listed in the <Errors> element in $prefix/etc/shibboleth/shibboleth.xml, e.g.:

<Errors supportContact="myservice-help@mit.edu"
    logoLocation="/shibboleth-sp/logo.jpg"
    styleSheet="/shibboleth-sp/main.css"/>

The error template files are located in $prefix/etc/shibboleth/ (you can override these locations in the <Errors> element). For more information, see https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPErrors

Letting the IdP know about your application

Until the MIT Identity Providers know about your application, they won't release information about an authenticated user to your server. Each Touchstone enabled application running on a server needs to be registered with the IdPs, by our adding it to metadata.

To register your application server with the MIT IdPs send mail to touchstone-support with the following information:

  • A contact email address. We strongly recommend that this be an email list rather than an individual's personal email address. Note that this address will be published in the MIT metadata file.
  • The web server host name, i.e. the host name that a user would specify when entering the URL to access your site. This should be the same as the Subject CN in your server's SSL certificate, and match the host name entered in response to gen-shib2's initial prompt. This name will be used to create a unique Entity ID by which the IdPs will identify your SP; by convention, this ID is the URI https://mywebapp.mit.edu/shibboleth. (For more information on entity ID naming, please see EntityNaming|https://wiki.shibboleth.net/confluence/display/SHIB2/EntityNaming]at the Internet2 wiki site). If you have multiple applications installed on the same machine, served by different host names (e.g. using different Apache vhosts), you will also need to provide each application's host name, as Shibboleth endpoints on each host must be registered in metadata. In some cases, different applications will require the use of separate entity IDs; please see below.
  • The certificate information for the SP. If using the self-signed certificate generated at install time, you must include the certificate itself (in /etc/shibboleth/sp-cert.pem); do not send the private key file. If using the MIT server SSL certificate, we only need the Subject CN from the certificate (should be the same as the web server host name above).
  • Organization name. This is typically the name of the MIT department, lab, or center running the application.
  • Organization URL. The URL that provides some basic information about your department, lab, or center.

We also encourage you to send the following optional information with your registration information:

  • The application URL. The actual URL which will be used to access your application.
  • Your server machine's host name(s), if different from the web server host name.
  • Your server platform. (RHEL 4, RHEL 5, Windows, Debian, Solaris, ...)

A single Shibboleth SP installation is designed to support multiple applications installed on that server, but there are different deployment and configuration strategies to support multiple applications. At MIT we recommend that each application simply be configured to use a separate Apache vhost; more complex configurations, e.g. creating separate entity IDs for each application, are also possible. For more information, please see:

An example of when separate entity IDs are needed would be if one application requires a non-standard set of attributes to be released to it. Please consult with touchstone-support as needed.

Testing your Shibboleth configuration

Once your SP is properly registered with the IdP, you can test your SP's configuration by visiting either the Shibboleth handler's session initiation location (https://myhost/Shibboleth.sso/DS if using the standard configuration generated by gen-shib2.sh, or https://myhost/Shibboleth.sso/Login if using the new <SSO> element available in Shibboleth 2.4 or later), or a resource protected in your Apache configuration or Shibboleth request map, e.g. https://myhost/secure. After you have authenticated successfully, you can then visit https://myhost/Shibboleth.sso/Session to display the Shibboleth session information, including a list of the available attributes. To include the attribute values in this display, edit shibboleth2.xml, and set the handler's showAttributeValues property to "true":

    <!-- Session diagnostic service. -->
    <Handler type="Session" Location="/Session" showAttributeValues="true"/>

Keep your metadata up to date

You should ensure that your SP's copy of the MIT metadata is kept up to date. The current metadata is available in http://web.mit.edu/touchstone/shibboleth/config/metadata/MIT-metadata.xml.

The easiest way to maintain the metadata is by configuring a <MetadataProvider> element in shibboleth2.xml which points at this URL. (This will be set up for you automatically if you use the gen-shib2 procedure with the shibboleth2.xml.in template, as discussed above). The Shibboleth 2.x SP software will automatically refresh the metadata periodically.

If you are running Shibboleth 1.3, or prefer not to have Shibboleth refresh the metadata automatically for some reason, then you must use a cron job (or other regularly scheduled procedure) which runs a script to download and install the latest metadata. A sample of such a script is available in http://web.mit.edu/touchstone/shibboleth/config/metadata/update-metadata.sh-example. Adjust it as necessary for your installation; in particular, if you did not install from the stock RPMs from Internet2, you will need to adjust the setting for the Shibboleth etc directory at the top of the script.

The Shibboleth SP software detects and loads the updated metadata automatically; there is no need to restart the web server or shibd.

Example code and configuration information for third party applications

We have some pointers to example code written in various lanaguages. We do expect the examples to increase over time. We are also creating some local documentation that covers the configuration of third party software. However, users are encouraged to look at resources outside of MIT as well. If you do find useful information please do bring it to our attention.

Some simple examples:

  • Display the results of the SAML assertion in various languages.

Third party applications:

Support Resources

Consulting service may be arranged by sending mail to touchstone-support. This will open an RT case and a person will be assigned to work with you.

Classes held during IAP of 2009 were poorly attended. No training classes are scheduled at this time. If you are interested, please send mail to touchstone-support. If there is sufficient interest a class will be scheduled and you will be informed.

Who to Contact:

Web: MIT Touchstone
Email: touchstone-support@mit.edu