Shibboleth Installation Notes

NOTE: the original content of this page, containing notes from a meeting between Jasper Tredgold and Graham Klyne at ILRT Bristol to learn about Jasper's work to use Shibboleth with portals, has been moved to SakaiVre/ShibbolethInstallNotes-20060322. This page now contains actual installation notes for a demonstration/test environment, using WebAuth [7] to provide primary authentication and controlling access to pages in a Sakai portal.

Contents:

Contents

  1. Prerequisites
  2. Install Shibboleth Identity Provider
    1. More prerequisites
    2. Generate required PKI values
    3. Install the Shibboleth IdP
    4. Configure the IdP
      1. IdP and attribute results
    5. Configure an LDAP attribute authority (AA)
    6. Install the Shibboleth Service Provider module
    7. Configure the Service Provider module
      1. Possible problems
  3. Passing Shibboleth attributes to applications
  4. Links
    1. Shibboleth and SPIE project notes
    2. Other intallation notes

1. Prerequisites

See also SakaiVre/MachineStatus, which has information about the host platform we are using, and in particular has a list of key services used or added, locations of log files, etc. There are some further notes about transferrig the Shibboleth service provider (SP) installtion to a Debian-based system at DebianNotes.

2. Install Shibboleth Identity Provider

The basic plan is set out in https://authdev.it.ohio-state.edu/twiki/bin/view/Shibboleth/InQueueIdPInstall. See also SakaiVre/ShibbolethInstallNotes-20060322.

2.1. More prerequisites

Using Tomcat 5.5 with Java 1.5, Apache 2 and mod_jk connector.

2.2. Generate required PKI values

See https://authdev.it.ohio-state.edu/twiki/bin/view/Shibboleth/InQueueIdPInstall.

The IdP details have also been regsitered with inQueue for testing purposes; this is the metadata returned:

1.3 Metadata: 

<EntityDescriptor entityID="urn:mace:inqueue:oucs.ox.ac.uk"> 
   <IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol urn:mace:shibboleth:1.0">
      <Extensions>
         <shib:Scope xmlns:shib="urn:mace:shibboleth:metadata:1.0">oucs.ox.ac.uk</shib:Scope>
      </Extensions>
      <KeyDescriptor use="signing">
         <ds:KeyInfo>
            <ds:KeyName>sakai-vre-demo.oucs.ox.ac.uk</ds:KeyName>
         </ds:KeyInfo>
      </KeyDescriptor>
      <ArtifactResolutionService
        Binding="urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding"
        Location="https://sakai-vre-demo.oucs.ox.ac.uk/shibboleth-idp/Artifact"
        index="1"/>
      <NameIDFormat>urn:mace:shibboleth:1.0:nameIdentifier</NameIDFormat>
      <SingleSignOnService
        Binding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"
        Location="https://sakai-vre-demo.oucs.ox.ac.uk/shibboleth-idp/SSO"/>
   </IDPSSODescriptor>
   <AttributeAuthorityDescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol">
      <Extensions>
         <shib:Scope xmlns:shib="urn:mace:shibboleth:metadata:1.0">oucs.ox.ac.uk</shib:Scope>
      </Extensions>
      <KeyDescriptor use="signing">
         <ds:KeyInfo>
            <ds:KeyName>sakai-vre-demo.oucs.ox.ac.uk</ds:KeyName>
         </ds:KeyInfo>
      </KeyDescriptor>
      <AttributeService
        Binding="urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding"
        Location="https://sakai-vre-demo.oucs.ox.ac.uk:8443/shibboleth-idp/AA"/>
      <NameIDFormat>urn:mace:shibboleth:1.0:nameIdentifier</NameIDFormat>
   </AttributeAuthorityDescriptor>
   <Organization>
      <OrganizationName xml:lang="en">Oxford University (Sakai VRE demo)</OrganizationName>
      <OrganizationDisplayName xml:lang="en">Oxford University (Sakai VRE demo)</OrganizationDisplayName>
      <OrganizationURL xml:lang="en">http://www.oucs.ox.ac.uk/</OrganizationURL>
   </Organization>
   <ContactPerson contactType="technical">
      <SurName>Graham Klyne</SurName>
      <EmailAddress>graham.klyne@oucs.ox.ac.uk</EmailAddress>
   </ContactPerson>
   <ContactPerson contactType="administrative">
      <SurName>Graham Klyne</SurName>
      <EmailAddress>graham.klyne@oucs.ox.ac.uk</EmailAddress>
   </ContactPerson>
