Shibboleth IdP and SP Installation and Configuration

Shibboleth is a free open source implementation for identity management, providing a web-based single sign-on mechanism across different organizational boundaries. It is a federated system, supporting secure access to resources across security domains. Information about a user is sent from a home identity provider (IdP) to a service provider (SP) which prepares the information for protection of sensitive content and use by applications. If you are not familiar with Shibboleth and how it works, you may be benefited from the Shibboleth home page. In this tutorial we will cover installation of the IdP first and then we will perform the necessary configuration to customize the IdP for an organization. Afterwards, we will install and configure the shibboleth SP and will setup a basic scenario to protect a resource.

IdP Installation
This is an installation guide to setup an IdP with the basic features. For a detail introduction to the identity provider or Shibboleth, please refer to Understanding Shibboleth. This tutorial uses CentOS 5.6 as the OS for IdP server.

1. Java 1.6 (Prerequisite):
CentOS ship with the GNU Java compiler and VM (OpenJDK 1.6) by default. These are not usable with Shibboleth so you must install another JVM. The Sun HotSpot VM is the most commonly used. We will install the Sun JDK 1.6 as:

Download Sun JDK 1.6 (latest update) from Sun Java download. Choose the correct platform and product (Linux x86 – Self Extracting Installer) and download jdk-6uXX-linux-i586.bin. Place it in a directory of your choice; we will place it in /usr/local/src using the commands:

# cd /usr/local/src
# curl -L -O

You have to give the executable permissions to the downloaded installer as:

# chmod +x jdk-6uXX-linux-i586.bin

Install JDK 1.6 by the following command:

# ./jdk-6uXX-linux-i586.bin
# java -version will show java version "1.6.0"

2. Apache Tomcat:
The Shibboleth Identity Provider, version 2, is a standard Java web application based on the Servlet 2.4 specification. In order to install the IdP we need to prepare a Servlet container for the deployment of our IdP. There are a number of Servlet containers available but we will use the most popular one i.e., Apache Tomcat. If you don’t want to use Apache Tomcat you can use Jetty 7, or JBoss Tomcat.

a) Download and Install Apache Tomcat:
Apache Tomcat 6.0.17 or greater is required, download to /usr/local/src and extract it as:

# curl -L -O
# tar -xvzf apache-tomcat-6.0.32.tar.gz

We will rename it to a shorter name i.e., tomcat6 (we will call it TOMCAT_HOME throughout the document):

# mv apache-tomcat-6.0.32 tomcat6

Set the following environment variables before starting tomcat:

# export JAVA_HOME=/usr/local/src/java6-source/jdk1.6.0_25
# export PATH=$JAVA_HOME/bin:$PATH
# export CATALINA_HOME=/usr/local/src/tomcat6
# export CATALINA_BASE=/usr/local/src/tomcat6

To make the environment variables persistent throughout different sessions add the above lines (excluding the # sign) to your profile file (.bash_profile).

b) Configure JVM memory options for the needs of the IdP web application. The values for memory usage depend on the physical memory of the server. Set Xmx (maximum amount of heap space available to the JVM) to at least 512 MB and XX:MaxPermSize to 128 MB.

Edit the TOMCAT_HOME/bin/ file and add the JAVA_OPTS variable as:

JAVA_OPTS="-Djava.awt.headless=true -Xmx512M

c) In the file TOMCAT_HOME/conf/server.xml, the default value of the parameter autoDeploy is equal to true. This means that Tomcat checks periodically for new or updated web applications. If an updated web application or context XML descriptors is found, a redeploy is triggered. This is not the preferred behavior, therefore set this to false as:

<Host  appBase="webapps" unpackWARs="true" autoDeploy="false"
xmlValidation="false" xmlNamespaceAware="false">

d) Start tomcat:

# TOMCAT_HOME/bin/ start

Check whether it’s running by typing the following in your browser:
http://localhost:8080  (If you see the tomcat home page, it’s running)

3. Shibboleth IdP Installation:
This section describes the installation and configuration of the Shibboleth IdP.
a) Get the latest Identity Provider software package from the Shibboleth download page, you may download to /usr/local/src as:

# curl -O

b)  Extract the and make the installer script executable. The archive will be extracted into the directory shibboleth-identityprovider-2.3.0 as:

# unzip
# cd shibboleth-identityprovider-2.3.0
# chmod u+x

c) Endorse Xerces (Java parser for XML) and Xalan (Xalan is an XSLT processor for transforming XML documents into HTML, text, or other XML document types) libraries from the Shibboleth IdP source package in TOMCAT_HOME/endorsed. Copy the endorsed directory and the included jar files from the shibboleth-idp source directory to the TOMCAT_HOME directory as:

# cp -r endorsed/ /usr/local/src/tomcat6
# export JAVA_ENDORSED_DIRS=/usr/local/src/tomcat6/endorsed

d) Run the installer script to install IdP as:

# ./

