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.
-
Primary Contact - enter your contact details. This is where confirmation and registration emails will be sent to.
-
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
-
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.
-
Public Key Certificate
-
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:
-
requested in I-Trust (View SP > SAML > Attributes tab)
-
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.