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.


1. Prerequisites

<Connector port="8009"


</Location> }}}

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 See also SakaiVre/ShibbolethInstallNotes-20060322.

2.1. More prerequisites

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

</IfModule> # JkWorkersFile "/opt/apache-tomcat/apache-tomcat-5.5.16/conf/jk/" # JkLogFile "/opt/apache-tomcat/apache-tomcat-5.5.16/logs/mod_jk.log" JkWorkersFile "/etc/httpd/conf.d/" JkLogFile "/var/log/httpd/mod_jk.log" # JkLogLevel emerg JkLogLevel debug JkMount /shibboleth-idp/* ajp13w JkMount /jsp-examples/* ajp13w }}}

# worker.list=wlb,jkstatus,ajp13w # # Defining a worker named ajp13w and of type ajp13 # Note that the name and the type do not have to match. # worker.ajp13w.type=ajp13 worker.ajp13w.port=8009 # # Defining a load balancer # worker.wlb.type=lb worker.wlb.balance_workers=ajp13w # # Define status worker # worker.jkstatus.type=status }}}

<Connector port="8009"


LoadModule webauth_module modules/ # Set locations for various files used by mod_webauth WebAuthKeyring webauth/keyring WebAuthKeytab webauth/keytab WebAuthServiceTokenCache webauth/service_token_cache WebAuthCredCacheDir webauth/cred_cache # Point to the Oxford Webauth service WebAuthLoginURL WebAuthWebKdcURL WebAuthWebKdcPrincipal service/webkdc@OX.AC.UK # If you're having trouble switch on debugging WebAuthDebug on # For each location that you want to protect using Webauth you should add a section like: <Location /shibboleth-idp/SSO>

</Location> }}}

2.2. Generate required PKI values


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

1.3 Metadata:

{{{<EntityDescriptor entityID="">

</EntityDescriptor> }}}

1.2 Metadata:

{{{<OriginSite xmlns="urn:mace:shibboleth:1.0" Name="">

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


Buildfile: build.xml init: install.init: install: Do you want to install the Shibboleth Identity Provider? [Y,n] y What name do you want to use for the Identity Provider web application? [default: shibboleth-idp] init: install.init: install.idp: Deploying the java web application. Do you want to install it directly onto the filesystem or use the tomcat manager application?

1 init: install.init: install.idp.filesystem.prompt: Select a home directory for the Shibboleth Identity Provider [default: /usr/local/shibboleth-idp] /opt/shibboleth-idp Enter tomcat home directory [default: /usr/local/tomcat] /opt/apache-tomcat/apache-tomcat-5.5.16 init: install.init: compile: ext-invoke: build-util: Building jar: /opt/shibboleth/shibboleth-idp-1.3c-install/lib/shib-util.jar install.url: package-idp: Copying 1 file to /opt/shibboleth/shibboleth-idp-1.3c-install/webAppConfig ext-invoke: Building war: /opt/shibboleth/shibboleth-idp-1.3c-install/dist/shibboleth-idp.war Deleting: /opt/shibboleth/shibboleth-idp-1.3c-install/webAppConfig/idp.xml install.idp.filesystem: Copying 1 file to /opt/apache-tomcat/apache-tomcat-5.5.16/webapps Copying 11 files to /opt/shibboleth-idp/lib Copying 4 files to /opt/shibboleth-idp/endorsed Copying 7 files to /opt/shibboleth-idp/bin Created dir: /opt/shibboleth-idp/logs init: install.init: install.url: Skipping urlconvert as property idp.home.url has already been set. Skipping urlconvert as property sp.home.url has already been set. install.idp.filesystem.config: Created dir: /opt/shibboleth-idp/etc Copying 12 files to /opt/shibboleth-idp/etc Moving 1 files to /opt/shibboleth-idp/etc ext-invoke: savePropertyFile: Updating property file: /opt/shibboleth/shibboleth-idp-1.3c-install/ BUILD SUCCESSFUL Total time: 2 minutes 34 seconds }}}

The Shibboleth authentication system experienced a technical failure. Please email root@localhost and include the following error message: Identity Provider failure at (/shibboleth-idp/SSO) org.opensaml.SAMLException: Invalid data from Service Provider: no target URL received. }}}

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 and TomcatNotes#EnablingServletLogging for more details.


<RelyingParty name="urn:mace:inqueue" signingCredential="inqueue_cred">

</RelyingParty> }}}

</Logging> }}}

</Credentials> }}}


Other points to check if there are problems:

<Connector port="8009"


2.4.1. IdP and attribute results

Validate the IdP by browsing to, 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):

</Response> }}}

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

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://,dc=ox,dc=ac,dc=uk" />

</JNDIDirectoryDataConnector> }}}

  1. For each attribute to be returned from LDAP, edit or create an entry of the form:

</SimpleAttributeDefinition> }}}

  1. 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="">

</SimpleAttributeDefinition> }}}

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

</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/; e.g.:

<AttributeReleasePolicy xmlns:xsi=""

</AttributeReleasePolicy> }}}

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, all RPM files in that directory.

  2. Following the instructions at page

  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:
     is needed by log4cpp-0.3.5rc1-1.i386
     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

  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, saving them to /usr/src/redhat/SRPMS/:

    • cd /usr/src/redhat/SRPMS/
      wget -r -l1 --nodirectories -A.rpm
    • 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 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..." - The most helpful instructions were found at:

  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>

</Location> }}}

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


  1. Start the shibd daemon:

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 ( Session Creation Error }}}

  1. Configure the identity provider:
    • In <Local>/<RequestMapProvider>:

      {{{<Host name=""> <Path name="secure" authType="shibboleth" requireSession="true"/>

</Host> }}}

</Site> }}}


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


  1. Copy the IdP key and certificate files to /etc/Shibboleth, and configure the identity provider credentials:


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:

The inter-institutional access system was unable to successfully build a login session for you at Wed Jun 14 15:04:00 2006 To report this problem, please contact the site administrator at root@localhost. Please include the following message in any email: Session creation failure at ( Session Creation Error }}}

[Wed Jun 14 15:03:45 2006] [error] [client] Directory index forbidden by rule: /var/www/html/ [Wed Jun 14 15:03:50 2006] [error] [client] File does not exist: /var/www/html/Shibboleth.SSO }}}

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

  1. Configuring an IdP Attribute Release Policy (ARP) arps/ 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">

</Attribute> <Attribute name="urn:mace:dir:attribute-def:cn">


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

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

[What about local attributes like oucsStatus?]

  1. - Tomcat configuration

  2. - Tomcat AJP connector configuration

  3. - Personalisation, Shibboleth and WSRP in the SPIE Project, Jasper Tredgold's presentation to the Sakai VRE demonstrator workshop help in Portsmouth, January 2006.

  4. - Shibboleth-aware Portals and Information Environments (SPIE) project website

  5. - Instructions for Shibboleth IdP installation

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

  7. - WebAuth Apache module for Kerberos-based authentication. Download and installation instructions:

4.1. Shibboleth and SPIE project notes

4.2. Other intallation notes

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.