The installer will ask for the installation directory (default is /opt/shibboleth-idp) and a fully qualified hostname for the IdP server (default is during the installation process. We will use the default location and for hostname. You may provide a location and hostname of your choice. The hostname cannot be changed at later stage for a particular installation. Remember the password that you provide for the key store during installation as this password will be used later in configuration.
Note: The installation directory given during installation will be known as IDP_HOME throughout this document.

e) You may set symbolic links for your convenience. Link /etc/shibboleth to the shibboleth-idp configuration directory and /var/log/shibboleth to the shibboleth-idp log directory:

# ln –s /opt/shibboleth-idp/conf /etc/shibboleth
# ln –s /opt/shibboleth-idp/logs /var/log/shibboleth

f) Set the IDP_HOME environment variable as:

# export IDP_HOME=/opt/shibboleth-idp

Add  the following to the .bash_profile file edited earlier:

export IDP_HOME

g) Supporting SOAP Endpoints:
During certain operations like Attribute Query, Artifact Resolution, and Logout the Shibboleth IdP and SP may communicate directly, as opposed to sending messages via the user’s browser. In order to support these request the IdP needs an additional port (called a Connector within the Tomcat configuration), distinct from the one used by the user (because they have different, mutually exclusive, security requirements). To support SOAP endpoints perform the following steps:

i) Download tomcat6-dta-ssl-1.0.0.jar in to TOMCAT_HOME/lib/ folder.

ii) Add the following connector definition to Tomcat’s TOMCAT_HOME/conf/server.xml file:

<Connector port="8443"
scheme="https" SSLEnabled="true" clientAuth="true"
keystorePass="yourPasswordHere" />

Note: In the keystorePass provide the password that you entered during shibboleth-idp installation.

h) Deploy the IdP WAR file, located in IDP_HOME/war/ using a context deployment fragment:
The normal procedure of deploying web applications to Tomcat is by copying the WAR file into the Tomcat webapps/ folder. However, when this procedure is followed Tomcat will explode the war (giving you idp.war and idp/ within webapps/) and then cache another version of the application in work/Catalina/localhost/. This can lead to cases where you copy a new WAR into place but Tomcat continues to use the older version.

To address this issue, it is recommended that you use a context deployment fragment. It means that you use a small bit of XML that tells Tomcat where to get the WAR and provides some properties used when Tomcat load the application. This approach will also prevent those times when you create a new WAR and forget to copy it into Tomcat as this makes Tomcat load the war from IDP_HOME/war/ where the installer places it.

Create and open the file at TOMCAT_HOME/conf/Catalina/localhost/idp.xml as:

# vi /usr/local/src/tomcat6/conf/Catalina/localhost/idp.xml

Copy the following content to the newly created idp.xml file:

<Context docBase="/opt/shibboleth-idp/war/idp.war"
privileged="true" antiResourceLocking="false"
antiJARLocking="false" unpackWAR="false"
swallowOutput="true" />

At this point, your IdP’s basic installation and configuration is completed. The IDP_HOME directory created during installation will have the following directories:

  • bin/ – This directory contains various tools useful in running, testing, or deploying the IdP
  • conf/ – This directory contains all the configuration files for the IdP
  • credentials/ – This is where the IdP’s signing and encryption credential, called idp.key and idp.crt, is   stored
  • lib/ – This directory contains various code libraries used by the tools in bin/
  • logs/ – This directory contains the log files for the IdP
  • metadata/ – This is the directory in which the IdP will store its metadata, in a file called idp-metadata.xml.  It is recommended you store any other retrieved metadata here as well.
  • war/ – This contains the web application archive (war) file that you will deploy into the servlet container

i) A quick test at this point:
The IdP can be tested for proper installation and running by accessing the URL: (replace the hostname with your hostname that you have used during IdP installation). If you receive an “ok” page, it means everything is okay till now. You will not be able to log into anything yet as you have not yet configured the IdP to use your organization’s infrastructure. Before testing the URL do the following:

  • Stop the TOMCAT (if it’s running) and start it again so that it deploy the idp.war

# /usr/local/src/tomcat6/bin/ stop
# /usr/local/src/tomcat6/bin/ start

  • Add your local IP address and the hostname to your hosts file as:

# vi /etc/hosts    idp

j) Enabling SSL for the IdP (Optional):
On the IdP system, X.509 certificates are installed for different purposes:

  • Secure the traffic on the login page
  • Secure the communication with the Shibboleth Service Providers

For the IdP login page, a certificate from an official CA (of which the root is in the browser) is needed. This will make sure the users can verify they are submitting their credentials to a server they trust. We will create our own certificates to secure the traffic to login page and communication with SP, alternatively for actual deployment; one MUST get certificates from an official Certification Authority.

Tomcat currently operates only on JKS, PKCS11 or PKCS12 format keystores. The JKS format is Java’s standard “Java KeyStore” format, and is the format created by the keytool command-line utility. This tool is included in the JDK (nothing new to install if you have installed Java as shown in the prerequisite step above).

If you have an existing certificate signed by an official CA or your own CA, you can import that certificate to a keystore using OpenSSL as:

# openssl pkcs12 -export -in yourcert.crt -inkey yourkey.key -out idpself.p12 -name tomcat -Cafile yourCA.crt -caname root –chain

