Page History

IS&T currently supports new customers intending to use current versions of Shibboleth 2SP 3.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. 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.

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

•  Building Shibboleth SP on Linux Linux 
  
• Building Shibboleth SP on Solaris WIndows
• Building Shibboleth SP on Mac OS X

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

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 servernames server names in your certificate request. The server name within the certifiacte 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.

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

to use Touchstone's mit-config-shib.sh script to generate an initial configuration from a template. You will need to know the Okta external ID for your integration in order to complete this step.

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

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

• attribute-map.xml
• mit-config-shib.sh
• mit-md-cert.pem
• shibboleth2.xml.in

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:

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

Configure for the Okta IdP? [Y] 
Please enter the Okta external ID provided by Touchstone Support.

Enter the Okta external ID: exkdckcmyloNarixC697
 
Downloading metadata to okta-exkdckcmyloNarixC697-md.xml...

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-server-1.mit.edu] simulacrum.mit.edu

Support contact email address? [simulacrum-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 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 genmit-config-shib2shib.sh procedure described above is currently works only supported on Linux and Solaris systems only; it should be portable to other UNIX-based systems without too much with minimal effort. Please contact touchstone-support if you are using another operating system and having problems with the genmit-config-shib2shib.sh script.

The $prefix/etc/shibboleth directory will contain apache.config, apache2.config, apache22.config, and apache22apache24.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.

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.

NOTE: shibd is a daemon that must be running, so make sure it is started at boot time, after Apache httpd has been started.  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.

Configuring and customizing the Shibboleth 1.3x SP

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.'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 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/shibbolethshibboleth2.xml, e.g.:

<Errors supportContact="root@localhostmywebsite-help@mit.edu"
    logoLocationhelpLocation="/shibboleth-sp/logo.jpgabout.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://spaceswiki.internet2shibboleth.edunet/confluence/display/SHIB2SP3/NativeSPErrorsErrors

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

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:

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.

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

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