Provisioning Steps

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.

IS&T is currently supporting customers intending to use Shibboleth 1.3x or 2.x. We recommend that new installations use Shibboleth 2.x based SPs.

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.

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

• Building the Shibboleth SP from MIT's source tarball and build script  
• Building Shibboleth SP on Linux  
• Building Shibboleth SP on Linux

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

Please make sure that you use lower case servernames in your certificate request. The server name within the certifiacte 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

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

1. cp /mit/touchstone/config/shibboleth2-sp/* .
2. 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 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.

On Red Hat machines, copy shibd-redhat to /etc/init.d/shibd, make sure it is executable, add it as a managed service with "chkconfig --add shibd", and enable it for run levels 3, 4, and 5 ("chkconfig --level 345 shibd on").

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.

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, by modifying the log4j.appender.native_log.fileName setting in $prefix/etc/shibboleth/native.logger.

For information on configuring Shibboleth to protect content, see the Shibboleth wiki at Internet2, 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/shibboleth.xml (search for "You should customize these pages!"), e.g.:

<Errors session="/usr/local/shibboleth/etc/shibboleth/sessionError.html"
  metadata="/usr/local/shibboleth/etc/shibboleth/metadataError.html"
  rm="/usr/local/shibboleth/etc/shibboleth/rmError.html"
  access="/usr/local/shibboleth/etc/shibboleth/accessError.html"
  ssl="/usr/local/shibboleth/etc/shibboleth/sslError.html"
  supportContact="root@localhost"
  logoLocation="/shibboleth-sp/logo.jpg"
  styleSheet="/shibboleth-sp/main.css"/>

The pages are used as follows:

• session
      displayed if a session cannot be created after successful authentication,
      for example if shibd is not running. In a standard configuration, you can
      force this page to be displayed by visiting the server's /Shibboleth.sso location, e.g.:
      https://my-sp.mit.edu/Shibboleth.sso
• metadata
      displayed in certain cases where there is no valid metadata
      for an identity provider. This should not happen using our
      standard configuration; it should only be possible when
      using the Artifact profile, or "lazy sessions", and there
      is a configuration problem.  You can force the page to be
      displayed by visiting:
      https://my-sp.mit.edu/Shibboleth.sso?providerId=NoSuchIdP
• rm
      displayed when an exception occurs when exporting assertions into
      request headers.  This indicates a software problem, and should
      not happen.
• access
      displayed for access control failures.  This should only
      happen if you have access control directives in the Apache
      configuration for your Shibboleth-protected content.  You
      can force the page to be displayed by adding an access
      control directive that is certain to fail, for example
      "require NoSuchAlias" (remember to remove this configuration
      when you have completed testing).
• ssl
      displayed when a POST is attempted using http instead of https,
      and RedirectToSSL is in effect.  This should not happen on a
      properly configured server.

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 platform. (RHEL 4, RHEL 5, Windows, Debian, Solaris, ...)

The IdP doesn't really need to know your hostname. It does need to know the Provider ID that uniquely identifies your application. Typical MIT installations that use the gen-shib.sh script (see above) hide this detail from you so that we simply need the hostname. If you want to learn more about provder ID naming please see EntityNamingat the Internet2 wiki site.

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 be configured to use a separate Apache vhost, in addtion to simply creating additional ProviderIDs for each application. More information is available here:

• Shib 1.3 Add Separate Application
• Shib 2.x - NativeSPApplicationOverride

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:

• Drupal

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