(This will create a file by the name idpself.p12 in the directory from where the command was executed. The above command will work assuming OpenSSL is installed, if not install as # yum install openssl)

If you don’t have any existing certificate and want to create a new keystore from scratch, containing a single self-signed certificate, execute the following commands to create a directory to store the certificate keystore and generate an RSA keystore. You will be asked to provide a password for the keystore, remember this password as you will need it in the next step:

# mkdir /home/yourHomeDir/idpcerts/
# keytool -genkey -alias tomcat -keyalg RSA -keystore /home/yourHomeDir/idpcerts/idpself.keystore

You will also need to reflect this new location of the keystore in the server.xml configuration file of Tomcat. Open the server.xml in TOMCAT_HOME/conf directory and search for the connector port 443. Make the following modification to the connector. If this connector is not present, simply copy the following to the server.xml file:

<Connector port="443" protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true" clientAuth="false"
keystorePass="yourPasswordHere" />

Set the keystoreFile to the location where you have stored the newly created Java key store (idpself.keystore) or the converted p12 keystore file (idpself.p12) and keystorePass to your provided password at time of creating the key store. To test whether SSL works open the following address in a browser:
If your browser returns with the “ok” page then you have successfully configured SSL for your IdP server, if you have any problems, comment below and I will try to help.

k) Setting up the Authentication Mechanism:
According to Shibboleth wiki IdP can support different authentication mechanisms at one time. As an added feature in SAML 2.0 a Service Provider may require one (from a possible list) of authentication method be used. If the IdP is configured for one of the methods required by the SP, then such a method is used. If the Service Provider does not require a specific method, then the default method, identified on the relying party’s configuration, is used. If no default is specified, the IdP chooses a method randomly.

1) Configuring the IdP for Username/Password Authentication:
This authentication handler supports authenticating users with a username/password and is performed through the Java Authentication and Authorization Service (JAAS). The Username/Password handler presents the user with an authentication page and then checks the entered username and password against an LDAP directory or Kerberos 5 domain.

Open the handler.xml file in IDP_HOME/conf/ directory and perform the following:
Enable the UsernamePassword login handler in the configuration file by remove the comments around the UsernamePassword <LoginHandler> element. You must comment out the RemoteUser <LoginHandler>element or the authentication will be open for any user. You handler.xml should look like as:

<!--   ....   -->
<!-- Login Handlers -->
<ph:LoginHandler xsi:type="ph:RemoteUser">
<!--  Username/password login handler -->
<ph:LoginHandler xsi:type="ph:UsernamePassword"

2) Setting up an LDAP server and LDAP browser:
ApacheDS is an extensible and embeddable directory server entirely written in Java, which has been certified LDAPv3 compatible by the Open Group. Besides LDAP it supports Kerberos 5 and the Change Password Protocol. It has been designed to introduce triggers, stored procedures, queues and views to the world of LDAP which has lacked these rich constructs. We will use ApacheDS as our LDAP server. Download and install Apache Directory Server as:

# curl –O
# chmod a+x apacheds-1.5.2-i386.bin
# ./apacheds-1.5.2-i386.bin
(proceed with the default options provided during installation)

Run ApacheDS:

# /etc/init.d/apacheds-1.5.2 start

In order to create your own authentication server for your own organization and add users to the ApacheDS, you need to install Apache Directory Studio.
Apache Directory Studio is a complete directory tooling platform intended to be used with any LDAP server however it is particularly designed for use with ApacheDS. It is an Eclipse RCP application, composed of several Eclipse (OSGi) plugins that can be easily upgraded with additional ones.
Download and install Apache Directory Studio:

# curl –O

Extract the downloaded archive and place the extracted folder where you want Apache Directory Studio to be installed. We will shorten its name and place it in /opt:

# tar –xvzf ApacheDirectoryStudio-linux-x86-1.5.3.v20100330.tar.gz
# mv ApacheDirectoryStudio-linux-x86-1.5.3.v20100330 /opt/apachedirstudio

Move to the extracted directory and run Apache Directory Studio using the following command:

# cd /opt/ apachedirstudio
# ./ApacheDirectoryStudio

You need to create a new LDAP connection with the LDAP server i.e., Apache Directory Server (make sure it’s running).

  • Click on File –> New –> LDAP Connection (from the LDAP Browser wizard selection).
  • In the Network Parameter pane enter a name for the connection (CSRDU LDAP), in the Hostname field enter the name of the host where the Apache Directory Server is running (localhost in our case), and in the port field enter 10389 for the Port (since Apache Directory Server is listening on this port). Click Next:

Network Parameter

  • In the Authentication pane select the Authentication Method as Simple Authentication, in the Bind DN or user field, enter uid=admin,ou=system (this is the DN of the administrator’s account on the for the default instance of the Apache Directory Server), and in the Bind password field, enter the administrator’s password which is secret for the default instance.

Authentication Pane

  • If the connection is successfully established, you should see the Directory Information Tree (DIT) in the LDAP browser view, drill down the ou=users view as shown:

LDAP Browser View

  • To add a new user; right-click on the ou=users node and select New Entry. The New Entry wizard appears.
  • In the Entry Creation Method pane, you do not need to change any settings. Click Next.
  • In the Object Classes pane, select inetOrgPerson from the list of Available object classes on the left and then click Add to populate the list of selected object classes. Click Next.

