Shibboleth Single Sign-on

The following guide/documentation can be used as a reference to install and configure Shibboleth SP v3 on Red Hat Enterprise Linux or CentOS 7.

Shibboleth Installation

For further information related to Shibboleth SP installation, please consult the Shibboleth documentation wiki.

  1. Create a yum repository reference, and add the following information (CentOS/RHEL):

    vim /etc/yum.repos.d/shibboleth.repo
    [security_shibboleth]
    name=Shibboleth (CentOS_7)
    type=rpm-md
    baseurl=http://download.opensuse.org/repositories/security:/shibboleth/CentOS_7/
    gpgcheck=1
    gpgkey=http://download.opensuse.org/repositories/security:/shibboleth/CentOS_7/repodata/repomd.xml.key
    enabled=1

  2. Install Shibboleth Service Provider (SP) component:

    yum install shibboleth.x86_64
  3. Start the Shibboleth daemon (shibd) and enable for system startup:

    systemctl enable shibd
    systemctl start shibd

Shibboleth Configuration

Please Note: different institutions will have wildly different Shibboleth configuration requirements. The following should be taken as an example.

  1. In the Shibboleth configuration directory /etc/shibboleth edit the file shibboleth2.xml:

    cd /etc/shibboleth
    vim shibboleth2.xml
  2. Change the ApplicationDefaults entry and add entityID:

    <ApplicationDefaults entityID="https://elentra.med.university.edu" REMOTE_USER="eppn persistent-id targeted-id">
  3. Configure the SSO section with the IDP URL:

    <SSO entityID="https://shibidp.university.edu/idp/shibboleth"
    discoveryProtocol="SAMLDS" discoveryURL="https://ds.example.org/DS/WAYF">
    SAML2 SAML1
    </SSO>
  4. Edit the Errors section to update the supportContact:

    <Errors supportContact="[email protected]"
    helpLocation="/about.html"
    styleSheet="/shibboleth-sp/main.css"/>
  5. Find the example MetadataProvider entries, and add a new one after the examples:

    <!-- University IDP -->
    <MetadataProvider type="XML" url="https://shibidp.university.edu/idp/profile/Metadata/SAML"
    backingFilePath="idp-metadata.xml" minRefreshDelay="120" reloadInterval="120">
    </MetadataProvider>
  6. Set up the attribute mapping which will identify which IDP provided attributes should be presented to the application in the $_SERVER variable. Add the block below to the configuration file just after the AttributeResolver section.

    <!-- UNIVERSITY BEGIN -->
    <ApplicationOverride entityID="https://elentra.med.university.edu" id="elentra.med.university.edu">
    <Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
    checkAddress="false" handlerSSL="true" cookieProps="https" handlerURL="/Shibboleth.sso" />
    <AttributeExtractor type="XML" file="AttributeRelease/elentra.med.university.edu-attribute-map.xml" />
    </ApplicationOverride>
    <!-- UNIVERSITY END -->
  7. Create a directory AttributeRelease and add a file called elentra.med.university.edu-attribute-map.xml. This file should contain the appropriate IDP attributes. Please consult your local IDP expert.

    mkdir /etc/shibboleth/AttributeRelease
    vim /etc/shibboleth/AttributeRelease/elentra.med.university.edu-attribute-map.xml
    <Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Attribute name="TBD" id="employeeID" />
    </Attributes>
  8. Update the 000-elentra.conf Apache configuration file and add the following to the VirtualHost definition. This tells Shibboleth to operate in passive mode for the site:

    vim /etc/httpd/conf.d/000-elentra.conf
    <Location />
    ShibRequestSetting applicationId elentra.med.university.edu
    AuthType shibboleth
    Require shibboleth
    </Location>
  9. Update the shib.conf Apache configuration file and comment out the following lines within the file:

    vim /etc/httpd/conf.d/shib.conf
    #<Location /secure>
    # AuthType shibboleth
    # ShibRequestSetting requireSession 1
    # require shib-session
    #</Location>
  10. Restart Shibboleth and Apache:

    systemctl restart shibd
    systemctl restart httpd

Shibboleth Metadata

