UC Davis Shibboleth Service Provider (2.x) Configuration Guide

Note: Shibboleth SP 3.x is current and 2.x is no longer supported. This guide remains to be updated.

An outline of considerations for installing and configuring the Shibboleth SAML Service Provider in the UC Davis environment. Specific issues not addressed here may well be found via the References section at the bottom.

Preparation

1. Choose an entityID for the service to be protected by Shibboleth.

   • Typical entityIDs for production and development systems might be:

     • https://myapp.ucdavis.edu/shibboleth

     • https://myapp-dev.ucdavis.edu/shibboleth

   • Note: these look like URLs to guarantee global uniqueness, but technically are not.

   • Note: very old entityIDs may be URNs e.g. urn:mace:incommon:ucdavis.edu

2. Think about any restrictions on identifiers sent by Identity Providers (IdPs) with respect to privacy in your application (i.e. opaque identifiers vs. not).

3. Think about the types of information (attributes) that might be useful for your application, e.g. name, email address.

Install

• Accept defaults for install location, but fill in the service (or host) name if prompted.

  • Linux — https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRPMInstall
    E.g. RHEL 6 x86_64

    $ cd /etc/yum.repos.d $ sudo curl -O http://download.opensuse.org/repositories/security://shibboleth/RHEL_6/security:shibboleth.repo $ sudo yum install shibboleth.x86_64

    
    
    

  • Note: Do not install both .i686 and .x86_64 versions (choose one).

  • Note: Platforms for which binary RPMs are available are listed in the NativeSPLinuxRPMInstall wiki page.

  • Note: Do not install binary RPMs that are not for your platform. Build from SRPM or build from source.

• Windows installation instructions here https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPWindowsInstall

Configuration - Sandbox

• If this is for a sandbox system, consider setting up against a public SAML testing service (e.g. https://samltest.id) to get some practice with the basics.

  • To move on to configuring a development and/or production system, restore the distributed XML configuration files.

Configuration - Development and Production

• /etc/shibboleth/shibboleth2.xml (ref. InCommon Technical Guide)

  1. <ApplicationDefaults> — entityID

     <ApplicationDefaults entityID="https://myapp-dev.ucdavis.edu/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">

     
     
     

  2. <Sessions> — checkAddress, handlerSSL, cookieProps

     <Sessions lifetime="28800" timeout="3600" checkAddress="true" relayState="ss:mem" handlerSSL="true" cookieProps="https">

     
     
     

  3. <SSO> — entityID vs. discoveryProtocol
     https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceSSO

     1. If federating locally (only UC Davis affiliates will use the application)

        
        
        

     2. If federating with other (InCommon federation) institutions, as well as UC Davis affiliates
        Note: your SP will not work until it is registered with the InCommon federation.

        
        
        

     3. If federating with a relatively small subset of InCommon institutions, consider the Embedded Discovery Service and its Configuration

        
        
        

  4. <Logout> — We now support SAML SLO

     
     
     

  5. <Errors> — supportContact

     
     
     

  6. <MetadataProvider>
     
     The example here allows affiliates from four different institutions to authenticate to the application. If federating locally (UC Davis affiliates only) use <Whitelist> and <Include> only urn:mace:incommon:ucdavis.edu
     
     This configuration example employs the InCommon/eduGAIN IdP-only metadata aggregate. Start up time and memory consumption is improved over use of the full IdP+SP aggregate, cf. https://spaces.internet2.edu/display/InCFederation/IdP-only+Aggregate
     
     Validating the InCommon metadata signing certificate is a critical security step. See "Bootstrapping Trust" on https://spaces.internet2.edu/display/InCFederation/Metadata+Signing+Certificate and certificate signatures here https://ops.incommon.org/inc_md_cert.html
     
     The InCommon metadata signing certificate may be obtained from http://md.incommon.org/certs/inc-md-cert.pem 

     
     However, even the IdP-only metadata aggregate contains nearly 2300 entries (as of 9 Jan 2017) and is over 17 MB in size. If federating with a small number of IdPs and/or your SP is memory-constrained, consider using the SAML Metadata Query (MDQ) Protocol. This protocol dynamically fetches IdP metadata only when needed.
     
     InCommon has an MDQ service in beta that presents production metadata. A production MDQ service is about a year away (as of 9 Jan 2017) .
     
     Note that using a local Embedded Discovery Service with MDQ presents a bootstrapping issue. The Shibboleth consortium is working with InCommon to resolve it.
     
     Example configuration for MDQ. As before, validating the metadata signing certificate is critical.

     
     
     

Test Initial Configuration and Start

https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPInitialTesting

1. Check the configuration
   Note: libcurl on RedHat 6 and 7 Linux variants is linked against NSS instead of OpenSSL libraries. The Shibboleth SP requires some OpenSSL features, so for these platforms will additionally be installed with a version of libcurl linked against OpenSSL. For these, override LD_LIBRARY_PATH on the command line to test the configuration.

   
   
   

2. Start shibd and httpd, e.g. RedHat Linux

   
   
   

3. Status — check from localhost
   Note: the default /Status handler has an access control directive restricting connections to the local host (check with a web browser on the local host or use a command line utility).
   Look for <OK/> in <SessionCache> and <Status>

   
   
   

Metadata

• Metadata contains information about the protocols an SP or IdP supports, communication end point URLs, supported data types, and signing/encryption keys.

• Metadata sharing is required for SPs and IdPs to communicate with one another and to establish trust. Sharing metadata might be as simple as mutual exchange of XML files or, more commonly, registering instances with a trusted federation and subscribing to its metadata feed.

• To register your application with local or InCommon federations, first fetch a copy of your metadata. This can be done from the command line, or with your browser. E.g.

  Send the resulting file to shibadmin@ucdavis.edu. The choice of which federation to join depends whether your application is restricted to UC Davis-only affiliates, or it includes access by affiliates from other institutions.

Attributes

Choose which attributes you need to support your application and ensure they're enabled in your configuration, cf. references above. Some common ones are

/etc/shibboleth/attribute-map.xml

Note: When differing definitions exist, both SAML2 OID and SAML1 URN definitions need to be uncommented/defined for each attribute.

Configure /etc/shibboleth/attribute-policy.xml as necessary to accept attributes you wish to use.

Logging

To assist in diagnosing errors, if needed, set to DEBUG cf. https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLogging

Example Apache httpd configuration directive

https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPhtaccess

Note: in some deployments you may see ShibRequireSession On instead of the requireSession directive. The former is from Shibboleth 1.x and is backward compatible.

Access control is usually done in the application itself, but may be done with an Apache httpd Require directive e.g.

Test Scripts

/var/www/html/shib/index.shtml

/var/www/html/shib/t.php

Session Initialization

Visit a protected location.
Note: SP metadata must be registered with the tested IdP or with a federation before these will work

• https://myapp-dev.ucdavis.edu/shib/index.shtml

• https://myapp-dev.ucdavis.edu/shib/t.php

• https://myapp-dev.ucdavis.edu/Shibboleth.sso/Login?target=https://myapp-dev.ucdavis.edu/shib/t.php&entityID=urn:mace:incommon:ucdavis.edu

• https://myapp-dev.ucdavis.edu/Shibboleth.sso/Login?target=https://myapp-dev.ucdavis.edu/shib/t.php

View your session

• https://myapp-dev.ucdavis.edu/Shibboleth.sso/Session

• To view with attribute values, modify the Session Handler in shibboleth2.xml

  
  
  

InCommon Metadata Registration

Incommon metadata registration calls for a number of elements in addition to standard metadata. Please review the following and include with your registration request.

User Interface Elements in SP Metadata

Requested Attributes

Troubleshooting

https://wiki.shibboleth.net/confluence/display/SHIB2/Troubleshooting

References 

http://shibboleth.internet2.edu/
http://shibboleth.net
https://wiki.shibboleth.net/confluence/display/SHIB2/Installation
https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfigurationElements
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPEnableApplication
https://spaces.internet2.edu/display/InCCollaborate/X.509+Certificates+in+Metadata
https://spaces.internet2.edu/display/InCCollaborate/Technical+Guide
http://www.incommon.org/federation/attributes.html
http://www.incommon.org/federation/attributesummary.html
http://middleware.ucdavis.edu/ldap_attribute.php
http://middleware.internet2.edu/dir/docs/internet2-mace-dir-saml-attributes-200804.pdf