Object Classes Pane

  • In the Distinguished Name pane, complete the RDN field, putting uid in front and any user identifier after the equals sign. Click Next.

Distinguished Name pane

  • Now fill in the remaining mandatory attributes in the Attributes pane. Set the cn (common name) and the sn (surname) attributes for the newly created user. Click Finish.

Attributes Pane

  • Add a userPassword attribute to the user entry. In the LDAP Browser view, you should now be able to see a new node, uid=skhan. Select the uid=skhan node. Now, right-click in the Entry Editor view and select New Attribute. The New Attribute wizard appears.
  • From the Attribute type drop-down list, select userPassword. Click Finish.

New Attribute Pane

  • The Password Editor dialog appears. In the Enter New Password field, enter a password and Click Ok. A new user is created.

Password Editor

Take a note of the LDAP URL i.e., ldap://localhost:10389 and the DN i.e., ou=users,ou=system as both these values will be required in setting up the JAAS.

3) Setting up JAAS
The JAAS authentication policy to be used with Shibboleth is specified by the jaasConfigurationLocation attribute on the AuthenticationHandler element as mentioned above. The deployment of Shibboleth IdP requires using ShibUserPassAuth as the JAAS policy application configuration entry.

Open the login.config file in IDP_HOME/conf/ directory, at the end of the file you will find ShibUserPassAuth, copy the following inside the ShibUserPassAuth parenthesis and make sure everything else is commented out inside the parenthesis:

ShibUserPassAuth {
edu.vt.middleware.ldap.jaas.LdapLoginModule required
host="ldap://localhost:10389" base="ou=users,ou=system"
ssl="false" userField="uid";

4. Shibboleth IdP Advance Configuration:
a) Metadata Trust Configuration:
In the Shibboleth Identity Provider a great deal of functionality is driven from SAML metadata information. Metadata refers to the configuration data used to provision an SP or IdP to communicate with each other. It is provided to the IdP through <MetadataProvider> elements that are defined in the IDP_HOME/conf/relying-party.xml file. During the IdP installation a basic metadata for IdP is generated and is reflected in the relying-party.xml file. We need to provide this metadata to any Server Provider relying on our IdP. The IdP also need to be informed about the relying parties (SPs) through their metadata. Since we haven’t installed the SP yet in this tutorial, so we will wait till SP installation and will cover how to edit relying-party.xml file in the configuration section of SP.

b) Attribute Resolution and Filtering:
According to Shibboleth wiki when an attribute is requested from a source system and is released to a SP, it passes through four main steps: it’s pulled from the system of record (LDAP or DB etc…), massaged within the provider, given a set of protocol-specific encoders, and then filtered for release. Every attribute has a unique attribute ID which is used to refer to it consistently through this process. You may read further details provided in the link above.

Shibboleth doesn’t store any attributes about users itself; it relies on external data stores to supply user information to be released. These attributes are pulled from data sources using data connectors. You may need to modify your existing data connectors or add a new one if the attribute isn’t available through any existing connector. We will use the existing data connector for LDAP by editing the IDP_HOME/conf/attribute-resolver.xml file. The file contains different AttributeDefinition elements but are commented out. You need to search for the attributes that you wish to make available for release to SP. We will release the Common Name (cn) and Surname (sn) attributes, copy the following to the file (make sure to copy in an uncommented area):

<resolver:AttributeDefinition xsi:type="ad:Simple"
xmlns="urn:mace:shibboleth:2.0:resolver:ad" sourceAttributeID="cn">
<resolver:Dependency ref="myLDAP" />
<resolver:AttributeEncoder xsi:type="enc:SAML1String"
xmlns="urn:mace:shibboleth:2.0:attribute:encoder"name="urn:mace:dir:attribute-def:cn" />
<resolver:AttributeEncoder xsi:type="enc:SAML2String"
friendlyName="cn" />

<resolver:AttributeDefinition xsi:type="ad:Simple"
xmlns="urn:mace:shibboleth:2.0:resolver:ad" id="surname" sourceAttributeID="sn">
<resolver:Dependency ref="myLDAP" />
<resolver:AttributeEncoder xsi:type="enc:SAML1String"
xmlns="urn:mace:shibboleth:2.0:attribute:encoder"name="urn:mace:dir:attribute-def:sn" />
<resolver:AttributeEncoder xsi:type="enc:SAML2String"
xmlns="urn:mace:shibboleth:2.0:attribute:encoder" name="urn:oid:"
friendlyName="sn" />

Scroll down to the end of the file where Data Connectors are given. Uncomment the LDAP connector to reflect your changes or copy the following. Your LDAP connector should look like as:

<!-- Example LDAP Connector -->
<resolver:DataConnector xsi:type="dc:LDAPDirectory"
baseDN="ou=users,ou=system" principal="uid=admin,ou=system"
<![CDATA[ (uid=$requestContext.principalName) ]]>

An Attribute Filter policy describes which attributes are sent to a Service Provider. The default attribute filter policy file attribute-filter.xml is in IdP_HOME/conf/ directory. The changes made to the attribute-resolver.xml needs to be reflected in the attribute-filter.xml file. Edit the file and place the following under the <AttributeFilterPolicy> element:

