Before you begin:

Is Shibboleth already available on your web hosting platform?

Get familiar with the basic concepts

When you set up Shibboleth access to your system, you'll be creating a service provider (SP) on your local server that communicates with at least one identity provider (IDP) elsewhere. You'll establish what information your system requests from the identity provider and what access that will provide to people who match the requested credentials.

More Shibboleth-specific terms and explanations are provided at Shibboleth, For IT Pros: Understanding Shibboleth Terms .

Download and save University-localized Shibboleth2 and attribute map XML files

For your convenience, Technology Services offers localized templates for shibboleth2.xml and attribute-map.xml files. Download these files and save them in a convenient location. (You'll change a few lines later in order to specify your own Shibboleth instance and select which attributes you wish to use.)

Right-click the following links and save them as XML files:

• Localized shibboleth2.xml
• Localized attribute-map.xml

Step 1: Choose your entity ID

Your Entity ID will be a string of the format https://your.host.name/shibboleth. Although it looks like a URL, it doesn't need to be one that your web server responds to with valid content. Your entity ID needs to be a string not used by other services, and it should be something that won't change.

• One host name on your server:
  If you only have one hostname that users will use to access your server, substitute that hostname for your.host.name.
• Multiple host names per server, one primary:
  If you have multiple hostnames on your web server with Shibboleth-protected content and one of the hostnames can be considered primary, use that for your.host.name.
• Multiple host names, none primary:
  If you have multiple hostnames but can't select a primary one, use the system's primary hostname. Be careful with this, though: it's not easy to change your entity ID if, for instance, you move your sites to a new server.

Step 2: Choose which attributes you want to use for authorization

Determine what attributes your Shibboleth-protected attributes will need to use in order to permit access to authorized users and deny access to others. This can be changed later, but you'll need to know what you want to start with.

Shibboleth, Authorization and Shibboleth describes how to use attributes to control access to your services.

You can look at the localized attribute-map.xml file for examples of the most commonly used attributes. (However, you probably won't need to use all of the attributes included in the file.)

Step 3: Configure HTTPS

Configure your webserver to support encrypted communications. Shibboleth-protected sites at the University of Illinois at Urbana-Champaign are required to operate completely over an https connection.

Installation and configuration

Step 4: Install Shibboleth SP

Install the Shibboleth SP software. You should consult the instructions for installation on your platform, including web server configuration, on the Shibboleth Project Wiki for your OS.

• Linux installer
• Windows installer
• Mac installer

Step 5: Generate a SSL key and certificate pair for Shibboleth.

Generate a key and certificate to be used by your service provider to sign and encrypt data. Note that this is different from the web server certificate.

Your SP installation may have already generated these files, but it's smart to re-generate them manually to make sure appropriate values were selected.

In the below commands, your.host.name is the hostname you chose for your entityID previously. Path names will vary if you installed Shibboleth in a non-standard location. These commands will create a key and cert pair, sp-key.pem and sp-cert.pem.

Step 5a on Unix:

1. cd /etc/shibboleth

2. ./keygen.sh -h your.host.name -e https://your.host.name/shibboleth -f -y 20
   (Note: On some distributions such as Ubuntu and Debian, this command may be called shib-keygen instead of keygen.sh.)

3. Replace the shibboleth2.xml file that was installed in step 1 with the localized shibboleth2.xml file.
   (On Unix, this file usually should be placed at /etc/shibboleth/shibboleth2.xml. Locations will vary if you installed Shibboleth in a non-standard location.)
4. Continue with step 6 instructions below.

Step 5a on Windows:

1. Open a command prompt.
2. Change directories to c:\opt\shibboleth-sp\etc\shibboleth
3. Run ./keygen.bat -h your.host.name -e https://your.host.name/shibboleth -f -y 20
4. Replace the shibboleth2.xml file that was installed in step 4 with the localized shibboleth2.xml file.
   (On Windows, it should typically go at C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2.xml. Locations will vary if you installed Shibboleth in a non-standard location.)
5. Continue with step 6 instructions below.

Step 6: Configure your installation

6a: General instructions

1. Open your localized shibboleth2.xml in a text editor and make the following changes.
   • In the line <ApplicationDefaults entityID=https://sp.example.org/shibboleth>:
     Replace https://sp.example.org with the entity ID you chose previously.
      
   • In the line <Errors supportContact=consult@illinois.edu>:
     Replace consult@illinois.edu with the appropriate support email address for services on this server.
      
2. Place the localized attribute-map.xml in the same directory as shibboleth2.xml.
   By default, this file contains attribute definitions for all of the attributes supported by the UIUC identity provider, but they are all commented out.
    
3. Uncomment the attributes that your service needs by removing the <!-- from the beginning of each line and --> from the end of each line.
   Note that uncommenting more attributes than you actually need can slow down your server's performance.
    
4. Customize the error templates used by Shibboleth. These are all of the .html files in the same directory as shibboleth2.xml. Though skipping this step won't break anything, it'll give your service a much better appearance when errors occur or other intermediate screens are displayed by the Shibboleth SP.
   
   
5. (For Windows IIS ONLY:) Add InProgress and RequestMapper code blocks into shibboleth2.xml, as described in Shibboleth, Windows IIS Server specific configuration instructions .

6b: Specific configurations

You may wish to refer to one of the following pages for more specific guidance on particular configurations.

Shibboleth, Urbana-specific configuration

In an Urbana campus-specific configuration, the service administrator wants to provide access to students, faculty, and staff at only the Urbana campus.

Shibboleth, University of Illinois-specific configuration

In the University-wide configuration, the service administrator wants to provide access to students, faculty, and staff at any or all of the three University of Illinois campuses, based on one or multiple group or role identities.

Shibboleth, Multi-university configuration

In the multi-university configuration, the service administrator wants to provide access to students, faculty, and staff at any of the three University of Illinois campuses as well as students, faculty, and staff at a hypothetical partner University.

6c (optional): Assigning uid to REMOTE_USER

It's handy to have the domain name appended to the NetID in REMOTE_USER if you'll ever be opening up your application to users outside of the university. Shibboleth best practices suggest the use of eppn or eptid instead of just a NetID without any domain name scoping. However, if it's going to be too much work to change your application to handle the domain name being included, you can request the uid attribute from the I-Trust federation registry and configure your service provider to look for that attribute when setting REMOTE_USER.

In the ApplicationDefaults section, look for the REMOTE_USER attribute. This attribute contains a list of attributes that will be used to set REMOTE_USER in the environment. The first attribute in the list that's found in the data that's returned from the IDP will be used. So, once you've requested the uid attribute, simply add it to the beginning of your list and restart shibd and your web server.

For more information on Apache's mod_shib settings, see the Shibboleth Project Wiki page, https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig.

Step 7: Restart and registration

Restart shibd and your web server to read your new configurations. You should already know how to restart your webserver. To restart shibd:

• On Windows, simply restart the service.
• On Linux, run service shibd restart.

Register your new service provider with the necessary federation or individual identity providers.

• Every campus Shibboleth instance should register with iTrust. See http://go.illinois.edu/itrust for details.
• Shibboleth instances that wish to allow multi-university federation should first register with iTrust to get things working. After that, they should also register with InCommon, which is a manual process. Contact shibboleth-mgr@illinois.edu for assistance with the InCommon registration.

Testing

If you did everything correctly, your Shibboleth service should now be working.

Try visiting https://your.host.name/Shibboleth.sso/Login. You will be redirected to a discovery service or a login page depending on your configuration.

Complete the login process, and you will be sent back to document root on your server.

If you receive an error, consult the native service provider troubleshooting section of the Shibboleth project Wiki at https://wiki.shibboleth.net/confluence/display/SHIB2/Troubleshooting (external link) or contact shibboleth-mgr@illinois.edu.

Logs

If you encounter any problems with testing, or if you want to check up on what Shibboleth is doing, Shibboleth offers a robust set of logs.

You can configure logging to meet your needs. This can be done with the files ending in .logger located in the same directory as your shibboleth2.xml. The log facilities that you can configure are:

• shibd_log for shibd messages
• native_log for basic operations, and
• tran_log for logging of the attributes (but not the values) that your SP receives from an IDP.

For specifics on configuring these logs, see the comments in shibd.logger and configure as needed. The defaults are probably fine for most setups. A syslog.logger and console.logger are also available if you prefer.

Consuming attributes from Shibboleth

Now that your service provider is working, you'll want to put your application behind it. This means consuming the attributes that you requested into your application so you can use them.

• On IIS web servers: You'll find these attributes passed as http header variables to any location on your server that you've placed behind Shibboleth.
• On Apache-based systems: You can have attributes passed to your application as header variables or more securely through environment variables. A sample Apache configuration for using Apache's modshib to protect a location on the webste might look like this. This can be placed in your Apache server config, a virtualhost block, or a .htaccess file:

AuthType shibboleth

ShibRequestSetting requireSession 1 # Authentication required

ShibRequestSetting shibUseEnvironment 1 # Pass returned attributes as environment vars

require valid-user

More complex configurations and many other options can be found in the Shibboleth project Wiki.