How do I install and configure a Shibboleth Service Provider for a Web Service?

Overview

This article provides detailed information regarding how to install and configure a shibboleth service provider.
 

Red Hat Enterprise Linux, CentOS & SUSE Linux

The best way to install shibboleth on these platforms is to use the yum software management tool. Access to a Yum repository can be configured by visiting this site:

https://shibboleth.net/downloads/service-provider/RPMS/

Then, to install shibboleth:

​sudo yum install shibboleth

sudo systemctl start shibd.service

RPMs are no longer supplied for Centos/Redhat in standard locations but you can create a file called:

/etc/yum.repos.d/shibboleth.repo

with this content:

[shibboleth]
name=Shibboleth (CentOS_7)
# Please report any problems to https://shibboleth.atlassian.net/jira
type=rpm-md
mirrorlist=https://shibboleth.net/cgi-bin/mirrorlist.cgi/CentOS_7
gpgcheck=1
gpgkey=https://shibboleth.net/downloads/service-provider/RPMS/repomd.xml.key
        https://shibboleth.net/downloads/service-provider/RPMS/cantor.repomd.xml.key
enabled=1

then run sudo yum install shibboleth

Other Platforms

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

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

IMPORTANT NOTE: It can take up to 4 hours for the UIC IDP to receive any changes to I-Trust metadata.

Configure your service provider


/etc/shibboleth/shibboleth2.xml file

You can either download a sample configuration from UIUC here:

https://answers.illinois.edu/images/group180/shared/Shibboleth/example-shibboleth2.xml

Or edit the file that comes with the installation. If you use the sample configuration from UIUC you will need to make a few changes:

replace:

SSO entityID="urn:mace:incommon:uiuc.edu"

with

SSO entityID="https://shibboleth.uic.edu/shibboleth"

replace:

ApplicationDefaults entityID="https://hostname.illinois.edu/shibboleth"

with

ApplicationDefaults entityID="https://hostname.uic.edu/shibboleth"

The Discovery service and I-Trust metadata locations should remain in the illinois.edu domain.

Configure I-Trust metadata

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

cd /etc/shibboleth

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

Download attribute-map.xml

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

Edit the file and uncomment the attributes you will need.

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


Optional: restricting access to an application

If you wish your application to be only accessible from a subset of UIC netids you will need to create (and maintain) an Active Directory Group:

https://help.uillinois.edu/TDClient/37/uic/Requests/ServiceOfferingDet?ID=61

Open a ticket with ithelp@uic.edu to request an Entitlement attribute/value be associated with your Group. The Shibboleth Identity Provider will be configured to release attributes to your application based on this.


Optional: requesting MFA (Duo)

Edit /etc/shibboleth/shibboleth2.xml and change the appropriate line to look like this:

            <SSO entityID="https://shibboleth.uic.edu/shibboleth"
                authnContextClassRef="https://refeds.org/profile/mfa">SAML2</SSO>

Restart the shibd service.

50% helpful - 2 reviews
Print Article