Internet2 is investigating a security incident involving a compromise to a confluence server that affected https://spaces.at.internet2.edu on April 10, 2019, which was successfully mitigated on April 12, 2019. If you did not receive an email from us, it’s unlikely that any of the content you submitted to the Internet2 Spaces Wiki needs to be re-entered. We apologize for any inconvenience this may have caused. Should you have any questions or require further assistance, please email collaboration-support@internet2.edu.
Child pages
  • Linux Service Provider (RHEL 7.0)
Skip to end of metadata
Go to start of metadata

Section 0: VM Preconfiguration

Complete the preparation required in Linux Preparation for Participants before you continue.

Notes: This document is not meant to be a complete discussion on anything you might ever do with an SP. There are many topics of potential interest that are left out of this document in an attempt to keep it more focused on getting a basic SP up and running. This document is meant as a guide to help you get your SP working and in understanding how to care for it. Please read the official Shibboleth project documentation (linked to occasionally from this document) for a deeper understanding.

Note

Before you begin, if you had previously used the same VM to perform the IdP installation and Docker is running, you will need to turn it off so that httpd can bind to 0.0.0.0:443.

systemctl stop docker

Section 1: Install

1. Understand the Shibboleth SP
2. Download the Shibboleth SP software
    • Paste the following text into the file /etc/yum.repos.d/shibboleth.repo (overwriting anything that was already there, or creating the file if it doesn't exist)

      [shibboleth]
      name=Shibboleth (CentOS_7)
      # Please report any problems to https://issues.shibboleth.net
      type=rpm-md
      mirrorlist=https://shibboleth.net/cgi-bin/mirrorlist.cgi/CentOS_7
      gpgcheck=1
      gpgkey=https://downloadcontent.opensuse.org/repositories/security:/shibboleth/CentOS_7/repodata/repomd.xml.key
      enabled=1

      For operating systems other than CentOS 7, you may generate a custom shibboleth.repo file by going to https://shibboleth.net/downloads/service-provider/RPMS/.

3. Install the Shibboleth SP software on your web server

  • Objective:
    • Successfully install the Shibboleth SP software on your server.
  • Tasks:
    • Run the command:
      yum install shibboleth
      
  • Resources:
  • Success Factors:
    • The Shibboleth SP software has been successfully installed on your web server.
    • rpm -qa | grep shibboleth should show that the Shibboleth package has been installed.
    • The runtime Shibboleth directory will now exist at /etc/shibboleth
    • Shibboleth requires that messages passed between the IdP and the SP have similar, current, and consistent time-stamps.  Please check the ntpd service is running with:
      systemctl status ntpd 
      

      If it is not, please start the ntpd service:

      systemctl start ntpd

      If it is not installed, please install with:

      yum install ntp
      systemctl start ntpd
4. Basic Apache configuration

    • As part of the SP installation process, a basic set of Apache configuration directives to load mod_shib and protect the sample directory /secure were placed in /etc/httpd/conf.d/shib.conf. You shouldn't need to modify this file, but it can be a convenient place to put additional resource protection directives in the future.
  • Objective:
    • If Apache httpd is not installed, install it (and the SSL module) via yum:

      yum install httpd mod_ssl
    • Turn on canonical name use by Apache in /etc/httpd/conf/httpd.conf by adding the following.  This directive is no longer in the example configuration, so its placement is now a deployment choice.  It should be placed along with all your other server naming directives, however you'll be doing your web space allocation.  Placing it near the Include directive for the conf.d directory is fine for this class since we won't use multiple hostnames.


      UseCanonicalName On
      ServerName my.special.name:80


      The UseCanonicalName directive is used in virtualization.  When Apache generates URLs in response to inbound requests, it will typically use the Fully-Qualified Domain Name (FQDN) of the requested host to ensure that the client continues to be able to access the service.  However, multiple paths for the same resource would each need to be protected in order to prevent unauthorized access.  UseCanonicalName tells Apache to use the configured server name rather than the name in the HTTP request in all cases, ensuring proper virtualization and content protection and reducing your configuration burden.


    • We recommend disabling non-SSL (http://) access to sensitive resources that require Shibboleth protection.  This is to reduce the probability that a client will attempt to issue an HTTP request with cookies or other sensitive information in them in plaintext prior to the message ever reaching the server in the first place.  To do so, you can use the following configuration (preferably in a port 80 VirtualHost, but simply adding it to the appropriate part of /etc/httpd/conf/httpd.conf is also okay, generally where the commented out examples for each live):
      RewriteEngine On
      RewriteCond %{HTTPS} off
      RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
      
    • Or, this configuration: (wink)  Either is sufficient on its own, and if you do both, the commented out listener will render the earlier rules inactive, but that's fine.
      #Listen 80
      
    • Add mod_ssl (if not already installed: check to see if the file /etc/httpd/conf.d/ssl.conf exists)
      yum install mod_ssl
      
  • Resources:
  • Success Factors:
    • Your web server forces use of https://my.special.name/. (or, your web server knows its name and insists that it always be spelled properly, and will not speak to you in public)
5. Verify that your new Shibboleth SP is alive

  • Objective:
    • Successfully load the SP's "Status" page
  • Tasks:
    • Start shibd using systemctl start shibd.
    • Start httpd with systemctl start httpd.  You will need to restart httpd for subsequent changes in this task to take effect. 
      • If httpd has problems binding to port 80, with error messages like Address already in use, you have another service already listening on port 80.  It's probably Jetty hosting the IdP, so be sure it's turned off with systemctl stop shibboleth-idp.
    • Try accessing the URL https://127.0.0.1/Shibboleth.sso/Status from inside your VM (you may need to restart the web service first):
      curl -k https://127.0.0.1/Shibboleth.sso/Status
      Note that handler URLs such as /Shibboleth.sso/Status are case sensitive. If you see a 404 error or a shibsp::ConfigurationException page with the message "Shibboleth handler invoked at an unconfigured location," Check that your URL exactly matches the example above, and make sure it does not have a trailing slash.
    • The status handler will display a lot of build and configuration information about your SP.  It won't be immediately useful or meaningful to you, but it does show that your SP is operational.
    • The status handler is protected by an IP address ACL, which means you need to either perform this task from the web server itself or edit the ACL for the /Status handler in /etc/shibboleth/shibboleth2.xml. Keep in mind that the list is space delimited.
      <Handler type="Status" Location="/Status" acl="127.0.0.1 192.168.100.1 10.0.0.3"/>
      

      You can also access the status page by adding your laptop's IP address to the ACL and visiting https://my.special.name/Shibboleth.sso/Status, which is a more common example for monitoring purposes (you may need to restart your web server first). An easy way to ensure that you've added the right IP to the ACL is to source it from Apache's access logs at /var/log/httpd/ssl_access_log.

  • Resources:
  • Success Factors:
    • Able to successfully load the SP's status page
6. Understand the files and directories of the SP

  • Objective:
  • Detail:
    • /etc/shibboleth
      • The main directory for configuration files for the Shibboleth SP
    • /usr/sbin/shibd
      • This is the shibboleth daemon
      • It is useful to run it from the command line with the -t option to check your configuration for errors before attempting a service restart
    • /var/log/shibboleth
      • This is the main directory for Shibboleth SP log files
      • shibd.log is the main log file and the first place to look for errors
      • transaction.log contains summary information about each transaction processed by the SP
    • /var/log/shibboleth-www/native.log
      • This log file contains messages logged by mod_shib
      • Before starting Apache, be sure to give Apache ownership of its log directory by running chown apache /var/log/httpd.
    • /usr/lib64/shibboleth
      • The location of the Shibboleth SP extensions/modules
    • /etc/httpd/conf.d/shib.conf
      • The location of Shibboleth SP-specific Apache configuration directives. This file is designed to be included at start time in your main apache config.
    • *.dist files are just copies of the original files that shipped with Shibboleth.
  • Success Factors:
    • Able to explain the different log files created by the Shibboleth SP and their location on the server.

Section 2: Configure

1. Create your default SAML entityID

  • Objective:
    • Configure an appropriate default SAML entityID for your SP
  • Tasks:
    • Set the entityID parameter, located in the <ApplicationDefaults> element in /etc/shibboleth/shibboleth2.xml.  Be sure you're working on the opening tag.
    • The best bet is to just follow the suggested name, with appropriate modifications for your hostname (i.e. https://my.special.name/shibboleth)
  • Resources:
  • Success Factors:
    • Default SAML entityID is properly defined and configured. This can be validated by looking at <Application id="default" entityID="https://my.special.name/shibboleth"/> as returned by the Status handler if you feel so inclined.
2. Configure the SP to require SSL for cookies

  • Objective:
    • Configure the Shibboleth SP to set secure cookies
  • Tasks:
    • Locate the <Sessions> element inside the <ApplicationDefaults> element within shibboleth2.xml in /etc/shibboleth.
    • The Sessions element contains sessions timeouts and settings that affect how the SP responds to most requests directly issued to it by clients. Most of those default settings work fine, but the default is not to force SSL/TLS for cookie and assertion presentation. As these are bearer tokens, if they are stolen, then they can be used to impersonate an authenticated user. We would like to prevent that.
    • It's good practice to require secure cookies by forcing cookieProps="; path=/; secure; HttpOnly", which can be done through the convenient shorthand cookieProps="https".  Even if you have disabled http:// on your server, this will tell the browser to only deliver cookies over SSL, further reducing the chance that user error will expose a cookie.
      <Sessions lifetime="28800" timeout="3600" checkAddress="false"
                  relayState="ss:mem" handlerSSL="true" cookieProps="https">
      
    • It's also good practice to use consistentAddress="true" when possible, as documented in the link below.
    • If you can't convince an application administrator to only require access over https://, then don't set cookieProps to secure. However, you can at least set handlerSSL="true", which will force the assertion itself to be delivered over SSL. But since the assertion over HTTPS is arguably better secured than a cookie over HTTPS, you should really talk harder more to the application administrator.
  • Resources:
  • Success Factors:
    • The SP sets cookies with the secure flag. These session cookies will not be set until a user successfully logs in, so it's hard for you to validate this now, but later you can look at the contents of _shibsession cookies in the browser.
3. Define/Load a metadata source

  • Objective:
    • Configure a source of metadata for your SP and, in production scenarios, verify the signature on the metadata and require it to have a maximum validity period.
  • Tasks:
    • Add the metadata provider described below to shibboleth2.xml.
    • For production, you should require digitally signed metadata and you should validate it.
    • You should also require a validUntil parameter in the metadata and specifying a "reasonable" value for maxValidityInterval is advisable.
    • For this training, your SP's MetadataProvider element will look like this. Add it next to the example, commented-out Example of locally maintained metadata MetadataProvider element.
              <!-- Example of locally maintained metadata. -->
              <!--
              <MetadataProvider type="XML" validate="true" file="partner-metadata.xml"/>
              -->
       
              <!-- Classroom metadata -->
              <!-- By copying and pasting this clickthrough agreement, I pledge on my -->
              <!-- mom's favorite food to never, ever use untrusted metadata in production -->
              <MetadataProvider type="XML" uri="http://md.training.incommon.org/downloads/ShibTrain1-metadata.xml"
               backingFilePath="ShibTrain1-metadata.xml" reloadInterval="7200" />
      

      The backingFilePath is generally a relative path, and that path depends on the OS on which the SP has been installed and the manner in which the installation occurred.  In most cases, you'll find it in a POSIX-style /var/cache/shibboleth.  Absolute paths may be used if you have some reason to do so.

    • You can test the resulting configuration by running the mdquery utility from the command line.  This command will use the SP's configuration as a list of metadata sources and it will search through all those sources for string matches.  You should expect to see a couple pages of XML that describes the IdP completely to your SP, including its entityID, certificates and endpoints.
      mdquery -e https://idp.training.incommon.org/idp/shibboleth -idp -saml2
      

      mdquery may complain that "libcurl lacks OpenSSL-specific options; this will greatly limit functionality". This warning is safe to ignore.

    • There is also a special endpoint at /Shibboleth.sso/DiscoFeed that exposes the list of identity providers that the SP recognizes.  Some discovery interfaces can retrieve this and further prune the list of options by presenting the union of providers the DS trusts and providers the SP trusts to a user.

  • Resources:
  • Success Factors:
    • SP has successfully loaded a metadata source. This can be done by running mdquery, or checking for a file in the backingFilePath that you used.
4. Configure Session Initiation

  • Objective:
    • Configure the SP to use the classroom Discovery Service and IdP to start new user sessions
  • Tasks:
    • In the SSO element in /etc/shibboleth/shibboleth2.xml, modify the SSO element's discoveryURL="https://ds.example.org/DS/WAYF" URL to be https://ds.training.incommon.org/shibboleth-ds. Also, modify the default entityID to be https://idp.training.incommon.org/idp/shibboleth. The successfully modified SSO element will look like this:
      <SSO entityID="https://idp.training.incommon.org/idp/shibboleth" discoveryProtocol="SAMLDS"
           discoveryURL="https://ds.training.incommon.org/shibboleth-ds">
             SAML2 SAML1
      </SSO>
      


      The SSO handler will send users, by default, directly to the test IdP to authenticate there. If there were no default entityID defined or provided as part of the web environment or query, they would be sent to the Discovery Service (DS) next.

    • You can use query strings and other methods to send users directly to a specified IdP only for certain requests. There are examples in the wiki page below.
  • Resources:
  • Success Factors:
    • Requests for Shibboleth-protected URLs are successfully redirected to the Test IdP. This can be validated by going to https://my.special.name/secure if you like, but you'll just be presented with an error page ("Unsupported Request") because the rest of the configuration process is incomplete.
5. Configure the attribute-map.xml file

  • Objective:
    • Configure/uncomment the attributes that your applications will need in the attribute-map.xml configuration file (for the class, just uncomment every Attribute element in this file; however, watch out for deprecated configuration editions for certain attributes.  Each attribute definition must have at most one decoder, so if you uncomment some deprecated decoders too [in particular, eduPersonTargetedID], you will experience errors on start.)
  • Tasks:
    • Make sure that all attributes needed by your applications protected by this SP are defined in the attribute-map.xml file in /etc/shibboleth/. Most commonly used attributes are already defined in the file and may just need to be uncommented. Any local or organization-specific attributes used by your applications will also need to be defined in this file, and the SAML names must match those configured at the partner IdP(s).
    • attribute-map.xml functionality may be thought of in many ways as the obverse of the identity provider's attribute-resolver.xml.
    • The reason these are commented out by default, is that this part of the SP's code must run on every request. The fewer attributes that it needs to iterate through, the faster the SP – and the rest of the web server – is. Practically speaking, though, this will not be an issue in most deployments, since the performance impact is not large.
  • Resources:
  • Success Factors:
    • SP is able to process and map all needed attributes. This can be seen in the SP's shibd.log with log level set to DEBUG (per the next step), but will be most obvious later when you test SSO.
6. Turn on DEBUG-level logging in shibd.logger

7. One Last Check...

  • Objective:
    • After the configuration changes, confirm that your SP is still able to load its configuration (and thus is operating properly)
  • Tasks:
    • Use shibd from the command line to check your configuration.  You can do this at any time, and it's especially useful if your web server appears to be unresponsive.
      • /usr/sbin/shibd -t
      • You should see the words overall configuration is loadable, or a fascinating error message.
      • check console for non-fatal problems is a placeholder message to ensure that deployers check appropriate logging facilities(stdout is used for severe cases, so it's obvious) for WARNs or ERRORs indicating configuration mistakes that aren't severe enough to prevent shibd from initializing, but are severe enough to cause problems in actual operation.
    • Restart your web server and shibd
    • You could also use the status page as a check if you preferred to do so.
      • curl -k https://127.0.0.1/Shibboleth.sso/Status
  • Resources:
  • Success Factors:
    • The shibd check and status page loads both complete successfully
8. Provide your SAML metadata to a federation or IdP so that others can use your new SP

  • Objective:
    • Provide your SP's default SAML metadata to an IdP or federation (the administrator's machine, in this case)
  • Tasks:
    • Retrieve your SP's default metadata from the Metadata Handler, located by default at https://my.special.name/Shibboleth.sso/Metadata.  Make sure to use the right hostname, because it's used by the SP to generate its own metadata.  We'll discuss why later.
      • On your host laptop (not the VM), Use the command curl -o metadata.xml -k https://my.special.name/Shibboleth.sso/Metadata .
      • The above command will write the metadata file to a file called metadata.xml in the current directory on your host laptop.
    • Download the metadata.xml file created to your host machine.  Mechanisms such as scp are less likely to introduce hidden dingbats that will cause parsing failures.
    • Upload the copy of your SP's metadata at the classroom metadata aggregator page: https://sp.training.incommon.org/mdupload/
    • The upload page requires a password.  The classroom instructors will communicate the upload password to you.
    • Classroom metadata is built every 2 minutes.  This is designed as a special test for the impatient, so please wait a couple of minutes before trying to test your new SP.
    • This metadata file is generated dynamically by the SP by polling its own configuration. This will work fine for most basic deployments, but if you have any special configurations and/or virtual hosts, you will need to configure your metadata manually (though you can typically use this file as a starting point).
  • Resources:
  • Success Factors:
    • Your SP's SAML metadata is visible to all the IdP's in the training federation, including the training IdP (once your metadata is added to the training metadata). If you feel the need to validate this, you can access http://md.training.incommon.org/downloads/ShibTrain1-metadata.xml and wade through the XML looking for your entry. Or you can just wait a little while and go on to the next step.

Section 3: Simple Resource Protection

1. Test with your SP's default /secure directory

  • Objective:
    • Authenticate successfully to your SP using the classroom's test IdP.
  • Tasks:
    • You can create a happy landing webpage for yourself at /var/www/html/secure if you are so inclined.
    • Access the resource using a web browser at https://my.special.name/secure, with the source page located at /var/www/html/secure/index.*. If everything is configured well, you will be asked to authenticate at the test IdP. After authenticating, you should be granted access to your secure resource. By default, you will see a 404 or your customized page after you have logged in. If you receive any error or other unexpected outcome, please look demotivated and raise your hand and a trainer will be with you shortly.
    • If your unexpected outcome includes Error Message: SAML 2 SSO profile is not configured for relying party <yourEntityID>, then your SP is not yet recognized by the training IdP.
    • If your unexpected outcome appears to be a perpetual loop, or a stalled browser, please stop your inadvertent load test and ensure that you are accessing your SP over https://. (note the 'S')
  • Resources:
  • Success Factors:
    • You can access the /secure directory after having authenticated successfully.
    • If you would like to see what the SP knows about you, you can access the Session Handler at https://my.special.name/Shibboleth.sso/Session from the web browser that has the active session.  You can also toggle the display of values and content type by setting showAttributeValues to true.  This should generally be disabled in production to limit information leakage.

2. Protect a New Resource

By default, Shibboleth is installed with the /secure path already Shib-protected.
  • Tasks: Protect /testscript and redirect the user to the testing DS, rather than directly to the test IdP. (can be done in /etc/httpd/conf.d/shib.conf)
  • Objective:
    • Configure a new URL path to require a Shibboleth session.
  • Tasks:
    • Protect /testscript and redirect the user to the testing DS, rather than directly to the test IdP.
    • Edit /etc/httpd/conf.d/shib.conf. Add a <Location> element to activate mod_shib to protect a new test script that we'll create later.
      <Location /testscript>
        AuthType shibboleth
        ShibRequestSetting requireSession true
        Require shibboleth
      </Location>
      
    • Disable direct-to-IdP session initiation. This is done by removing the entityID attribute in shibboleth2.xml's SSO element. The SP will iterate over inbound requests to see if an entityID is present anywhere.  As there is no default entityID present, nor an entityID supplied with the request, the SP will fall back to performing using the discoveryProtocol at the discoveryURL.
      <SSO discoveryProtocol="SAMLDS" discoveryURL="https://ds.training.incommon.org/shibboleth-ds">
                         SAML2 SAML1
                  </SSO>
      
    • Restart httpd.
    • Select the InCommon Training IdP rather than your own IdP.
  • Success Factors:
    • You will be redirected to the classroom discovery service.  If you select the InCommon Training IdP and login, you should be redirected back to your script.
3. Create a PHP test page that shows what attributes your SP knows about

Let's create a simple PHP test page to print variables at /var/www/html/testscript/test.php.  You will need to create the testscript directory.

 

Install PHP using yum install php.  Don't worry about a missing mbstrings library.  Restart httpd.

Your PHP test page need only contain the following (name your file with a .php file extension):

test.php
<html>
<head>
<title>Hello Shib World</title>
</head>
<body>
<?php phpinfo(); ?>
</body>
</html>

Now that discovery has been enabled, you will need to select the InCommon Training IdP to authenticate. If you want to bring up and use your own IdP, it's an exercise for the reader: you'll need to front Tomcat with Apache (because they can't both bind to 443) and set up attribute release.  You should see the output from the phpinfo() command, which includes a large amount of information about the web server's environment. Scroll through this output, and look for attributes sent from the Identity Provider, sometimes prefixed with SHIB. They will appear as server environment variables.

Go to https://my.special.name/testscript/test.php and try it out.

Some basic guidance on enabling applications is available from https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPEnableApplication.

Section 4: Shibbolized Drupal


1. Go to https://www.drupal.org/project/drupal/releases/7.59, grab the link, and curl -O the most recent version of Drupal 7. Decompress it.

We recommend using Drupal 7 because Drupal 8 requires PHP 5.5.9 or newer, but RHEL 7 currently still ships with PHP 5.4.

cd /opt
curl -O https://ftp.drupal.org/files/projects/drupal-7.59.tar.gz
tar -zxvf drupal-7.59.tar.gz
mv /opt/drupal-7.59 /var/www/html/drupal
cd /var/www/html/drupal
cp sites/default/default.settings.php sites/default/settings.php
chmod o+w sites/default/settings.php
chmod o+w sites/default

2. Uncomment RewriteBase /drupal in /var/www/html/drupal/.htaccess.

3. Configure Apache for Shibboleth for Drupal and clean Drupal URL's by adding to the end of /etc/httpd/conf.d/shib.conf:

<Location /drupal>
  AuthType Shibboleth
  ShibRequireSession Off
  ShibUseHeaders On
  require shibboleth
</Location>

<Directory "/var/www/html/drupal">
AllowOverride All
</Directory>

4. Make sure you have all the PHP and MariaDB related packages installed and then continue installing Drupal. newpass below should be replaced with a new password of your choosing.

yum install php-gd php-xml mariadb mariadb-server
systemctl start mariadb
mysqladmin -u root password 'newpass'

When you run the following commands, you will be prompted to authenticate using your newpass so you can create the Drupal database.

mysqladmin -u root -p create drupal
mysql -u root -p

You'll then enter your password. Inside the mysql tool, execute the following query:

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES ON drupal.* TO 'root'@'localhost' IDENTIFIED BY 'newpass';
\q

Your query should return OK, and it's fine and expected that there were 0 rows selected.  Finally, please enable php-mysql and restart httpd.

yum install php-mysql
systemctl restart httpd

5. Configure Drupal:

Go to https://my.special.name/drupal/ and start a standard install using a language of your choice(your instructors are fond of English). Your database name is drupal, username root, and password newpassPlease remember your administrator name and password. Complete the rest of the installation process.

6. Grab the Shibboleth Drupal module from http://drupalmodules.com/module/shibboleth-authentication and install it:

cd /var/www/html/drupal/sites/all/modules/
curl -o shib_auth.tar -L http://ftp.drupal.org/files/projects/shib_auth-7.x-4.0.tar.gz
tar -xvf shib_auth.tar

7. Go to https://my.special.name/drupal/ and use the menu bar to select "Modules". Select the Shibboleth check box (at the bottom) and then click Save configuration at the bottom of the page. Close out of the module configuration by clicking on the black "x" near the upper right hand corner of the modules 'overlay'.

8. Go to https://my.special.name/drupal/ and use the menu bar to select "Configuration". Don't worry about any problems Drupal thinks it's detected. On this page select the "Shibboleth settings" link. Change and save the configuration as follows:

Shibboleth login handler URL: https://my.special.name/Shibboleth.sso/Login
Shibboleth logout handler URL: https://my.special.name/Shibboleth.sso/Logout
Shibboleth login link text: Shibboleth Login
Force Https on login: Checked
Server variable for username: REMOTE_USER
Server variable for e-mail address: REMOTE_USER

*Be sure to save these changes using the button at the bottom of the page.

Click on the Advanced Settings tab and set URL to redirect to after logout to null (empty). Save the configuration again and close the tab.

9. Remove the "SAML2" attribute from the Logout element in /etc/shibboleth/shibboleth2.xml. This is necessary because the default Logout configuration on the SP supports global logout, but the Shibboleth 2.x IdP does not support single logout by default, so users get stranded on a page at the SP suggesting that logout is not complete and the browser should be closed. This is good to read about if you have some spare time.

<Logout>Local</Logout>

10. Restart httpd and shibd:

systemctl restart httpd 
systemctl restart shibd

11. Go back to Drupal's front page and logout.
12. Take a moment to realize how unintuitive this sort of interface is: a username/password dialogue appears next to a federated identity initiation link. This should be avoided whenever possible with production services. We'll fix it here once federated login works.
13. Login to Shibbolized Drupal by clicking the Shibboleth Login link in the sidebar. Depending on your SP's <SSO> configuration, you may be sent directly to the training IdP; if not, please select it from the discovery interface. Login as student1 with password password.
14. Logout again, and login as admin again.
15. Click the People link at the top of the page.  in the list of users, click on student1@example.org.  On the person page select the Edit tab.  Check the "administrator" box under Roles Click the Save button at the bottom of the screen.
16. Logout again, and login as student1@example.org using Shibboleth again.
17. Ensure you are logged in as student1@example.org. You should see the administration links at the top.
18. Go to Structure, and then Blocks. Under Sidebar First, please change User Login from Sidebar First to - None -. This will remove the local username/password dialog from the sidebar. Click the Save button at the bottom of the screen and click the X to close the configuration page.

Logout to see your handiwork: you've Shibbolized Drupal. Please read more about the module and productionalizing it using the link below.

Remember that single sign-out support requires harmonizing Drupal, SP, and IdP sessions. This can be done, but it's more than you want to bother with now.

Section 5: Advanced Topics

1. Session Initiation
  • Required sessions

When accessing our resource at /secure and /testscript, Shibboleth forced us to create a session when we first accessed. This static, forced session initiation for a complete URL space is one mode of operation for Shibboleth.

  • Lazy sessions

More commonly used, perhaps, is the Lazy Session. This allows the application to decide when session creation should be initiated by sending the user to a special URL. This is how the Drupal plugin works.

  • Tasks: Protect /testscript using lazy sessions. (can be done in /etc/httpd/conf.d/shib.conf)
  • Objective:
    • Change /testscript to no longer require a Shibboleth session, but to still require Shibboleth. Then, modify the testscript to have a link that will allow you to start a session.
  • Resources:
    • <Location> element in Apache's configuration files, such as shib.conf or httpd.conf, to permit, but not require, mod_shib to protect the test script.
      <Location /testscript>
        AuthType shibboleth
        Require shibboleth
      </Location>
      
    • Also, a link to start a session using the DS. A revised /var/www/html/testscript/test.php:
      <html>
      <head>
      <title>Hello Shib World</title>
      </head>
      <body>
      <a href="https://my.special.name/Shibboleth.sso/Login?target=https://my.special.name/testscript/test.php">
      Make Me A Session</a><br/>
      <a href="https://my.special.name/Shibboleth.sso/Login?target=https://my.special.name/testscript/test.php&entityID=https://idp.training.incommon.org/idp/shibboleth">
      Make Me A Session and Skip the DS</a><br/>
      <a href="https://my.special.name/Shibboleth.sso/Logout?return=https://my.special.name/testscript/test.php">
      End My Session</a><br/>
      <hr/>
      <?php phpinfo(); ?>
      </body>
      </html>
      

Restart Apache. Then, try accessing https://my.special.name/testscript/test.php. Note the difference in environment variables before and after authenticating.

This is the most simple interface possible for lazy session initiation. You could front these links with buttons that go directly to an IdP(and even have multiple buttons for multiple IdP's) so long as you're not operating with many IdP's.

2. Accept users from a new IdP

We only have one IdP that can release attributes to your SP. However, there's a general use IdP that you can also use at TestShib.

https://www.testshib.org/

Do not follow the TestShib configuration instructions. They are intended for novice deployers performing fresh installations. Please follow the steps below to add TestShib as another IdP for your existing SP.

  1. Register your SP with TestShib.
  2. Next, you need to load the TestShib IdP's metadata in shibboleth2.xml:

    <MetadataProvider type="XML" uri="http://www.testshib.org/metadata/testshib-providers.xml"
                      backingFilePath="testshib-two-idp-metadata.xml" reloadInterval="180000" />
  3. We'll also need to configure session initiation to go to the TestShib IdP. Modify your test script again to make this happen.

    <html>
    <head>
    <title>Hello Shib World</title>
    </head>
    <body>
    <a href="https://my.special.name/Shibboleth.sso/Login?target=https://my.special.name/testscript/test.php">
    Make Me A Session</a><br/>
    <a href="https://my.special.name/Shibboleth.sso/Login?target=https://my.special.name/testscript/test.php&entityID=https://idp.testshib.org/idp/shibboleth">
    Make Me A Session with the TestShib IdP</a><br/>
    <a href="https://my.special.name/Shibboleth.sso/Logout?return=https://my.special.name/testscript/test.php">
    End My Session</a><br/>
    <hr/>
    <?php phpinfo(); ?>
    </body>
    </html>
    
3. Direct-to-IdP Session Initiation

In many situations, you may have an application that serves a limited number of identity providers. Rather than doing full IdP discovery, it can be advantageous to send the users directly to their IdP by doing limited discovery on the application page itself. We're vivisecting test.php again:

<html>
<head>
<title>Hello Shib World</title>
</head>
<body>
<table><tr>
<td>
<p><a href="https://my.special.name/Shibboleth.sso/Login?target=https://my.special.name/testscript/test.php&entityID=https://idp.testshib.org/idp/shibboleth">
<center><img src="https://www.testshib.org/testshibtwo.jpg" /><br/><br/>
Make Me A Session with the TestShib IdP
</a></center></p>
</td><td>
<p><a href="https://my.special.name/Shibboleth.sso/Login?target=https://my.special.name/testscript/test.php&entityID=https://idp.training.incommon.org/idp/shibboleth">
<center><img src="https://sp.training.incommon.org/images/incommon-training-logo.jpg" /><br/><br/>
Make Me A Session with the InCommon Training IdP
</a></center></p>
</td></tr><tr>
<td><a href="https://my.special.name/Shibboleth.sso/Login?target=https://my.special.name/testscript/test.php">
Make Me A Session with a Different IdP</a><br/></td>
<td><a href="https://my.special.name/Shibboleth.sso/Logout?return=https://my.special.name/testscript/test.php">
End My Session</a></td>
</tr></table>
<br/><br/><br/><hr/>
<?php phpinfo(); ?>
</body>
</html>

Now imagine changing out the images for, say, school logos, and getting this in the hands of a competent web designer.

This is a highly effective discovery approach for smaller-scaled collaborations.

4. Authorization ACLs
  • Issue:
    • You may want to restrict access to certain users, based on specified values of certain attributes.
    • Attribute-based authorization can be performed by Shibboleth and defined in Apache configuration or Shibboleth configuration. It can also be delegated to the application entirely by defining no authorization rules in the environment. If you want the web environment to do it, and you're using httpd, you should use Apache configuration unless your rules are horribly complex.
  • Notes:
    • The Apache rules are generally simple require statements of the form require <AttributeNameFromAttributeMap> <MatchingValue>. There is regex support.
    • We generally recommend that authorization be enforced within the application rather than by Shibboleth. This is because the application will have the best idea why authorization failed, what to do with the user once authorization has failed, and how to make rejection most comfortable for the user.
    • The built-in require shib-session rule needs to be commented out because it will be fulfilled with any Shibboleth session.

Try putting one of these rules into the shib.conf directives protecting your test script and try different users. Enjoy the occasional 401's that result and reflect on the value of the application handling authorization failures.

# Direct comparison
Require shib-attr affiliation student@example.org student@incommon.org
ShibRequestSetting requireSession true

# Using an expression
Require shib-attr affiliation ~ ^student@(example|osu)\.edu$
ShibRequestSetting requireSession true

Section 6: Discussion Topics

1. Application Interaction with the Shibboleth SP
  • The Shibboleth SP, by design, has no API.  This is to allow application developers to offload security and identity to the Shibboleth SP and web environment.  This obviates the need for the application to understand and handle identity protocols and allows for much better security hygiene.  Engineering an application to rely on the web environment for identity data is commonly termed domestication.
  • There are two primary ways in which the SP interfaces with applications: administrative functions, and attribute access.
    • The two most important administrative functions are session initiation and session destruction.
      • This is totally configurable, but by convention, session initiation is triggered by redirecting the user to https://my.special.name/Shibboleth.sso/Login and session are destroyed by redirecting the user to https://my.special.name/Shibboleth.sso/Logout
      • These should not be confused with the resources that the SP protects, which are hosted at their natural locations, but may trigger redirects to /Shibboleth.sso as necessary to interact administratively with the SP itself.
    • Attributes and other information about the federated user are made available to the web environment through environment variables or header variables.  Environment variables are preferred because they are unspoofable by definition.  However, you can also use headers when necessary, such as HTTP forwarding, lazy applications, and IIS.
      • Examples were available in the beginning slides.
  • attribute-map.xml is where SAML attributes are assigned internal names for the SP, web environment, and application.  For example,
    <Attribute name="urn:oid:2.5.4.42" id="givenName"/>

    will map urn:oid:2.5.4.42 received on the wire to givenName internally and givenName as an environment variable.  Some permutation of HTTP_GIVENNAME or something will show up as a header if you have that option enabled, but we can't tell you precisely what it is, since web environments take artistic liberty with headers.

  • If you want to enhance the performance of the SP, particularly in httpd prefork environments, consider commenting out attribute mappings that you will not need.  Ensure that the applications are not using the headers, since the SP can't clear all the headers in the universe and will now pass them happily along from the client.
  • You may find vendors asking for seemingly nonsensical attributes like employeeID.  It's best to communicate with them to see what they really want and encourage them to use defined standards and unique names.  If your heroic efforts go begging, you can always define a mapping such as the following.

    <!-- headdesk -->
    <Attribute name="firstname" nameFormat="
    urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified" id="givenName"/>

Resources

2. Discovery

Discovery is perhaps the most challenging aspect of deployment of a large-scale federated service.  Users generally need to be presented with an intelligible and intuitive way to get back to the appropriate IdP.  There are many alternatives available today for IdP discovery interfaces and integration. You can read about some of them in the Shibboleth Wiki's IdP Discovery article.

There is a primer on how to integrate an embedded discovery service with an application. It's an excellent way to give the application freedom in implementation while making the interface itself as shared as much as possible.

An example of a great large-scale live discovery service can be found at the Shibboleth Wiki, https://wiki.shibboleth.net/.

An example of a great small-scale live discovery interface can be found at a Five Colleges collaborative site at https://moodle.smith.edu .

An example of a slick discovery interface that may have accessibility limitations can be found at EDUCAUSE's website at http://www.educause.edu/.

There's also plenty of scientific inquiry that has been conducted into discovery interfaces. If you have lots of free time, try perusing the ESPReSSO report from NISO or Google's work or the Publisher Interface Study by the University of Cardiff.

3. Logout

Logout is a fun topic in identity, and your options will be constrained by how you do session management.  "Close the Browser" was once an acceptable and functional logout mechanism, but the world has changed greatly and logout must now be handled expressly.  You may have limited ability to clear user sessions in most scenarios since the IdP also maintains user state.

The problem is exacerbated in a federated world with multiple organizations and the Web.  We will divide logout along four functional lines:

  • administrative logout
    • Occasionally, there will be a specific user whose access to systems must be terminated immediately.  This is tough to do in single sign-on systems, where session creation often cascades into further session creation and applications make arbitrary access tokens for themselves.  Cracking down on application behavior is half of the battle; the other half is having a centralized session store/session notification mechanism that is capable of clearing all extant sessions is the other.  This is rarely possible "out of the box", but many applications and services have hooks intended for these purposes.
  • logout from an application
    • Applications will generally establish their own sessions with users after an SSO transaction, and the SSO mechanism itself may persist a user session.  Clearing these sessions will terminate a user's session at an application.  Users are sometimes befuddled when they attempt to login as a different user, only to have SSO work perfectly.  User expectations are often contextual.
  • logout from an application and an SSO session
    • Everything above, except that users are occasionally surprised that they are forced to re-authenticate.  This is routinely the most palatable user-facing logout mechanism.
  • logout from all applications accessed during an SSO session and an SSO session
    • This is broadly considered impracticable across multiple domains in a web environment.  Resources are available for you if you think you'd like to try.

The IdP supports logout via a recently defined specification as part of SAML 2.0 and a simple redirect, both of which give the IdP the ability to clear a user's session through front channel communication. The user's session is cleared not only by deleting the cookie(idp_session) from the user's browser, but also by destroying the session internally.

  • You can register logout endpoints in your IdP's metadata(e.g. /idp/profile/SAML2/SLO/Redirect), or give SP's a well-known IdP that they can redirect users logging out in scenario B to (/idp/profile/Logout).
  • You can test this out by logging into a resource, then accessing https://my.special.name/idp/profile/Logout in the same browser context, or by clicking the right logout URL on the test page.

The <Logout> element gives you the option of enabling either full SAML logout, local logout, or, by default, both.

  • You can test this out by logging into a resource, then accessing https://my.special.name/Shibboleth.sso/Logout?return=https://my.special.name/insecure in the same browser context, or by clicking the right logout URL on the test page.
  • Support for logout across products varies widely.

Resources:

4. Scopes, Attributes, and Metadata Filtering
  • Issue:
    • Use this if you need to exclude certain IdP's from a metadata source that you trust from ever working with your SP
    • Useful for constraining what attributes IdPs can assert to your SP, though this is a rare use case
  • Notes:
    • Attribute filtering uses roughly the same syntax as the IdP implementation, with as much power in transmogrification.  It allows the SP to control the vocabulary (allowed values) of certain attributes (for example, eduPersonAffiliation).  It could also restrict certain attributes, or values of attributes, to specific IdPs (for example, you could restrict certain IdPs in your federation, whom you do not partner with, from asserting certain eduPersonEntitlement values that are specific to your applications)
    • Shibboleth enforces scope checks on attributes that are defined as such out of the box, specifically eduPersonPrincipalName and eduPersonScopedAffiliation.  Many other software packages don't.
      • The scopes for which an IdP has authority are typically enumerated by a third party registrar such as a federation.
      • A scope denominates domains that an IdP can express attributes on behalf of.  For example, if Internet2's IdP were permitted only to express internet2.edu scopes, then ndk@internet2.edu would be valid, ndk@osu.edu would be invalid and discarded automatically by the SP with a WARN in the logs, and ndk@dorms.mwahaha.internet2.edu would also be rejected.  One IdP may be authoritative for an arbitrary number of scopes, and this is particularly encountered with some large outsourced identity management solutions.
    • If you block metadata for an IdP from being loaded, the SP will act as if the entity (or entities) is not even present in the metadata file
      • Useful if you want IdPs (like public IdPs) which appear in federation-supplied metadata to not be able to use your services under any circumstances
    • Other filters should always be used with production-level metadata, and examples appear on the linked pages, including specific guidance from InCommon.
      • Enforcing validUntil
      • Checking signatures
      • Removing SP's from metadata to reduce the memory footprint
  • Resources:
5. Clustering and Load Balancing
  • Issue:
    • The SP can be clustered for high availability.  This is conceptually distinct from load balancing, and you can do one or the other independently depending on your use case.  Load balancing allocates sessions between servers, while clustering replicates data between servers so it generally doesn't matter which node a query arrives at.
  • Notes:
    • Most applications protected by the SP that require high availability can provide it by themselves. Frequently, because the session is persisted/checked autonomously by the application after Shibboleth helps with session creation, there is no need to configure the SP for high availability at all.
    • But if you do need to cluster SP sessions too, there are many options: ODBC, memcache, and virtualized environments being the most commonly used
      • Please see the links below, but the short answer is that it is easiest to run a single shared instance of shibd (on a private network segment) between cluster members.
    • It's best to not configure the load balancer to strip off the SSL from incoming connections.  Any performance improvement you may gain is likely not worth the pain this will cause.
    • When configuring a virtualized web environment, the web environment must be configured such that it believes it is the public-facing interface.  This is almost always done in web server configuration.
  • Resources:
6. Error Handling
  • The SP should not return a generic statement about how IdPs should handle this type of problem. The SP operator should try to put him/herself in the place of the user.
  • The SP shouldn't be required (or tempted) to instantiate a workflow process for the user to follow in order to obtain access to the site.
  • The best approach is to tell the user specifically what steps to take in order to proceed (e.g., contact the SP help desk, obtain local login credentials, contact the IdP help desk, etc.).

Please don't use the Shibboleth logo as the primary error page logo. It is recommended that SPs host a branded error page with a look-and-feel consistent with the rest of the protected application. If there is an errorURL in IdP metadata, the SP should display a prominent link to the IdP’s advertised error page (given by the value of errorURL). Otherwise the SP should display contact information for the IdP’s administrative contact(s) (also taken from metadata) and give the user enough information to send a meaningful message to the administrative contact. The SP may actually send such a message on the user’s behalf (with user permission of course).

The previous recommendation presents a fairly high bar for the SP, at least initially. It presumes that the SP can parse IdP metadata, extract the needed information (errorURL, contact information, etc.), and display it dynamically on a branded error page. To alleviate this burden, the SP can instead display a centralized error page offered by InCommon Operations as a service.

7. Logging, Auditing, Reporting, and Troubleshooting
  • Issue:
    • The SP creates 3 different primary log files which can be useful for a variety of purposes
      • /var/log/shibboleth/shibd.log (Shibboleth daemon logging - this is the main log file)
      • /var/log/apache/native.log (web server plug-in logging - mod_shib)
      • /var/log/shibboleth/transaction.log (Summary/Audit logging of sessions)
    • You can use the SP's logs to generate useful audit reports as well.  There are tools contributed by the community to do some of this analysis, so please check the contributions page, and consider giving back if you build something new and cool.
      • Configured in *.logger files in the same directory as shibboleth2.xml, based on log4cpp/log4shib, which basically has log4j format configuration
      • The defaults are generally just fine, but avoid running the SP at higher logging levels in production.  It will dramatically slow down your SP, fill up disk, and may cause other performance issues.
    • When troubleshooting, the following tact is recommended:
      • Check shibd.log for any ERROR or higher messages.  Many of these may occur at initialization time rather than message issuance or receipt.
      • Check the Shibboleth wiki (http://wiki.shibboleth.net/confluence/display/SHIB2/Home)
      • Check the mailing list archives here:
      • Post a question to the users@shibboleth.net mailing list for help, or dev@shibboleth.net for development-oriented questions.  Please include all details that you believe may be relevant, because it's easier to skim over something than ask for more information.  The degree of thought put into the answer will be proportionate to the amount of thought put into the question.
        • You'll generally receive answers very quickly, and some may be terse
      • Commercial support is available through the InCommon Industry Program and through consulting firms listed on the Shibboleth website.  Firms listed on the website are not vetted or endorsed, and we receive no compensation beyond membership if they choose to join.  The project itself does not directly support deployments at this time.
  • Notes:
    • shibd.log is the main log file to check for warnings or errors.
    • native.log is generally only useful for debugging strange web browser behavior, such as cookies being improperly set or infinite SSO loops occurring.
    • transaction.log is very parseable and can tell you things like:
      • What IdPs are using your services?  What attributes are these IdPs sending?  What are the IP addresses of your SP's users?  What times is your SP most heavily used?
  • Resources
8. Application Override
9. Service restarts

Some changes to Shibboleth configuration will require restart of specific components: httpdshibd, or both.  Other changes are dynamically reloaded.  A general rule of thumb is that the lower a configuration directive appears in shibboleth2.xml, the more likely it is to be dynamically reloaded.

shibboleth2.xml as a whole is generally dynamic, and once it's reloaded, it also rereads all the subordinate files it references.  Everything in shibboleth2.xml above <ApplicationDefaults> is only read at shibd startup or each httpd child startup.  With modern configuration, those are largely defaulted and invisible, but it consists of components such as Listeners, the SessionCache, the StorageService, etc.  Most sites will not modify these settings at all, and those that do will likely do so only during initial configuration.

Modifications directly to subordinate files, such as attribute-filter.xml, are sometimes loaded dynamically, which can be turned on and off for most of these files.  Any file referenced by shibboleth2.xml that has reloadChanges="true" is dynamic, while the rest are not automatically reloaded.  attribute-map.xml defaults to reloadChanges="false" because changing them on a system under load can inadvertently desynchronize httpd and shibd enough to cause failures and problems.

In order to reload any ISAPI-specific configuration, IIS must be restarted; simply stopping and restarting the specific site is not sufficient.

10. More cool stuff
  • The developers keep a running log of new ideas that get implemented.  Some recent additions include attribute aggregation, constrained delegation, processing hooks, new attribute decoders, metadata tag consumption, and more.  You won't likely need to use any of these features, but some of them are very helpful in particular use cases.
  • Resources:
  • No labels