</EntityDescriptor>

1.2 Metadata: 

<OriginSite xmlns="urn:mace:shibboleth:1.0"  Name="urn:mace:inqueue:oucs.ox.ac.uk"> 
   <Alias>Oxford University (Sakai VRE demo)</Alias>
   <Contact Email="graham.klyne@oucs.ox.ac.uk" Name="Graham Klyne" Type="technical"/>
   <Contact Email="graham.klyne@oucs.ox.ac.uk" Name="Graham Klyne" Type="administrative"/>
   <HandleService
     Location="https://sakai-vre-demo.oucs.ox.ac.uk/shibboleth-idp/SSO"
     Name="sakai-vre-demo.oucs.ox.ac.uk"/>
   <AttributeAuthority
     Location="https://sakai-vre-demo.oucs.ox.ac.uk/shibboleth-idp/AA"
     Name="sakai-vre-demo.oucs.ox.ac.uk"/>
   <Domain regexp="false">oucs.ox.ac.uk</Domain>
</OriginSite>
Intended use of Shibboleth:
Test and demonstration deployment of a Shibboleth federation for a multi-site Sakai VRE system

2.3. Install the Shibboleth IdP

See https://authdev.it.ohio-state.edu/twiki/bin/view/Shibboleth/InQueueIdPInstall.

2.4. Configure the IdP

Note: errors in the configuration can result in obscure failures, with reports like "IdP servlet not available". In order to diagnose these problems, it will be necessary to activate appropriate logging through Tomcat and cataline: see http://tomcat.apache.org/tomcat-5.5-doc/logging.html and TomcatNotes#EnablingServletLogging for more details.

Other points to check if there are problems:

2.4.1. IdP and attribute results

Validate the IdP by browsing to https://wayf.internet2.edu/InQueue/sample.jsp, which, after performing appropriate authentication steps, will give results something like the following (this result was generated using the default attribute resolver logic with resolverConfig="resolver.xml", not the LDAP attribute resolver):

If the attribute assertion is blank, but the response otherwise indicates that an authenticated user has been established, then there is probably a problem with the attribute resolver setup. In this case, here are a few things to look for:

2.5. Configure an LDAP attribute authority (AA)

The attribute authority configuration file is named by the resolverConfig attribute of the <IdPConfig> element in file IdP.xml. A skeleton file resolver.ldap.xml is provided as a starting point for configuring an LDAP attribute provider. We are using an LDAP server at ldap.ox.ac.uk.

Appliy the following changes to the skeleton file resolver.ldap.xml to configure attribute resolution via LDAP:

  1. Define a JNDI connector, identified in our case as "directoryOUCS", for the LDAP server: 
    • <JNDIDirectoryDataConnector id="directoryOUCS"> 
    <Search filter="oucsUsername=%PRINCIPAL%">
        <Controls searchScope="SUBTREE_SCOPE" returningObjects="false" />
    </Search>
    <Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory" />
    <Property name="java.naming.provider.url" value="ldap://ldap.ox.ac.uk:389/ou=people,dc=ox,dc=ac,dc=uk" />
</JNDIDirectoryDataConnector>
      This configuration assumes that all attributes to be returned relate to LDAP subjects [[[term?]]] having distinguished names with leading components "ou=people,dc=ox,dc=ac,dc=uk". [[[Check the detail here; see JNDI for details.]]]

      Note that LDAP may be used to store binary Java objects, but this introduces a considerable degree of additional configuration complexity. In the above example, the attribute returningObjects="false" avoids this complexity.

  2. For each attribute to be returned from LDAP, edit or create an entry of the form: 
    • <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:oucsStatus"> 
    <DataConnectorDependency requires="directoryOUCS"/>