You can manually retrieve the application servers Shibboleth metadata for your local IDP team by accessing /Shibboleth.sso/Metadata and saving the output as an XML file.

curl -k https://<hostname>/Shibboleth.sso/Metadata > /home/production/elentra-metadata.xml

If you are running your servers behind a load balancer you can temporarily modify the /etc/hosts file and add 127.0.0.1 <hostname> before you call the curl command above. If you don't do this, there is no guarantee you will hit the correct server. Once you have saved the metadata, simply remove this temporary line. Once you have setup Shibboleth up on one of the servers in the cluster, you can copy your /etc/shibboleth directory to the other servers.

PHP Configuration

There is one PHP setting that can cause issues with Single Sign-on. Within /etc/php.d/elentra.iniensure that session.cookie_samesite is set to Lax, and then restart Apache.

vim /etc/php.d/elentra.ini
session.cookie_samesite = Lax
systemctl restart httpd

Elentra ME Configuration

Elentra ME requires a few configuration changes as well in order to utilize SSO.

  1. Ensure that your Elentra ME .htaccess file contains:

    RewriteRule ^Shibboleth.sso/* - [L,NC]

    This rule should appear just before the Default Elentra ME Rules:

    ...
    RewriteRule ^.* - [L,QSA]
    RewriteRule ^Shibboleth.sso/* - [L,NC]
    # Default Elentra ME Rules
    RewriteRule ^api/v2/(.*)$ api/v2/index.php/$1 [L,QSA]
    ...
  2. Ensure that the AUTH_METHOD in your settings.inc.php file is (or contains) sso:

  3. Review the other settings available in settings.inc.php @todo:

/**
* SSO Configuration
*/
define("AUTH_SSO_ENABLED", true); // Enable SSO in addition to local or ldap login
define("AUTH_SSO_TYPE", "Shibboleth"); // SSO Implementation used. One of "Cas" or "Shibboleth"
define("AUTH_SSO_LOCAL_USER_QUERY_FIELD", "number"); // The field name from the user_data table of the Authentication database used to match against the identifier supplied by SSO
define("AUTH_SSO_ID_DECODE_CALLBACK", ""); // If the identity key (AUTH_SHIB_ID, AUTH_CAS_ID) requires massaging before looking up in user_data, provide a name of a callback function that takes
// the value returned as input e.g. "Entrada_Utilities::decodeActiveDirectoryGuid"
...
define("AUTH_SHIB_URL", "https://elentra.med.university.edu"); // URL of the Shibboleth Service Provider (SP) service
define("AUTH_SHIB_LOGIN_URI", "/Shibboleth.sso/Login"); // The URI to request Shibboleth SP to authenticate the user
define("AUTH_SHIB_LOGOUT_URI", "/Shibboleth.sso/Logout?return=" . rawurlencode("https://login.university.edu/logout")); // The URI to request Shibboleth SP to invalidate the user's session(s)
define("AUTH_SHIB_SESSION", "Shib-Session-ID"); // The variable in $_SERVER containing the SP session if authentication succeeds
define("AUTH_SHIB_ID", "shib-studentid"); // The variable in $_SERVER set by SP that holds the identity key provided by Shibboleth
// This value will be compared against user_data.AUTH_SSO_LOCAL_USER_QUERY_FIELD column in auth database

Troubleshooting

Every single sign-on installation is a snow flake. We have built up some decent experience installing and configuring Shibboleth over the years, and will share some factoids, tips, and tricks in this section.

Load Balancer

HTTPS to the load balancer, then HTTP between the load balancer and the application servers in the cluster.

Note line 3 and line 4 in the following 000-elentra.conf excerpt. It doesn't read like it makes sense, but is required for Shibboleth to function via port 80.

...
<VirtualHost *:80>
ServerName https://elentra.med.university.edu:443
ServerAdmin [email protected]
DocumentRoot /var/www/vhosts/elentra.med.university.edu/current/www-root
<Directory "/var/www/vhosts/elentra.med.university.edu/current/www-root">
Options FollowSymLinks
Require all granted
AllowOverride all
</Directory>
<Location />
ShibRequestSetting applicationId elentra.med.university.edu
AuthType shibboleth
Require shibboleth
</Location>
</VirtualHost>