...
| Panel |
|---|
In order to make your application use MIT Touchstone, or Shibboleth, for authentication, several steps have to be performed |
...
. |
...
The information below is intended to help guide you through your configuration. |
Installing, or building, the Shibboleth SP software for your system
Shibboleth SP version information
| Panel |
|---|
IS&T |
...
currently |
...
supports new customers intending to use |
...
As of June 30, 2010, the Internet2 Shibboleth development team will no longer promise to supply security updates for version 1.3x.
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.
Using installers:
The most current installers from Internet2 can always be found at http://shibboleth.internet2.edu/downloads.html
Historical installers:
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.
...
current versions of Shibboleth SP 3.x. Please see https://wiki.shibboleth.net/confluence/display/SP3/Home for information on the current releases of Shibboleth.
|
Installing native SP software:
| Panel | ||
|---|---|---|
Some other Linux distributions also maintain binary installers available from the OS distribution point. For Debian/Ubuntu, please install the |
Building from source:
| Panel | ||
|---|---|---|
|
...
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 | ||
|---|---|---|
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.ezproxyberklee.flo.org/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 |
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.
We also encourage you to send the following optional information with your registration information:
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. Once Touchstone support has created your application integration in Okta, we will provide you with the Okta external ID you will need to supply in the configuration procedure (see below) |
Configure the SP software for Touchstone
| Panel | ||||||
|---|---|---|---|---|---|---|
On a Linux server, the quickest way to get started is to use Touchstone's 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.:
If you are not using the Okta IdP, then you will also need to download the MIT metadata signing certificate, mit-md-cert.pem 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:
Notes:
NotesNote 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 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 | ||||
|---|---|---|---|---|
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.:
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 |
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 (
Once you have confirmed that your SP is getting the proper set of attributes, we recommend that you set the handler's
|
Keep your metadata up to date
| Panel | ||
|---|---|---|
|
The script can build the software on Linux and Solaris systems; note that you will to need to have Apache httpd (preferably 2.x, though 1.3 should also work) and OpenSSL (0.9.7 or higher) installed on the system, including their development packages. On Solaris systems, you must have the native Sun C/C++ compiler installed; Athena Solaris machines have this available, via attachandrun scripts and the sunsoft locker, but this requires that you have AFS tokens for the athena cell. Solaris machines must also have GNU make (gmake) installed.
To build from this, create a build directory, and unpack the source tarball into it; use the build-sp.sh script as follows: # sh build/build-sp.sh -a <apxs_path> -p <install_prefix> -s openssl_prefix
The -a option argument is the path to the Apache apxs executable, e.g. /usr/local/apache2/bin/apxs (defaults to using the apxs in the PATH). The -p option specifies the install prefix (defaults to /usr/local/shibboleth). The -s option specifies the install location of the version of OpenSSL you want to build against, e.g. /usr/local/ssl (defaults to finding OpenSSL in standard system library locations).
Once you have built the software successfully, you will need to configure and customize it for use.
Certificate request and configuration
| Note: Before proceeding to "Configuration and customization for use" you should obtain a server certificate. |
*Configuration and customization for use *
Note: The gen-shib.sh procedure described below currently works only on Linux and Solaris systems; it should be portable to other UNIX-based systems without too much effort.
When you have successfully built and installed the Shibboleth SP, you will need to configure things to work against our test and pilot IdPs. We have some template files and a script in AFS (the touchstone locker) to generate the needed config files from the templates: cd to shibboleth's etc directory ($prefix/etc/shibboleth), and copy in the following files from /mit/touchstone/shibboleth/config/shibboleth-sp/ (or just copy all files from the directory):
- AAP.xml.in
- shibboleth.xml.in
- MIT-metadata.xml
- protectnetwork-metadata.xml
- gen-shib.sh
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.ezproxyberklee.flo.org/touchstone/shibboleth/config/shibboleth-sp/
On Solaris, also copy:
- shibd.in
- shibd-wrapper.in
Then run the gen-shib.sh script:
sh ./gen-shib.sh
and answer its prompts, which will hopefully be clear. Remember that the certificate it wants should be enabled for client as well as server use. Any MIT server certificates that have been created after July of 2008 will be enabled for client as well as server use.
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://mv-ezproxy-com.ezproxyberklee.flo.org/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://mv-ezproxy-com.ezproxyberklee.flo.org/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*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.
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: Shib 1.3 Add Separate Application.
...
|
...
...
|
...
|
Example code and configuration information for third party applications
| Panel |
|---|
We have some pointers to example code written in various languages. 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: Some simple examples:
Third party applications: |
Support Resources
| Panel |
|---|
Please send email to touchstone-support for assistance with setting up your SP. |
Who to Contact:
| Panel |
|---|
Web: MIT Touchstone |
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:
- Drupal*Support Resources*Consulting Services:
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.
Training:
We are intending to offer some hands on training during IAP 2009. Space will be limited to 18 participants. The hands-on lab is scheduled for January 20th, 1:30-3:30pm. There will also be session talking about configuration options on January 16th, from 2:30-4:00pm.
Who to Contact:
| Wiki Markup |
|---|
Web: [MIT Touchstone|http://mit.edu.ezproxyberklee.flo.org/touchstone]
Email: [touchstone-support@mit.edu|mailto:touchstone-support@mit.edu]\[ |
...