<afp:AttributeRule attributeID="commonName">
<afp:PermitValueRule xsi:type="basic:ANY" />

<afp:AttributeRule attributeID="surname">
<afp:PermitValueRule xsi:type="basic:ANY" />

Installing SP:
This is an installation guide to setup a Service Provider (SP) with the basic features. For a detail introduction to the Service Provider or Shibboleth, please refer to Understanding Shibboleth.

Operating System:
Shibboleth SP2 can be built on a number of 32-bit and 64-bit Linux distributions. We will install it on CentOS-5.6 i386 OS. For detail information about other distributions and building it from source you may read NativeSPLinuxInstall.

Note: Disable SELinux at time of CentOS installation or at least change its mode to permissive while performing the initial setup and testing SP. This is what written on NativeSPLinuxInstall “We strongly suggest that during any initial setup or testing, that SELinux be left disabled or in permissive mode, and we don’t officially support the SP’s use with it enabled.”

a) Installing Shibboleth SP from RPMs:
I started to build Shibboleth SP from source and compiled all of the prerequisites but ended up with a huge number of errors and I switched to install it the easiest way using yum which is the recommended approach for installation SP.

The root of the repository tree for Shibboleth can be found at with each supported OS in its own subdirectory. Each subdirectory is the root of a yum repository and contains a definition file named security:shibboleth.repo.

Open the file CentOS-Base.repo residing at /etc/yum.repos.d/ directory and add the following lines at the end of the file:

#adding shibbolethSP repos
name=Shibboleth (CentOS_5)

Now run the following command to install SP:

# yum install shibboleth

When the installation is completed, various components of Shibboleth will be placed in appropriate directories based on the OS file system layout. You may check:

  • Shibboleth configuration files will be placed at /etc/shibboleth/ and the necessary Apache configuration  in /etc/httpd/conf.d/shib.conf
  • shibd will be installed to /usr/sbin and may be managed using /sbin/service and /sbin/chkconfig
  • An appropriate version of mod_shib and other pluggable modules will be installed to /usr/lib/shibboleth/
  • Logs will be located in /var/log/shibboleth/shibd.log

SP Configuration:
Basic Configurations:
a) Edit httpd.conf:
Open httpd.conf file located at /etc/httpd/conf/ directory and make the following changes:

  • Change the ServerName directive to the server name of your SP (
  • To ensure that there is no resource mapping errors while running the SP, the UseCanonicalName directive should be set to On.

b) Restart Apache:

# /etc/init.d/httpd restart

c) The shibd daemon must be independently started and run in order to handle requests

# /etc/init.d/shibd start

d) You may check the log which is created by shibd at /var/log/shibboleth/shibd.log

# cat /var/log/shibboleth/shibd.log

e) Enable ssl:

# yum install mod_ssl openssl

For actual deployment, you MUST obtain a certificate from an official CA. For testing purpose you may create a certificate using openssl by performing the following steps:

First you need a key pair for your server so create a key pair as:

# openssl genrsa -out ca.key 1024

Now create a certificate for your server:

# openssl req -new -x509 -days 3650 -key ca.key -out ca.crt

Place the key file and certificate in a directory preferably place it as:

# cp ca.crt /etc/pki/tls/certs/
# cp ca.key /etc/pki/tls/private/

The ssl.conf file at /etc/httpd/conf.d/ directory needs to be modified:

# vi /etc/httpd/conf.d/ssl.conf

Change the location for SSLCertificateFile and SSLCertificateKeyFile to reflect the above mentioned location respectively.

f) Initial Testing:
You can test to ensure that the SP is running properly by accessing from the actual web server machine. If this test is successful, then the software is ready for further configuration. Before accessing the URL add the hostname to the hosts file (/etc/hosts) as:

# vi /etc/hosts   sp

Advance Configurations:
a) Configuring the Metadata:
As stated in the IdP configuration section that metadata plays an important role in identifying and building the trust between an IdP and SP. Unlike IdP installation process the SP installation does not generate default metadata. You have to request a metadata from any pre-existing Federation or create your own by hand. Once you create or acquire metadata for SP, you must supply it to the IdP. Similarly, the IdP MUST supply its metadata to the SP. There are three different methods of supplying metadata to SP/IdP. We will follow the simple approach; maintaining the metadata in files that you copy to the IdP or SP server to load from the local file system.

For an initial setup you can download metadata for SP from here and place it at IdP (/opt/shibboleth-idp/metadata). You will have to change the SP certificate with the one of your own installed SP. The certificate is residing at /etc/shibboleth by the name sp-cert.pem. Make sure the name of the metadata file is sp-metadata.xml as it is reflected at different configuration files by the same name and the entityID of the SP server must match that of your SP server in the metadata you download, if you are following the naming conventions used in this tutorial then no need to change the entityID.

At the IdP server copy its metadata file idp-metadata.xml located at /opt/shibboleth-idp/metadata directory and place it at your SP server at location /etc/shibboleth/ directory. This way the both SP and IdP have supplied their metadata to each other.

