Versions Compared

Old Version 76

changes.mady.by.user Robert A Basch

Saved on

compared with

New Version 77

changes.mady.by.user Robert A Basch

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 4.0

...

Panel

On a Linux server, the quickest way to get started is to use Touchstone's gen-shib2.sh script to generate an initial configuration from a template.
For Shibboleth 2.4+, we provide a new procedure which generates a configuration which takes advantage of some simpler standard elements that were added in the 2.4 release. If you are running Shibboleth 2.3, please see the instructions for the older procedure below.

Shibboleth 2.4+

In the /etc/shibboleth directory (as root), download and run the gen-shib2.sh script from the Touchstone locker, e.g.:

No Format
# cd /etc/shibboleth
# wget -N http://web.mit.edu/touchstone/config/shibboleth2-sp/2.x/gen-shib2.sh
# sh gen-shib2.sh

where 2.x should be replaced by the version of the Shibboleth SP software you are running (e.g. 2.4 or 2.5). gen-shib2.sh will use the wget utility, if available, to download the other files needed to configure the SP. If you do not have the wget utility on your system, you must download the following files from http://web.mit.edu/touchstone/config/shibboleth2-sp/2.x/Image Removed (or, if AFS is installed on your server, copy them from the Touchstone locker /mit/touchstone/config/shibboleth2-sp/2.x/) into /etc/shibboleth:

  • attribute-map.xml
  • gen-shib2.sh
  • 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 mywebapp.mit.edu, but is hosted on a machine named simulacrum.mit.edu:

No Format
[root@simulacrum shibboleth]# sh gen-shib2.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] mywebapp.mit.edu

Enter the path for the Shibboleth certificate file: [sp-cert.pem] 
Please include the contents of sp-cert.pem when you register the server.

Enter the path for the Shibboleth private key file: [sp-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? [mywebapp-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, mywebapp.mit.edu.
  • We now require that you generate and use a self-signed certificate with Shibboleth, instead of sharing the MIT (or commercial) SSL certificate used for browser-facing https traffic. The gen-shib2.sh script can generate a proper certificate as needed. You must include the contents of this certificate file (generally sp-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).
Shibboleth 2.3

Download the following files from http://web.mit.edu/touchstone/config/shibboleth2-sp/2.3/Image Removed (or, if you have AFS, copy them from the Touchstone locker (/mit/touchstone/config/shibboleth2-sp/2.3) into /etc/shibboleth:

  • attribute-map.xml
  • gen-shib2.sh
  • shibboleth2.xml.in

Then run the gen-shib2.sh script, and answer the prompts, to generate shibboleth2.xml. For example:

No Format
# cd /etc/shibboleth
# cp /mit/touchstone/config/shibboleth2-sp/2.3/* .
# sh gen-shib2.sh
Notes

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

shibd is a daemon that must be running, so make sure it is started at boot time, after Apache httpd has been started. On Red Hat, the chkconfig tool can do this, e.g.:

No Format
# chkconfig shibd on

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.

...

Customize the error pages

Panel
Wiki Markup

{tip
}
This is optional, but recommended.

{tip}
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, e.g.:

{code
}
<Errors supportContact="myservice-help@mit.edu"
    logoLocation="/shibboleth-sp/logo.jpg"
    styleSheet="/shibboleth-sp/main.css"/>
{code}
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/SHIB2/NativeSPErrors|https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPErrors]

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, 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 gen-shib2'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://mywebapp.mit.edu/shibbolethImage Removed. (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.
  • The certificate for the SP. This should be the self-signed certificate generated at install time (in /etc/shibboleth/sp-cert.pem); do not send the private key file.
  • 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. (RHEL 4, RHEL 5, Windows, Debian, Solaris, ...)

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.

...

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/DSImage Removed if using the standard configuration generated by gen-shib2.sh, or https://myhost/Shibboleth.sso/LoginImage Removed if using the new <SSO> element available in Shibboleth 2.4 or later), or a resource protected in your Apache configuration or Shibboleth request map, e.g. https://myhost/secureImage Removed. After you have authenticated successfully, you can then visit https://myhost/Shibboleth.sso/SessionImage Removed 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. -->
    <Handler type="Session" Location="/Session" showAttributeValues="true"/>

...

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:

  • Display the results of the SAML assertion in various languages.

Third party applications:

...