Comment on page
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.
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.- 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_7gpgcheck=1gpgkey=https://shibboleth.net/downloads/service-provider/RPMS/repomd.xml.keyhttps://shibboleth.net/downloads/service-provider/RPMS/cantor.repomd.xml.keyenabled=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 shibdsystemctl start shibd
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 fileshibboleth2.xml
:cd /etc/shibbolethvim shibboleth2.xml - 2.Change the
ApplicationDefaults
entry and addentityID
:<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 thesupportContact
:<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 theAttributeResolver
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 calledelentra.med.university.edu-attribute-map.xml
. This file should contain the appropriate IDP attributes. Please consult your local IDP expert.mkdir /etc/shibboleth/AttributeReleasevim /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 grantedAllowOverride allShibRequestSetting applicationId <your application ID>AuthType shibbolethRequire 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 shibdsystemctl restart httpd
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.There is one PHP setting that can cause issues with Single Sign-on. Within
/etc/php.d/elentra.ini
ensure 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 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 RulesRewriteRule ^api/v2/(.*)$ api/v2/index.php/$1 [L,QSA]... - 2.Ensure that the
AUTH_METHOD
in yoursettings.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
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.
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>
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>
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>
Last modified 5mo ago