b) Configuration to reflect the metadata:
At IdP server add the following to the relying-party.xml file (at /opt/shibboleth-idp/conf/) just after the IdP’s own metadata is defined:

<!-- Load the SP's metadata.  -->
<metadata:MetadataProvider xsi:type="FilesystemMetadataProvider"
xmlns="urn:mace:shibboleth:2.0:metadata" id="SPMETADATA"
metadataFile="/opt/shibboleth-idp/metadata/sp-metadata.xml" />

At the SP server edit the shibboleth2.xml file (at /etc/shibboleth/), uncomment the <MetadataProvider>  element as:

<!-- Example of locally maintained metadata. -->
<MetadataProvider file="idp-metadata.xml"/>

c) Primary changes to SP configuration file:
Here is a summary of the primary changes required to the initial configuration of the SP software (in shibboleth2.xml). Open the file /etc/shibboleth/shibbolet2.xml and perform the following:

  • Change the entityID attribute located in the <ApplicationDefaults> element to one that’s appropriate for your service i.e., your SP hostname. An https:// URL is recommended as:
  • Change the homeURL attribute to the best landing spot in the event that users end up at your site without a more specific URL. This should be an absolute URL. In the <RequestMapper> element add the following under <RequestMap applicationId=”default”> element:
<Host name="">
<Path name="secure" authType="shibboleth" requireSession="true"/>
  • For testing purposes, it’s simplest to start with a single IdP and point the SP to it by modifying the default <SessionInitiator> in the file to it. Replace the entityID attribute in the outer element with the name of the IdP to use as:

d) Attribute Extraction:
The <AttributeExtractor> element configures the component used by the SP to turn SAML content into attributes, the internal representation of information stored with user sessions. This element is set to refer the attribute-map.xml file by default; open the attribute-map.xml file at /etc/shibboleth/ directory uncomment the following two attributes:

<Attribute name="urn:oid:"  id="cn"/>
<Attribute name="urn:oid:"  id="sn"/>

Note: If your IdP is releasing different attributes than the above mentioned, you have to write those attributes here. The attribute-map.xml file contains a number of attributes but are commented out, search for your required attribute and uncomment it.

e) Protecting a resource:
Once you’ve actually configured the SP with its own settings and metadata from at least one IdP, in order to check that the SP is working. Protect a directory by requiring a Shibboleth session. Usually, this is already done by default for the location /secure. You can view the following is added by default at shib.conf file at /etc/httpd/conf.d/ directory.

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

Create a directory by the name secure at /var/www/html/ and place your application in this directory that you want to protect. For testing, you can place a script inside the protected directory that dumps the web server environment by placing a PHP file in the directory with the following code:

<?php print_r($_SERVER) ?>

A more advanced version of such a script can be found here. Download it and place it in the secure directory.

If you want to keep another resource on the same server to be openly accessed without Shibboleth authentication; Create another directory by the name /unsecure at /var/www/html/ and place whatever resource you want to be accessed without authentication. Open the shib.conf file at /etc/httpd/conf.d/ and place the following at the end of the file:

<Location /unsecure>
AuthType shibboleth
ShibRequireSession Off
require shibboleth

If you want to impose further access control e.g., to allow access to users from a particular Organizational Unit, your configuration at shibd.conf for the protected resource should look like:

<Location /secure>
AuthType shibboleth
ShibRequestSetting requireSession 1
ShibExportAssertion On
require organizationName CSRDU

The above will allow only those users who are affiliated with CSRDU. To test this, create a new user using Apache Directory Studio (follow the steps given in the LDAP section). To add an OrganizationalUnit attribute to the newly created user, repeat the step as you added the password attribute and select OrganizationalUnit and then click Finish. You will be prompted for the OrganizationalUnit name, enter whatever name you like and then write down that name in the shib.conf file as mentioned above. This way, you can control access to particular resources using different policies. This is just an example to show how it works, more details can be found at NativeSPXMLAccessControl and NativeSPhtaccess.

f) Let’s check it:
Edit the hosts file (/etc/hosts) of your IdP server and enter the IP address of your SP and vice versa. Add the IdP and SP IP addresses in the hosts files of your client machines.

  • Open a browser at Client machine and type the following URL: You will be redirected to the Login page at IdP as shown:

    Login Page at IdP

  • If you provide the valid username/password, authentication will be successful and you will access the resource:

    Access to Protected Resource after Successful Authentication

  • You can view the Assertions by clicking the Show Shibboleth assertions Option:

    SAML Assertion from IdP

  • If you are authenticated successfully but have no access rights to view the resource you will not be authorized to access the resource (users from OrganizationalUnit other than CSRDU in this example):

Unauthorized user accessing the resource

  • You can logout from the SP by accessing the URL:

    Logout Page

    In a nutshell Shibboleth is mainly divided into two halves: an identity provider (IdP), and a service provider (SP). The identity provider is responsible to supply information about users to services, and the service provider gathers information about users to protect resources. In a typical scenario, a web browser accesses a protected resource, authenticates at their identity provider, and ends up back at the resource logged in. You may wish to read FlowsAndConfig for further detail. You may BuildAFederation of your own and/or add a DiscoveryService for your organization. We haven’t tried these yet. Stay tuned and you might find out more about it.

