Page History

Panel
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

Panel

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

Warning

title	Attention

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

We strongly recommend that sites currently running Shibboleth 1.3 in production plan to upgrade to the current version of Shibboleth well in advance of the announced end-of-life date. This will protect against the possibility of a forced but unplanned migration from 1.3 should a security issue or incompatibility be discovered after the end-of-life date has been reached.

Tip
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:

Panel

Tip

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.

Info

Historical installers:

Please note that we strongly recommend that no new systems be created using Shibboleth 1.3x. This software will reach its end of life on June 30th, 2010. At that time, security updates for the software will no longer be created. If you still have some need to obtain the 1.3x packages, for now they can still be obtained from Internet 2.

1.3x RPMs remain available from Internet2 for RHEL 4 and 5.

You will typically need the 5 main RPMs: log4shib, opensaml, shibboleth, xerces-c, xml-security-c.
You should normally skip the -devol, -debug, and -doc RPMs from the Internet2 RPM download site.
If your system does not already have curl installed, you will need to install it (via the stock RHEL RPM).

A 1.3x installer for IIS is also available from Internet2.

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:

Panel

Tip
The Touchstone team 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

Panel

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

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

Note

Historical note:

If your server already has a server certificate issued by the MIT Certificate Authority, and it was issued after July 1st, 2008, and it has not expired, you should be able to use it with Shibboleth/MIT Touchstone. If the server certificate was issued prior to July 1st, 2008, you probably need to obtain a new server certificate.

Configure the SP software

Panel

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/shibboleth/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 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.

Note

title	Historical information

Configuring and customizing the Shibboleth 1.3x SP

Log Files

Panel

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.

Protecting Content

Panel
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

Panel

Tip
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 (search for "You should customize these pages!"), e.g.:

Code Block


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

Letting the IdP know about your application

Panel

Info
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.

Tip

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

A contact email address. We strongly recommend that this be an email list rather than an indivdual's persoanl email address.
The server or host name. If you have multiple applications installed on the same server, you will actually need to register each application's provider ID. See below for more details.
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 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:

SP 3.x. Please see https://wiki.shibboleth.net/confluence/display/SP3/Home for information on the current releases of Shibboleth.

Tip
Information about migrating an existing Shibboleth SP 2.x installation to version 3.x can be found at https://wiki.shibboleth.net/confluence/display/SP3/UpgradingFromV2

Installing native SP software:

Panel

Tip

The most current native packages and installers for the Service Provider software for the Red Hat Enterprise Linux (RHEL) and Windows platforms can always be found at the Shibboleth download site. Generally you should download the latest version of the SP software for your platform.

For RHEL installations, you should use the Shibboleth service's yum repository; please see https://wiki.shibboleth.net/confluence/display/SP3/RPMInstall for details.

For Windows installations, please see https://wiki.shibboleth.net/confluence/display/SP3/Install+on+Windows for more information.

Some other Linux distributions also maintain binary installers available from the OS distribution point. 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.

Building from source:

Panel

Tip
The Touchstone team strongly recommends that you use the native packages/installers available from Shibboleth 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.

Server SSL Certificate request and configuration

Panel

Tip
Before proceeding to "Configuration and customization for use" you should obtain a server SSL 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

While some older MIT SPs still use an MIT-issued server SSL certificate with Shibboleth (e.g. when the Shibboleth SP authenticates to an IdP), we now require using a separate, self-signed certificate for that purpose, so new installs must generate and provide us with that certificate. Please see below for details.

Ensure your system clock is accurate

Panel

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

Panel

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.:

No Format
# cd /etc/shibboleth # wget -N https://touchstone.mit.edu/config/shibboleth-sp-3/mit-config-shib.sh # sh mit-config-shib.sh

mit-config-shib.sh will use either the wget utility or curl utility, if available, to download the other files needed to configure the SP. If you do not have either wget or curl on your system, you must download the following files manually from https://touchstone.mit.edu/config/shibboleth-sp-3/ and install them into the /etc/shibboleth directory:

Here is a sample typescript from running the procedure for a web server whose public name (the host name entered by users as the URL to access your application) is mywebsite.mit.edu, but is hosted on a machine named simulacrum.mit.edu:

No Format

[root@simulacrum shibboleth]# sh mit-config-shib.sh

Download latest shibboleth2.xml.in? [Y] 

Download latest attribute-map.xml? [Y] 
Saving previous version as attribute-map.xml.old

Enter the web server host name: [simulacrum.mit.edu] mywebsite.mit.edu

Enter the path for the Shibboleth signing certificate file: [sp-signing-cert.pem] 
The certificate's subject CN must match your web server host name.
(The subject CN is simulacrum.mit.edu, given host name is mywebsite.mit.edu).

Generate a new (self-signed) certificate/key pair? [Y] 
Saving sp-signing-cert.pem to sp-signing-cert.pem.saved-by-mit-config-shib...
Saving sp-signing-key.pem to sp-signing-key.pem.saved-by-mit-config-shib...
Generating sp-signing-cert.pem and sp-signing-key.pem...
Please include the contents of sp-signing-cert.pem when you register the server.

Enter the path for the Shibboleth signing private key file: [sp-signing-key.pem] 

