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

This documentation will walk system administrators through setting up a basic Shibboleth SP SSO implementation within Elentra. For further information related to Shibboleth SP, please consult the Shibboleth documentation wiki.

This basic implementation supports both SSO and local user account authentication within Elentra. If your institution only wants to support SSO with no local user account access, then please ensure that you add /api/v2 as an exception.

Add /api as an exception if calendar subscriptions are not working.

See this section for details on how to set these up.

1. Create a yum repository reference by generating a yum repo file using the generation tool available on the Shibboleth website. The following is an example for RHEL/CentOS 7.

   vim /etc/yum.repos.d/shibboleth.repo
   
   [shibboleth]
   name=Shibboleth (CentOS_7)
   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

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="[e-mail]"
               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 modify the existing <Directory> directive to match below, and add the following <Location> directive within the <VirtualHost *:443> definition. This tells Shibboleth to operate in passive mode for the site:

   vim /etc/httpd/conf.d/000-elentra.conf
   
   <Directory "/var/www/vhosts/<your vhost>/current/www-root">
       Options FollowSymLinks
   #   Require all granted
       AllowOverride all
   
       ShibRequestSetting applicationId <your application ID>
       AuthType shibboleth
       Require shibboleth
   </Directory>
     
   <Location /Shibboleth.sso>
       SetHandler shib
   </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.

Authentication Methods

Our institution only wants to allow SSO authentication with no local user accounts. When we configure the Shibboleth SP this way, we can no longer log into Elentra.

Perhaps you have not added /api/v2 as an exception and Shibboleth is also protecting the API, which means Elentra is unable to access its own API. Add the following snippet to /etc/httpd/conf.d/000-elentra.conf and be sure to restart Apache afterwards.

<Location /api/v2>
    Satisfy Any
    Allow from all
    AuthType None
    Require all granted
</Location>

Calendar subscriptions are not working when we set up Shibboleth.

Add /api as an exception like above. The calendar subscription API (e.g. json and ics) is still in www-root/api, and not in elentra-1x-api yet, therefore the /api/v2 exception above would not be sufficient.

<Location /api>
    Satisfy Any
    Allow from all
    AuthType None
    Require all granted
</Location>

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 [e-mail]
   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>