Sohail Khan is a PhD candidate at Malaysian Institute of Information Technology, University Kuala Lumpur, Malaysia. His research interests include information security and open source mobile platform. His recent research focuses on secure and trusted applications for mobile platforms to leverage Trusted Computing technologies for enhancing the trustworthiness of these platforms. He has a Masters in Information Technology and can be reached at sohail (dot) khan67 (at) gmail (dot) com.

Leave a comment


  1. Muhammad Amin


    Good Work! It reminds me of hard days with my thesis.


  2. WS Amin,

    Thanks. If I remember correctly, Shibboleth was the first project that we opt to start. In fact, we met due to shibb…

  3. Very Usefull article ..

  4. Thank you akif. You can contribute too, but we have an approval system before publishing any contribution.

  5. hi, sohali i wnt to discuss with you regarding the shibboleth.

  6. @umesh You can post your query/comment here.

  7. Hi, we have a requirement to use the shibboleth 2.4 SP for spring application. I want to simulate with simple application running with tomcat web server along with the Apache 2.2 HTTP server how the flow with work (direct and redirect of the requests) can you please guide me ASAP.

  8. Take a look at shibboleth communication flow. From the diagrams shown in the link, you will have a better idea to place your app at the SP. You may follow our tutorial for the attribute release and decision making process.

  9. I am new with shibboleth. Could you post the snippy of the SP SessionInitiator with a single IdP? Many thanks,

  10. Good article, Sohail. I came across this page when I was looking for how to make SP select a specific authentication method to be used by the IDP. You mentioned about it in here but I would appreciate if you could provide more details about how that can be done.

  11. @lli here is the snippet for you:

    <SessionInitiator type=”Chaining” Location=”/Login” isDefault=”true” id=”Login”
    relayState=”cookie” entityID=””>
    <SessionInitiator type=”SAML2″ defaultACSIndex=”1″ acsByIndex=”false” template=”bindingTemplate.html”/>
    <SessionInitiator type=”Shib1″ defaultACSIndex=”5″/>

  12. Hi,
    Its very nice article. I would appreciate if you could provide me shibboleth2.xml for the same article you configured. Many thanks.

  13. Thanks a lot bro, great description.

  14. Hi Sohail,
    Thanks a lot for the article. It helped me setup IDP so easily. However the status pages do not show ‘ok’; instead only a blank page is displayed. Is it exoected behaviour or I have missed anything?

  15. Hi Sohail,

    I followed the steps for SP installation as mentioned in the above article. However, when I try to check the installation, the status page shows 403 error (Forbidden).
    I doubt if my SSL configuration is correct. Can you point out exactly what is wrong?

  16. Hi Shoba, You must be able see the “ok” page after successful configuration of the IdP. The SP status page must show the detail about the SP in xml format. The steps given above are tested and working fine so you might be missing something. You may check your configurations again or visit the shibboleth IdP/SP installation/configuration official site for any changes.

  17. Hi Shoba,

    Thanks for the detailed steps. I followed all the steps however I got a error message saying Unable to locate metadata for identity provider (
    I did do the step

    Could you help me?


  18. The xml fragment for attribute-resolver.xml has some error, please correct it:

    <resolver:AttributeDefinition xsi:type="ad:Simple"
    xmlns="urn:mace:shibboleth:2.0:resolver:ad" id=”commonname” sourceAttributeID=”cn”>

    - should remove

  19. “” should remove too

  20. \ should remove

  21. couldn’t post xml code somehow , any way “code” tag should be removed too

  22. Hello sohail,

    Very good article. I appreciate it very much. One question i still have here with respect to entity id.
    The idp provider has asked us to provide the entity id and we are at the moment configuring the additional configurations. The idp said that they will send their assertion to us which also contains the audience restriction (our entity id). If the audience restriction dosent match our entity id, then our sso server will simple reject the request. Can you throw some light, how the sp server verifies the audience restriction?

    Awaiting your reply,

  23. Hello,

    I am new to shibboleth2. I did all the steps in your tutorial, but at the end I receive the message “Unable to locate metadata for identity provider” and none of the suggestion found on the official Troubleshooting were good. Also I (think) IdP is working fine because I get “ok” when browsing. Can you please post your shibboleth2.xml config so I can try to detect my problem?

    Thank you

  24. Update: I resolved with the problem above. The issue was that the SP entityID value from the idp-metadata.xml was different from the one entered in the SessionInitiator entityID.

    Now I have another error when I login: “ERROR An error occurred while processing your request. Please contact your helpdesk or user ID office for assistance.This service requires cookies. Please ensure that they are enabled and try your going back to your desired resource and trying to login again.Use of your browser’s back button may cause specific errors that can be resolved by going back to your desired resource and trying to login again.”
    Do you know what this means? Modifying the relayState to relayState=”cookie” didn’t help.

  25. I resolved my problem by making sure that the entityID from the idp-metadata.xml was the same for the SessionInitiator entityID.
    Now I have another problem: when I connect I get a page with the message “ERROR An error occurred while processing your request. Please contact your helpdesk or user ID office for assistance.This service requires cookies. Please ensure that they are enabled and try your going back to your desired resource and trying to login again.Use of your browser’s back button may cause specific errors that can be resolved by going back to your desired resource and trying to login again.”
    Do you know what it means? Modifying relayState to relayState=”cookie” didn’t help.

    Thank you.

  26. Hi,

    nice tutorial. Want to note that the advanced version of such the PHP script cannot be downloaded anymore.


  27. Hi,

    Thanks for the tutorial. I have a question here

    Do we really need a fully qualified hostname for the IdP server (eg: during the installation process? because currently I dont have any domain registered. Can I use an IP?


  28. Hi guys, I’m trying to deploy both IdP and SP on the same Centos 6.3 machine. I followed the guide till the end and I succesfully made the suggested test that returns the “OK” pages. Now the problems I can’t sort out are mainly 2:
    1. When I configure the SP I have to install mod_ssl and then the port 443 conflicts with the same port 443 of tomcat, so I have to disable the tomcat one.
    2. At the end when I try to go to page I get “Unable to locate metadata for identity provider (” :neutral:
    Hope you can help me. Thanks a lot

  29. You can change the tomcat port to any other port in the configuration (see the shibboleth main wiki for installing both IdP & SP on the same machine). You need to provide metadata of both IdP and SP to each other and configure it (the steps are given in the tutorial).

  30. Thanks a lot sohail, I used the AJP connector on port 8009 and ProxyPass from httpd to tomcat and now it works on both ports, 80 and 443.
    But unfortunately the metadata problem persists. That’s what I did:
    1. I copied the idp-metadata.xml from /opt/shibboleth/metadata to /etc/shibbolet
    2. I downloaded the sp-metadata from the link provided in the tutorial and copied it to /opt/shibboleth/metadata with the right certificate string found in sp-cert.pem file.

    If it can be helpful if I go to I read a different error: “Shibboleth handler invoked at an unconfigured location.”
    If I go to Firefox shows me an XML file.

  31. I suddenly discovered that the idp-metadata.xml automatically generated by had a mistake on the !! I changed the entityID from the automatically generated to and now it goes ahead, that’s weird it was automated by the install script. By the way now the error I get is:

    opensaml::FatalProfileException at (
    SAML response contained an error.
    Error from identity provider:
    Status: urn:oasis:names:tc:SAML:2.0:status:Responder
    Sub-Status: urn:oasis:names:tc:SAML:2.0:status:AuthnFailed”

  32. The IdP entityID must be reflected in the configuration files at SP. I think the SP is not recognizing the IdP.

  33. Thanks a lot, I managed my demo to work. The problem was the relying-party.xml file, I had to insert the following attribute either in and tags:

    Now I’m trying to restrict the “/secure” directory access to a single user but with no success, I added a user with uid=john to myLDAP and tried the following:

    AuthType shibboleth
    ShibRequireSession On
    require user john

    And even releasing the uid attribute to SP didn’t help.

  34. Hi again, I’ve discovered that after a succesful authentication with the “require valide-user” setting in shib.conf no Attributes were released to SP (or fetched from?!). Following your tutorial at least cn and sn should be passed. Anyway idp-access.log doesn’t show errors and this i what I get from

    Client Address:
    Identity Provider:
    SSO Protocol: urn:oasis:names:tc:SAML:2.0:protocol
    Authentication Time: 2012-07-25T22:59:21.396Z
    Authentication Context Class: urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
    Authentication Context Decl: (none)
    Session Expiration (barring inactivity): 479 minute(s)


  35. Sohail, Thanks for this amazing article….made my life easy. Now my requirement is that of supporting multiple IDPs for a single SP. So as and when i get more and more customers, I would have to support their IDPs and that too this support need sto be added dynamically. I would not like my serve to stop and make configuration changes and then start my server. So with a single shibboleth.xml file, how can i make dynamic configuration changes in it. WOuld like to know if anyone has any ideas to support this kinda requirement. Thanks

  36. Hi Sohail,

    I followed exact steps as described by you everything is working fine when i am accessing the URL- it is redirecting to the idp login page but when i am trying to login it is saying “Credentials not recognized.” Please Help

  37. What should be used as username???? for authenticating and viewing the resource???

  38. Hi Sohail,

    Thanks for the helpful guide. I am very new to Shibboleth. I was wondering if you could help me with this error that I’m getting.


    The system encountered an error at Mon Apr 1 10:33:38 2013

    To report this problem, please contact the site administrator at root@localhost.

    Please include the following message in any email:

    shibsp::ConfigurationException at (

    Unable to locate a SAML 2.0 ACS endpoint to use for response.


  39. You can add the hostnames to /etc/hostname or your windows “hosts file”.

  40. Hi Shohail,

    Can you explain step by step the configuration for remote user in shibboleth? I want to redirect shibboleth Authenticating to another sso system. I see but I don´t undertand how to do this.
    The sso is working, basically I need settings in shibboleth and as shibboleth redirects the input from the sso and output sso to shibboleth


Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre lang="" line="" escaped="">

Trackbacks and Pingbacks: