Page Comparison

...

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

...

- Code Block
  $ 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
  Code Block

...

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

<Sessions> — checkAddress, handlerSSL, cookieProps
Code Block

...

1. <Sessions lifetime="28800" timeout="3600" checkAddress="true" relayState="ss:mem" handlerSSL="true" cookieProps="https">
2. <SSO> — entityID vs. discoveryProtocol
  https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceSSO
  1. If federating locally (only UC Davis affiliates will use the application)
    Code Block

...

1. 1. <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.
    Code Block

...

1. 1. <SSO discoveryProtocol="SAMLDS" discoveryURL="https://wayf.incommonfederation.org/DS/WAYF"> SAML2 SAML1 </SSO>
  2. If federating with a relatively small subset of InCommon institutions, consider the Embedded Discovery Service and its Configuration
    Code Block

...

<SSO discoveryProtocol="SAMLDS"
     discoveryURL="https://myapp-dev.ucdavis.edu/shibboleth-ds/index.html">
  SAML2 SAML1
</SSO>

<Logout> — We now support SAML SLO
Code Block

...

1. <Logout>SAML2 Local</Logout>
2. <Errors> — supportContact
  Code Block

...

1. <Errors supportContact="myappadmin@ucdavis.edu" ... />
2. <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
  Code Block

...

<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.

Code Block

language	xml

<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.

...

Code Block
# 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

...

Code Block
$ 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>
Code Block

...

$ 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.

...

Code Block
$ 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

Code Block

<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"/>

...

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

xml

Code Block
xml

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

...

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

Code Block
xml	xml	Require affiliation student@ucdavis.edu

Test Scripts

...

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

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

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

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

...

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
xml
Code Block
xml
<Handler type="Session" Location="/Session" showAttributeValues="true"/>

...

Versions Compared

Old Version 49

New Version Current

Key