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

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
Think about any restrictions on identifiers sent by Identity Providers (IdPs) with respect to privacy in your application (i.e. opaque identifiers vs. not).
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)

<ApplicationDefaults> — entityID

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

<Sessions> — checkAddress, handlerSSL, cookieProps

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

<SSO> — entityID vs. discoveryProtocol
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceSSO
1. If federating locally (only UC Davis affiliates will use the application)
  <SSO entityID="urn:mace:incommon:ucdavis.edu"> SAML2 SAML1 </SSO>
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.
  <SSO discoveryProtocol="SAMLDS" discoveryURL="https://wayf.incommonfederation.org/DS/WAYF"> SAML2 SAML1 </SSO>
3. If federating with a relatively small subset of InCommon institutions, consider the Embedded Discovery Service and its Configuration
  <SSO discoveryProtocol="SAMLDS" discoveryURL="https://myapp-dev.ucdavis.edu/shibboleth-ds/index.html"> SAML2 SAML1 </SSO>
<Logout> — We now support SAML SLO
<Logout>SAML2 Local</Logout>

<Errors> — supportContact

<Errors supportContact="myappadmin@ucdavis.edu" ... />

<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

<MetadataProvider type="Chaining">
    <MetadataProvider type="XML" uri="http://md.incommon.org/InCommon/InCommon-metadata-idp-only.xml"
         backingFilePath="InCommon-metadata-idp-only.xml" reloadInterval="7200" maxRefreshDelay="3600">
      <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
      <MetadataFilter type="Signature" certificate="inc-md-cert.pem" verifyBackup="false"/>
      <!-- Use either EntityRoleWhiteList (all InCommon/eduGAIN IdPs) or Whitelist (specific IdPs) -->
      <!--
      <MetadataFilter type="EntityRoleWhiteList">
        <RetainedRole>md:IDPSSODescriptor</RetainedRole>
      </MetadataFilter>
      -->
      <MetadataFilter type="Whitelist">
        <Include>urn:mace:incommon:ucdavis.edu</Include>
        <Include>urn:mace:incommon:ucsd.edu</Include>
        <Include>https://identity.andrew.cmu.edu/idp/shibboleth</Include>
        <Include>https://auth.yale.edu/idp/shibboleth</Include>
      </MetadataFilter>
    </MetadataProvider>
</MetadataProvider>

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.

<MetadataProvider type="Dynamic" ignoreTransport="true">
  <Subst>http://mdq-beta.incommon.org/global/entities/$entityID</Subst>
  <MetadataFilter type="RequireValidUntil" maxValidityInterval="1209600"/>
  <MetadataFilter type="Signature" certificate="mdq-beta-cert.pem"/>
  <MetadataFilter type="Whitelist">
  <Include>urn:mace:incommon:ucdavis.edu</Include>
  <Include>urn:mace:incommon:ucsd.edu</Include>
  </MetadataFilter>
</MetadataProvider>

Test Initial Configuration and Start

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

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.
# LD_LIBRARY_PATH=/opt/shibboleth/lib64 /usr/sbin/shibd -t [possible output] overall configuration is loadable, check console for non-fatal problems #

Start shibd and httpd, e.g. RedHat Linux

$ sudo /sbin/service shibd start
$ sudo /sbin/service httpd start

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>

$ curl -k https://localhost/Shibboleth.sso/Status

<?xml version="1.0"?>
<StatusHandler time="2011-05-09T15:07:10Z">
  <Version Xerces-C="3.1.1" XML-Tooling-C="1.4.1" XML-Security-C="1.6.0" OpenSAML-C="2.4.1" Shibboleth="2.4.2"/>
  <NonWindows sysname="Linux" nodename="myapp-dev.ucdavis.edu" release="2.6.18-238.9.1.el5" version="#1 SMP Fri Mar 18 12:42:39 EDT 2011" machine="x86_64"/>
  <SessionCache>
    <OK/>
  </SessionCache>
  <Application id="default" entityID="https://myapp-dev.ucdavis.edu/shibboleth"/>
  <Handlers>
    <Handler type="ArtifactResolutionService" Location="/Artifact/SOAP" Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"/>
    <Handler type="AssertionConsumerService" Location="/SAML2/POST" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
    <Handler type="AssertionConsumerService" Location="/SAML2/POST-SimpleSign" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign"/>
    <Handler type="AssertionConsumerService" Location="/SAML2/Artifact" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"/>
    <Handler type="AssertionConsumerService" Location="/SAML2/ECP" Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS"/>
    <Handler type="AssertionConsumerService" Location="/SAML/POST" Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post"/>
    <Handler type="AssertionConsumerService" Location="/SAML/Artifact" Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01"/>
    <Handler type="SessionInitiator" Location="/Login"/>
    <Handler type="SingleLogoutService" Location="/SLO/SOAP" Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"/>
    <Handler type="SingleLogoutService" Location="/SLO/Redirect" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
    <Handler type="SingleLogoutService" Location="/SLO/POST" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
    <Handler type="SingleLogoutService" Location="/SLO/Artifact" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"/>
    <Handler type="LogoutInitiator" Location="/Logout"/>
    <Handler type="MetadataGenerator" Location="/Metadata"/>
    <Handler type="Status" Location="/Status"/>
    <Handler type="Session" Location="/Session"/>
    <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
  </Handlers>
  <md:KeyDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" use="signing">
    <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:KeyName>myapp-dev.ucdavis.edu</ds:KeyName>
      <ds:X509Data>
        <ds:X509SubjectName>CN=myapp-dev.ucdavis.edu</ds:X509SubjectName>
        <ds:X509Certificate>MIIDADCCAeigAwIBAgIJAPF32CZrN4DZMA0GCSqGSIb3DQEBBQUAMB4xHDAaBgNV
BAMTE3BzbC0xMDMudWNkYXZpcy5lZHUwHhcNMDgxMDE2MTEyMTUzWhcNMTgxMDE0
...
FZu/SaAnDBZY4FN1xrPxLrWbrI9JOecV+b74izOpE9Di7l4jSRdEl9m//4fiReQh
VZDzDg==
</ds:X509Certificate>
      </ds:X509Data>
    </ds:KeyInfo>
  </md:KeyDescriptor>
  </md:KeyDescriptor>
  <md:KeyDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" use="encryption">
    <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:KeyName>myapp-dev.ucdavis.edu</ds:KeyName>
      <ds:X509Data>
        <ds:X509SubjectName>CN=myapp-dev.ucdavis.edu</ds:X509SubjectName>
        <ds:X509Certificate>MIIDADCCAeigAwIBAgIJAPF32CZrN4DZMA0GCSqGSIb3DQEBBQUAMB4xHDAaBgNV
BAMTE3BzbC0xMDMudWNkYXZpcy5lZHUwHhcNMDgxMDE2MTEyMTUzWhcNMTgxMDE0
...
FZu/SaAnDBZY4FN1xrPxLrWbrI9JOecV+b74izOpE9Di7l4jSRdEl9m//4fiReQh
VZDzDg==
</ds:X509Certificate>
      </ds:X509Data>
    </ds:KeyInfo>
  </md:KeyDescriptor>
  <Status>
    <OK/>
  </Status>
</StatusHandler>

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.
$ curl -k -o mymetadata.xml https://myapp-dev.ucdavis.edu/Shibboleth.sso/Metadata
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

<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>

<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" id="affiliation">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" id="affiliation">
    <AttributeDecoder xsi:type="ScopedAttributeDecoder" caseSensitive="false"/>
</Attribute>

<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="mail"/>
<Attribute name="urn:mace:dir:attribute-def:mail" id="mail"/>

<Attribute name="urn:oid:2.16.840.1.113730.3.1.241" id="displayName"/>
<Attribute name="urn:mace:dir:attribute-def:displayName" id="displayName"/>

<Attribute name="urn:oid:2.5.4.4" id="sn"/>
<Attribute name="urn:mace:dir:attribute-def:sn" id="sn"/>

<Attribute name="urn:oid:2.5.4.42" id="givenName"/>
<Attribute name="urn:mace:dir:attribute-def:givenName" id="givenName"/>

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

<Location /shib>
  DirectoryIndex index.shtml index.html
  AddHandler server-parsed .shtml
  Options +IncludesNoExec
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  require valid-user
</Location>

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.

Require affiliation student@ucdavis.edu

Test Scripts

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

<html>
<head></head>
<body>
<p>Hi, I'm protected by Shibboleth.</p>
<p>REMOTE_USER =
<!--#echo var="REMOTE_USER"-->
</p>
</body>

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

<html>
<head></head>
<body>
<pre style="font-size:10pt">
<?php print_r($_SERVER) ?>
</pre>
</body>
</html>

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

<Handler type="Session" Location="/Session" showAttributeValues="true"/>

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