How do I install and configure Shibboleth?

Install Shibboleth service provider software

Red Hat Enterprise Linux, CentOS, and SUSE Linux

The best way to install shibboleth on these platforms is to use the yum software management tool. Yum repositories are provided for these platforms by opensuse.org. Visit http://download.opensuse.org/repositories/security://shibboleth/ to view supported platforms. Click through to the appropriate operating system then download the “security:shibboleth.repo” file and save it to /etc/yum/repos.d/shibboleth.repo.

For CentOS 7 this can be accomplished with the following command:

sudo curl -o /etc/yum.repos.d/shibboleth.repo http://download.opensuse.org/repositories/security://shibboleth/CentOS_7/security:shibboleth.repo

Then, to install shibboleth:

​sudo yum install shibboleth

sudo systemctl start shibd.service

Other Platforms

Installation instructions for other platforms can be found in the Shibboleth wiki.

Create and register your service provider identity with the I-Trust Federation

Determine your Shibboleth service provider’s entityID

Shibboleth service provider refers to your server. We recommend your entity ID should be based on your website’s hostname. This is not necessarily the hostname of the server on which the site is running. It is the hostname that will appear in the user’s browser location bar. If your site is accessed as:

https://foo.example.uic.edu/protected/resource

Then your hostname is foo.example.uic.edu and your entityID should be:

https://foo.example.uic.edu/shibboleth

Note that the path of the website is not used in constructing your entityID.

Generate your Shibboleth SSL certificate

Important note: the Shibboleth SSL certificate is not the same as your web server’s SSL certificate. It’s an additional certificate, used specifically for Shibboleth.

You should generate a new key and certificate, including your shibboleth service provider hostname and entity ID as part of the certificate data.

For Red Hat Enterprise Linux, CentOS or other Linux based systems you can generate your SSL certificate and key. Go to your Shibboleth configuration directory:

cd /etc/shibboleth

Using the following command, substituting your server’s web address:

​sudo ./keygen.sh -h foo.example.uic.edu -e https://foo.example.uic.edu/shibboleth -f -y 10

This will create a file called sp-cert.pem which contains your server certificate. Make sure that the key and cert are owned by shibd user and group:

sudo chown shibd:shibd /etc/shibboleth/sp-key.pem

sudo chown shibd:shibd /etc/shibboleth/sp-cert.pem

For Windows based systems there is an equivalent keygen.bat normally found in c:\opt\shibboleth-sp\etc.

Register your service provider with the I-Trust federation

Using the hostname and entity ID determined above, register your server with I-Trust. Visit I-Trust Federation Registry and click Create a new Service Provider.

  1. Primary Contact - enter your contact details. This is where confirmation and registration emails will be sent to.

  2. Service Provider Description

    • Organization: University of Illinois at Chicago

    • Display Name: short (one-two word) description of your server

    • Description: longer description

    • Service URL: web address of your server

  3. SAML Configuration

    • In “Easy registration using defaults” section select “Shibboleth Service Provider (2.4.x or 2.5.x)”

    • In the URL field, enter the https:// URL of your server. The Advanced SAML 2 registration section should auto-complete.

  4. Public Key Certificate

    • Paste the contents of sp-cert.pem (located in your Shibboleth configuration directory).

  5. Requested Attributes - select some attributes in order to be able to identify users that login to your application. A few attributes in particular that you should consider:

    • eduPersonPrincipalName (aka eppn). The primary identification string for an individual. It is equivalent to the user’s scoped NetID including @uic.edu or @illinois.edu.

    • iTrustUIN. This is the best persistent user identifier. Unlike the eppn or NetID, this identifier normally does not change through the life of an identity.

    • uid. The user’s NetID without the scoped campus portion.

Important note: You will be asked to provide a reason for requesting the attributes. For example, you might ask for eppn or uid in order to use it as the username in your application.

After you submit the form, you should receive an email receipt. The registration process may take a couple of business days. When your registration is approved, you will receive an additional email with instructions to complete the registration.

Configure your service provider

shibboleth2.xml file

We provide a custom shibboleth2.xml configuration file generated for your service provider. Visit our Shibboleth tool to generate your file.

  1. Enter your website’s hostname.

  2. Enter your support email address.

  3. Provide the web address of your contact or help page.

  4. Select whether you want to restrict your users to UIC or all of the University of Illinois.

Save with the file name shibboleth2.xml to your shibboleth configuration directory. (/etc/shibboleth on Linux, or c:\opt\shibboleth-sp\etc on Windows systems).

Configure I-Trust metadata

Download the itrust.pem certificate file from: https://discovery.itrust.illinois.edu/itrust-certs/itrust.pem to /etc/shibboleth. Example commands:

cd /etc/shibboleth

sudo wget https://discovery.itrust.illinois.edu/itrust-certs/itrust.pem

Download attribute-map.xml

Download attribute-map.xml file from https://accc.webhost.uic.edu/shibboleth/attribute-map.xml to the Shibboleth configuration directory (on CentOS 7 /etc/shibboleth).

Important note: Make sure that the attributes are looking for are:

  1. requested in I-Trust (View SP > SAML > Attributes tab)

  2. present in the attribute-map.xml file

Start your service provider

On CentOS 7:

sudo systemctl start shibd.service

Shibboleth logs are located in /var/log/shibboleth/shibd.log

On CentOS 7 you can check if your service provider appears in I-Trust with the following commands:

cd /var/cache/shibboleth

grep foo.example.uic.edu itrust-metadata.xml

If you get any kind of output, it means your service provider appears in I-Trust.

Test your installation by visiting:

https://foo.example.uic.edu/secure

Shibboleth and SELinux

You will have to take additional steps if you have SELinux enabled. The following instructions have been adapted from Tuakiri

To configure SELinux to allow Apache (where mod_shib is loaded) to connect to shibd create a policy type enforcement file defining a policy module mod_shib-to-shibd. Create a file named mod_shib-to-shibd.te with the following contents:

module mod_shib-to-shibd 1.0;
require {
       type var_run_t;
       type httpd_t;
       type initrc_t;
       class sock_file write;
       class unix_stream_socket connectto;
}

#============= httpd_t ==============
allow httpd_t initrc_t:unix_stream_socket connectto;
allow httpd_t var_run_t:sock_file write;

Compile, package and load the module with the following 3 commands:

checkmodule -m -M -o mod_shib-to-shibd.mod mod_shib-to-shibd.te

semodule_package -o mod_shib-to-shibd.pp -m mod_shib-to-shibd.mod

semodule -i mod_shib-to-shibd.pp
Finally restart shibd.service with:
sudo systemctl restart shibd.service

Need help?

Last updated: 

September 20, 2016

Browse by tag