Page History

Some other Linux distributions also maintain binary installers available from the OS distribution point. If you For Debian/Ubuntu, please install the libapache2-mod-shib package (libapache2-mod-shib2 on older releases) with apt-get or other package manager. If you have questions about other distributions please contact touchstone-support and indicate what operating distribution and version you are using.

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.

On a Linux server, the quickest way to get started is to use Touchstone's mit-config-shib.sh script to generate an initial configuration from a template.

In the /etc/shibboleth directory (as root), download and run the mit-config-shib.sh script from the touchstone.mit.edu web server, e.g.:

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/touchstonewget -N https://touchstone.mit.edu/config/shibboleth2shibboleth-sp/* .-3/mit-config-shib.sh
# sh genmit-config-shib2shib.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 currently works only on Linux and Solaris systems; it should be portable to other UNIX-based systems without too much 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.

The Shibboleth Apache module logs by default to httpd's own error log.

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

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

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

<Errors supportContact="mywebsite-help@mit.edu"
    helpLocation="/about.html"
    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/SP3/Errors

Before registering your service provider with the MIT Identity Providers, please make sure that the Shibboleth software is installed and running on your server. You should confirm that Shibboleth is running properly by connecting successfully to https://localhost/Shibboleth.sso/Status from the server; Touchstone support will attempt to confirm the SP configuration by connecting (remotely) to https://myhost/Shibboleth.sso/Metadata.

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 and version. (e.g. RHEL 7, Windows 2012, Debian 8, ...)

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:

• Shibboleth SP Application Model
• Shibboleth SP Application Override

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.

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/Login by default), 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. -->
    <!-- Set showAttributeValues to "true" for testing only! -->
    <Handler type="Session" Location="/Session" showAttributeValues="true"/>

Once you have confirmed that your SP is getting the proper set of attributes, we recommend that you set the handler's showAttributeValues property back to "false":

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

Please send email to touchstone-support for assistance with setting up your SP