</SimpleAttributeDefinition>
    • "id=..." indicates the URI used by Shibboleth to identify this value, and the "requires=" attribute indicates that the directoryOUCS connector defined above is used to obtain the value. [[[What about the LDAP attribute name?]]]
  3. Some attributes (or is it just eduP:ersonAffiliation?) are provided by the Shibboleth default attribute provider. For these, include configuration sections like this: 
    • <!-- To use these attributes, you should change the smartScope value to match your site's domain name. --> 
<SimpleAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" smartScope="oucs.ox.ac.uk">
    <AttributeDependency requires="urn:mace:dir:attribute-def:eduPersonAffiliation"/>
</SimpleAttributeDefinition>

  4. The following is used by service providers that need to save additional information (e.g. personalization) on a per-user basis, without actually knowing who the user actually is. More explanation at http://sdss.ac.uk/wiki/wiki.pl?AttributeUsage: 

    • <PersistentIDAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonTargetedID" scope="oucs.ox.ac.uk" sourceName="cn"> 
    <DataConnectorDependency requires="directory"/>
    <Salt keyStorePath="file:/opt/shibboleth-idp/etc/persistent.jks"
          keyStoreKeyAlias="handleKey"
          keyStorePassword="shibhs"
          keyStoreKeyPassword="shibhs"/>
</PersistentIDAttributeDefinition>

Also, an attribute release policy needs to be established, referenced by <ReleasePolicyEngine> in idp.xml. In a default installation, the policy is established by file arps/arp.site.xml; e.g.:

2.6. Install the Shibboleth Service Provider module

There are two versions of the service provider module: one is implemented in C/C++ as an Apache server module and the other as a Java module (typically used as part of a servlet engine filter). The Java version for Shibboleth 1.3 is no longer being developed, and is not fully up to date, so we are using the C/C++ version. New Java and C/C++ service provider modules are being developed for Shibboleth 2.

(There are some further notes about transferrig the Shibboleth service provider (SP) installtion to a Debian-based system at DebianNotes.)

Our first attempt to install the service provider module from binary RPMs failked. The procedure followed for this was:

  1. Down RPMs from Shibboleth download site http://shibboleth.internet2.edu/downloads/RPMS/i386/RHE/4.2/, all RPM files in that directory.

  2. Following the instructions at page https://authdev.it.ohio-state.edu/twiki/bin/view/GridShib/SPOnRedHatFedoraCore4.

  3. The sanity check passed OK, but the first install (of log4cpp) failed with the following error: 
    • [root@sakai-vre-demo RPMS]# rpm -ihv log4cpp*
error: Failed dependencies:
        libstdc++.so.6(CXXABI_1.3.1) is needed by log4cpp-0.3.5rc1-1.i386
        libstdc++.so.6(GLIBCXX_3.4.4) is needed by log4cpp-0.3.5rc1-1.i386

At this point, we have decided to go for Shibboleth instllation from source, rather than to try and tweak the host system to resolve the dependencies.