Enter the path for the Shibboleth encryption certificate file: [sp-encrypt-cert.pem] 
The certificate's subject CN must match your web server host name.
(The subject CN is simulacrum.mit.edu, given host name is mywebsite.mit.edu).

Generate a new (self-signed) certificate/key pair? [Y] 
Saving sp-encrypt-cert.pem to sp-encrypt-cert.pem.saved-by-mit-config-shib...
Saving sp-encrypt-key.pem to sp-encrypt-key.pem.saved-by-mit-config-shib...
Generating sp-encrypt-cert.pem and sp-encrypt-key.pem...
Please include the contents of sp-encrypt-cert.pem when you register the server.

Enter the path for the Shibboleth encryption private key file: [sp-encrypt-key.pem] 

Always use SSL for Shibboleth handler? [Y] 

Set cookies secure (requires SSL for all protected content)? [Y] 

To avoid loops, be sure to redirect any non-https requests to SSL.
Enter <return> to continue: 

Support contact email address? [mywebsite-help@mit.edu] 


Will this server be joining the InCommon Federation? [N] 
Using prefix /usr...
shibboleth2.xml already exists, saving previous version as shibboleth2.xml.old

Notes:

The default web server host name is the machine host name, but we override that in this example with the user-visible web server host name, mywebsite.mit.edu.
We require that you generate and use a pair of self-signed certificates with Shibboleth (one pair for signing, another for encryption), instead of sharing the MIT (or commercial) SSL certificate used for browser-facing https traffic. The mit-config-shib.sh script can generate proper certificates as needed; in this example, it regenerates the certificates created when the shibboleth RPM was installed, so that the subject CN matches the web server host name, instead of the machine host name. You must include the contents of these certificate files (normally sp-signing-cert.pem and sp-encrypt-cert.pem) when emailing your registration request to touchstone-support (see below).
We recommend that you set Shibboleth cookies to be secure (i.e. only sent by the browser via https connections), to minimize the risk of a session being hijacked. This requires, though, you configure your server to use SSL for all Shibboleth-protected content; otherwise a browser loop may be introduced. Shibboleth provides a special option to force a redirect for any attempted http access to SSL (https), which can be specified via an Apache directive:
No Format
ShibRequestSetting redirectToSSL 443
(replace 443 with the appropriate number, if using a non-standard port for https traffic).
If your application will support user bases from other InCommon Federation institutions, i.e. other than MIT and Collaboration accounts, then answer Yes to the question about joining the InCommon Federation. The necessary configuration will be added to Shibboleth. Also remember to indicate that you want to register with InCommon when you submit your registration request to touchstone-support.

Notes

Note that some 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 mit-config-shib.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 mit-config-shib.sh script.

The $prefix/etc/shibboleth directory will contain apache.config, apache2.config, apache22.config, and apache24.config, which contain needed and example directives for Apache 1.3, Apache 2.0, Apache 2.2, and Apache 2.4, respectively. If you install from Red Hat RPMs, the appropriate version of this file will be installed in /etc/httpd/conf.d/shib.conf; we recommend that you add your Shibboleth directives to a separate file, to avoid having to merge changes to shib.conf when the RPM is updated. Otherwise, copy and/or include the appropriate version of the file in your Apache config, and customize as needed.

shibd is a daemon that must be running, so make sure it is started at boot time. Installing from Red Hat RPMs also take care of this, by adding shibd as a managed service. The $prefix/etc/shibboleth directory will contain init files (shibd-*) for various other types of installations.

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

Panel

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 logging by the SP, please see https://wiki.shibboleth.net/confluence/display/SP3/Logging.

Protecting Content

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

Customize the error pages

Panel

Tip
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/shibboleth2.xml, e.g.:

Code Block
<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

Letting the IdP know about your application

Panel

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.

Info
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.

Tip

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 mit-config-shib'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://mywebsite.mit.edu/shibboleth. (For more information on entity ID naming, please see 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.
Indicate if the SP should be registered with the InCommon Federation, if your application needs to support users at other InCommon institutions; the default is to register the SP for the MIT IdPs only, in which case only MIT and Collaboration account users will be supported.
The certificates for the SP. This should be the self-signed certificate files generated at install time (in /etc/shibboleth/), i.e. sp-signing-cert.pem and sp-encrypt-cert.pem); do not send the private key files.
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 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:

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

Panel

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":

No Format
<!-- 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":

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

Keep your metadata up to date

Panel

Warning

You should must ensure that your SP's copy of the MIT metadata is kept up to date. The current metadata is available in http://webtouchstone.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 mit-config-shib.sh procedure with the shibboleth2.xml.in template, as discussed above). The Shibboleth SP software will automatically refresh the metadata periodically.

If you 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 file. This procedure should validate the signature on the metadata file. via a cron job 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 file automatically; there is no need to restart the web server or shibd.

...

Panel

We have some pointers to example code written in various lanaguageslanguages. 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.to our attention.

For basic information on accessing attributes provided by a Shibboleth session, see:

https://wiki.shibboleth.net/confluence/display/SP3/AttributeAccess

Some simple examples:

Display the results of the SAML assertion in various languages.

Third party applications:

Drupal

Support Resources

Consulting Services

:

Drupal

Panel

Tip

title

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.

Note

title	Training

Support Resources

Panel

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

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:

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

Child pages

Versions Compared

Old Version 30

New Version Current

Key

Notes