Installing Shibboleth SP from source (instructions at https://authdev.it.ohio-state.edu/twiki/bin/view/Shibboleth/SPBuildRPMs):

  1. First, ensure that the rpmbuild software is installed (i.e. that command rpmbuild is available). If necessary, use: 

    • yum install rpm-build

  2. Check that package doxygen is installed. Use: 

    • yum install doxygen

  3. Download the various source RPMs from http://shibboleth.internet2.edu/downloads/SRPMS/, saving them to /usr/src/redhat/SRPMS/: 

    • cd /usr/src/redhat/SRPMS/
wget -r -l1 --nodirectories -A.rpm http://shibboleth.internet2.edu/downloads/SRPMS/

    • Run rpm -q on each of the downloaded packages to confirm that the checksums are all correct. (Signatures may be not confirmed, as we haven't obtained and configured the corresponding public key.)

  4. Build each of the packages with 
    • for file in *.rpm; do rpmbuild --rebuild $file; done
  5. Install the packages 
    yum install /usr/src/redhat/RPMS/*

Note that this assumes that you have no other packages in this staging area.

These instructoins are adapted from those at https://authdev.it.ohio-state.edu/twiki/bin/view/Shibboleth/SPBuildRPMs. Note that some of the minor version numbers of packages obtained from the download diretory bay be different from those in the instructions. When performing the step "Building and installaing OpenSAML", follow the instructions for the "elegant route", noting that the required source file will have been downloaded by the wget command given above, there being a copy of cxxtest in the Shibboleth SRPMS directory.

At the end of this process, the Shibboleth Service Provider module is installed. A new file shib.conf is created in the Apache HTTPD configuration directory (/etc/httpd/conf.d/), a new directory /etc/shibboleth/ is created containing several files including shibboleth.xml, which is referenced by the new shib.conf file. Also installed are some XML schema and transform files in directory /usr/share/xml/shibboleth/.

2.7. Configure the Service Provider module

We are using two configuration files in /etc/httpd/conf.d/:

Configuring the Shiboleth SP is a bit of a maze, and the installation documentation isn't too helpful ("Modify shibboleth.xml: Mods too numerous to mention..." - https://authdev.it.ohio-state.edu/twiki/bin/view/GridShib/SPOnRedHatFedoraCore4). The most helpful instructions were found at: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/sp/install-sp-1.3-debian.html.

  1. Create some test files in the web server area under /var/www/html/shibtest/, and edit file /etc/httpd/conf.d/shib-sp.conf to contain: 

    • <Location /shibtest> 
  AuthType shibboleth
  ShibRequireSession On
  require valid-user
</Location>

  2. The next change needed seems to be to configure the IdP address in /etc/shibboleth/shibboleth.xml: 

    • <!-- This example directs users to the InQueue federation's WAYF service. --> 
<SessionInitiator isDefault="true" id="IQ" Location="/WAYF/InQueue"
                  Binding="urn:mace:shibboleth:sp:1.3:SessionInit"
                  wayfURL="https://wayf.internet2.edu/InQueue/WAYF"
                  wayfBinding="urn:mace:shibboleth:1.0:profiles:AuthnRequest"/>

  3. Start the shibd daemon: 

    • service shibd start

      See also the notes in https://authdev.it.ohio-state.edu/twiki/bin/view/Shibboleth/SPLinuxInstall, setion 3, item 2. Now, the test access returns a different error: 

      Unauthorized Identity Provider  
The identity provider supplying your login credentials is not authorized for use with this service.
You should inquire with your identity provider as to whether this service is intended to be enabled for your use.
Please include the following error message in any email:
Metadata lookup failure at (https://sakai-vre-demo.oucs.ox.ac.uk/Shibboleth.sso/SAML/POST)
Session Creation Error
  4. Configure the identity provider:

    • In <Local>/<RequestMapProvider>: 

      <Host name="sakai-vre-demo.oucs.ox.ac.uk"> 
    <Path name="secure" authType="shibboleth" requireSession="true"/>
</Host>

      In <Local>/<implementation>/<ISAPI>: 

      <Site id="1" name="sakai-vre-demo.oucs.ox.ac.uk"> 
    <!-- <Alias>spalias.example.org</Alias> -->
</Site>

      In <Applications>: 

      <Applications id="default" providerId="https://https://sakai-vre-demo.oucs.oc.ac.uk/shibboleth/shibboleth" 
    homeURL="https://sp.example.org/index.html"
    xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">

  5. Copy InQueue metadata to /etc/shibboleth, and configure federation metadata. There is an initial "starter" InQueue metadata file, and a full metadata file that is made available after the IdP has been accepted by the InQueue federation. Copy the full InQueue metadata file. The configuration to use this looks something like this: 

    • <MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata" 
                  uri="/etc/shibboleth/InQueue-metadata.xml"/>
  6. Copy the IdP key and certificate files to /etc/Shibboleth, and configure the identity provider credentials: 
    • <CredentialsProvider type="edu.internet2.middleware.shibboleth.common.Credentials"> 
    <Credentials xmlns="urn:mace:shibboleth:credentials:1.0">
        <FileResolver Id="inqueue_cred">
            <Key>
                <Path>file:/etc/shibboleth/oucs-sakai-vre-demo.key</Path>
            </Key>
            <Certificate>
                <Path>file:/etc/shibboleth/oucs-sakai-vre-demo.crt</Path>
            </Certificate>
        </FileResolver>
     :

At this stage, we can access our Shibboleth-protected static web page.

2.7.1. Possible problems

If the Shibboleth protected page cannot be accessed, instead showing this error message after the initial authentication has been performed:

3. Passing Shibboleth attributes to applications

Accessing user information above and beyound the mere fact of authentication and authorisation is a significant goal. In our case attributes reside in an LDAP server (which is ultimately updated from core business systems which are beyond the scope of this project) and a made accessible to the Shibboleth IdP which then releases them to applications as they request them. There are a number of configuration steps involved. We're using the Tomcat servlets-examples/servlet/RequestHeaderExample test, which returns a webpage echoing the http headers it recieves.

  1. Configuring the IdP to extract attributes from the LDAP resolver.ldap.xml contains defines connections to LDAP databases and mappings from entries (usually Person entries) to Shibboleth attributes. Out of the box this handles default LDAP attributes very well. At Oxford we don't use the default LDAP schema, so we needed to add some extra details; e.g. to release an LDAP attribute oucsStatus: 

    • <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:oucsStatus"> 
    <DataConnectorDependency requires="directoryOUCS"/>
</SimpleAttributeDefinition>

    • where directoryOUCS is a reference to the LDAP connection.

  2. Configuring an IdP Attribute Release Policy (ARP) arps/arp.site.xml contains a (minimal) list of attributes to be release. We added some of the standard attributes (using the names harvested from resolver.ldap.xml): 

    • <Attribute name="urn:mace:dir:attribute-def:initials"> 
    <AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:oucsStatus">
    <AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:cn">
    <AnyValue release="permit"/>
</Attribute>

  3. Configuring the SP Attrubute Acceptance Policy (AAP) AAP.xml in the SP contains a complex logic of which attributes to accept and how to map them to local attributes. Out of the box a full set of standard attributes are present, but need to be uncommented. The selected attrubutes are presented to the application as HTTP header fields. The result appears as: http://static.flickr.com/77/168300211_d9e2fced6d_o.png

[[[Can we make the image smaller, and a local attachment?]]]

[[[What about local attributes like oucsStatus?]]]

4. Links

  1. http://tomcat.apache.org/tomcat-5.5-doc/config/ - Tomcat configuration

  2. http://tomcat.apache.org/tomcat-5.5-doc/config/ajp.html - Tomcat AJP connector configuration

  3. http://www.dsg.port.ac.uk/events/workshops/VRE05/talks/Jasper%20Tredgold.ppt - Personalisation, Shibboleth and WSRP in the SPIE Project, Jasper Tredgold's presentation to the Sakai VRE demonstrator workshop help in Portsmouth, January 2006.

  4. http://spie.oucs.ox.ac.uk/ - Shibboleth-aware Portals and Information Environments (SPIE) project website

  5. https://authdev.it.ohio-state.edu/twiki/bin/view/Shibboleth/InQueueIdPInstall - Instructions for Shibboleth IdP installation

  6. SakaiVre/ShibbolethInstallNotes-20060322 - Notes about Shibboleth deployment from meeting with Jasper Tredgold

  7. http://webauth.stanford.edu/ - WebAuth Apache module for Kerberos-based authentication. Download and installation instructions: http://webauth.stanford.edu/obtain.html.

4.1. Shibboleth and SPIE project notes

4.2. Other intallation notes

ShibbolethInstallNotes (last edited 2006-09-25 14:36:16 by GrahamKlyne)

Creative Commons License
The content of this wiki is licensed under the Creative Commons Attribution-ShareAlike 2.0 England & Wales Licence.
OSS Watch is funded by the Joint Information Systems Committee (JISC) and is situated within the Research Technologies Service (RTS) of the University of Oxford.