You are here

IdP with Shibboleth 2.4.4 on Ubuntu Linux (from version 10.04)


0. Foreword

1. Install Apache, Java JDK and Tomcat

2. Install Shibboleth's IdP software

3. Apache2 setup

4. Tomcat setup

5. Federation metadata

6. Shibboleth IdP setup

7. Certificates

8. WAR file

9. Restart Tomcat

10. Troubleshooting

0. Foreword

We suppose that you're using a server version of a recent LTS version of Ubuntu Linux (based on 10.04 LTS for this document). Also, all the commands need to be entered with root permission, so it is probably a good idea to start in your terminal with :

sudo su

update (27/10/2015): In this document, the referenced version was Shibboleth 2.3.6; you may freely replace it by v. 2.4.4, it will works flawlessly.

1. Install Apache, Java JDK and Tomcat

1.1. Apache

apt-get install apache2
You need to enable 2 Apache modules, ssl and proxy_ajp : a2enmod ssl a2enmod proxy_ajp

1.2. Java JDK

apt-get install openjava-6-jdk
You may use the Java implementation of your choice. Don't forget to change the default one to use with the following command : update-altenative --config java

1.3. Tomcat

sudo apt-get install tomcat6
You should change the default setting in /etc/default/tomcat6: JAVA_OPTS="${JAVA_OPTS} -XX:+UseConcMarkSweepGC -Xmx512m" This will allow Tomcat to use up to 512 MB of memory. You are encouraged to set it higher, according to the amount of memory available on the server.

2. Install Shibboleth's IdP software

You need to download the IdP Shibboleth package from the official Shibboleth website at following URL :
Next, you need to unzip the archive and install the software :

unzip cd shibboleth-identityprovider-2.3.6 JAVA_HOME=/usr/lib/jvm/java-6-openjdk ./

The install script is an interactive, text based script. The default location can be accepted (/opt/shibboleth-idp/). The directory will be known as $IDP_HOME.

Select an appropriate hostname for this installation, will be a good choice. The password for the key chain is mandatory and non-blank, but we will not use the keystore anyway, so it doesn't really matter.

Don't forget to add a record for your server in your DNS.

After the script is run, change ownership for the directory and its content : chown -R tomcat6:tomcat6 /opt/shibboleth-idp
Copy some Java classes/libraries to correct locations : cp -R endorsed /usr/share/tomcat6/

3. Apache2 setup

You need to create a configuration file for your IdP server. You may take following as a basis for your config to be placed in /etc/apache2/sites-available/idp.conf ################################################ # # Please leave the port numbers in the 'ServerName' statements. # It's important as there will be different certificates for both ports. # # 443 is the regular https port and will be user-facing. This has to be an official # certificate, typically one from the Belnet DCS service. # # 8443 is only used for SAML communications between SP and IdP. # It has to use the certificate published in the metadata. # In principle, a self-signed certificate is good to use here. # # If 443 is not yet enabled in the Apache config, you can enable it here: # # Listen 443 <VirtualHost *:443> ServerName ErrorLog /var/log/apache2/ssl_error_log ErrorLog /var/log/apache2/error.log # Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. LogLevel warn CustomLog /var/log/apache2/ssl_access.log combined # # SSL # # Please change the certificate below. It has to be an 'official' certificate, # like one from the Belnet DCS service. # For testing purposes you can use the IdP certicate, generated by the install script. # SSLEngine on SSLCertificateFile /etc/ssl/certs/ SSLCertificateKeyFile /etc/ssl/private/ SSLCertificateChainFile /etc/ssl/certs/comodo-chain.pem # # All request coming to /idp/ will proxied to Tomcat using AJP: # <Proxy ajp://localhost:8009/idp/*> Allow from all </Proxy> ProxyPass /idp/ ajp://localhost:8009/idp/ </VirtualHost> ################################################ # # ArtifactResolutionService and AttributeService # # Only SAML service providers will contact this service. # No client (web browser) will connect to port 8443 # Make sure it's open on your firewall! # # # # Listen 8443 <VirtualHost *:8443> ServerName SSLEngine on SSLCertificateFile /etc/ssl/certs/idp.pem SSLCertificateKeyFile /etc/ssl/private/idp.key # # Certificate chain is not needed here. # The certificate will be verified using the metadata, and it is a self signed certificate anyway. # SSLVerifyClient optional_no_ca SSLVerifyDepth 10 SSLOptions +StdEnvVars +ExportCertData <Proxy ajp://localhost:8009/idp/*> Allow from all </Proxy> ProxyPass /idp/ ajp://localhost:8009/idp/ </VirtualHost>

Enable this configuration in Apache :
a2ensite idp /etc/init.d/apache2 restart

If you try to access the URL :, you will get a Service Unavailable error message. That's normal because we still need have to configure Tomcat and IdP self first...

4. Tomcat setup

The Tomcat configuration resides in /etc/tomcat6/.
Find and change the AJP connector configuration for port 8009:
<Server port="8005" shutdown="SHUTDOWN"> <!-- Define the Tomcat Stand-Alone Service --> <Service name="Catalina"> >!-- Define an AJP 1.3 Connector on port 8009 --< <Connector port="8009" address="" enableLookups="false" redirectPort="8443" protocol="AJP/1.3" /> </Service> </Server>
Now create the file /etc/tomcat6/Catalina/localhost/idp.xml and add the following content: <Context docBase="/opt/shibboleth-idp/war/idp.war" privileged="true" antiResourceLocking="false" antiJARLocking="false" unpackWAR="false" swallowOutput="true" />

And restart Tomcat: /etc/init.d/tomcat6 restart If you retry the url you will get a plain and simple 'ok' meansing your Tomcat is configured correctly.

5. Federation metadata

We distinguish between IdP metadata and federation metadata. The federation metadata is managed by Belnet and it is in fact a collection of all individual IdP and SP metadata. If you have signed the Belnet R&E Federation agreement, you will be able to submit your IdP metadata to Belnet.

The IdP metadata has been generated automatically by the setup script during the Shibboleth installation phase and is at /opt/shibboleth-idp/metadata/idp-metadata.xml.
Before doing anything else, you should manually add some information to this file. If you don't add it, your metadata will not be accepted by the Belnet Metadata Manager system.

Please add following XML tags at the end of the file, before the closing </EntityDescriptor> tag :

<Organization> <OrganizationName xml:lang="en" xmlns:xml=""> Your Institution's name </OrganizationName> <OrganizationDisplayName xml:lang="en" xmlns:xml=""> Your Institution's display name </OrganizationDisplayName> <OrganizationURL xml:lang="en" xmlns:xml=""> http://www. </OrganizationURL> </Organization> <ContactPerson contactType="technical"> <GivenName>Technical Support</GivenName> <SurName>Technical Support</SurName> <EmailAddress></EmailAddress> </ContactPerson>

The display name will be used by the Discovery Service (aka DS or previously WAYF). Make sure your users will recognize the display name, because that's what they will see when making the selection!

Now you're ready to submit your metadata to You'll still have to add the global federation metadata to your IdP. This will be handled in the next section.

6. Shibboleth Identity Provider setup

The Shibboleth IdP configuration resides in /opt/shibboleth-idp/conf/.


6.1. relying-party.xml

First, we will make your IdP aware of the federation metadata. You will have to uncomment and edit this part:

<metadata:MetadataProvider id="URLMD" xsi:type="metadata:FileBackedHTTPMetadataProvider" metadataURL="" backingFile="/opt/shibboleth-idp/metadata/belnet-federation-metadata.xml"> <metadata:MetadataFilter xsi:type="metadata:ChainingFilter"> <metadata:MetadataFilter xsi:type="metadata:RequiredValidUntil" maxValidityInterval="P9D" /> <metadata:MetadataFilter xsi:type="metadata:SignatureValidation" trustEngineRef="shibboleth.MetadataTrustEngine" requireSignedMetadata="true" /> <metadata:MetadataFilter xsi:type="metadata:EntityRoleWhiteList"> <metadata:RetainedRole>samlmd:SPSSODescriptor</metadata:RetainedRole></metadata:MetadataFilter> </metadata:MetadataFilter> </metadata:MetadataProvider>

The federation metadata is signed, so you can detect any forgery by a 3rd party. Also, the federation metadata has a validity of 7 days, so to make your IdP work properly, you need to put maxValidityInterval to a higher vale (here it is set to 9 days which is OK). In order to enable signature verification, also uncomment and change the following part in relying-party.xml:

<!-- Trust engine used to evaluate the signature on loaded metadata. --> <security:TrustEngine id="shibboleth.MetadataTrustEngine" xsi:type="security:StaticExplicitKeySignature"> <security:Credential id="MyFederation1Credentials" xsi:type="security:X509Filesystem"> <security:Certificate>/opt/shibboleth-idp/credentials/</security:Certificate> </security:Credential> </security:TrustEngine>

You will have to download the certificate into /opt/shibboleth-idp/credentials/. The certificate is available here:

You need to verify to mention the self signed certificate+key generated during the setup phase in the following section :

<security:Credential id="IdPCredential" xsi:type="security:X509Filesystem"> <security:PrivateKey>/opt/shibboleth-idp/credentials/idp.key</security:PrivateKey> <security:Certificate>/opt/shibboleth-idp/credentials/idp.pem</security:Certificate> </security:Credential>

In another file, handler.xml, you will have to configure the authentication method for your institution's users. You will probably want to use the Username/Password method. It is documented at and you may read next section for some details.


6.2. handler.xml

At the very end of the file, you will need to uncomment and edit the following section : <!-- Username/password login handler --> <ph:LoginHandler xsi:type="ph:UsernamePassword" jaasConfigurationLocation="file:///opt/shibboleth-idp/conf/login.config"> <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</ph:AuthenticationMethod> </ph:LoginHandler> <!-- Removal of this login handler will disable SSO support, that is it will require the user to authenticate on every request. --> <ph:LoginHandler xsi:type="ph:PreviousSession"> <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession> </ph:LoginHandler>

This enable the Java Authentication and Authorisation System ~JAAS).


6.3. login.config

As you have noticed in the previous file, we need that file for the handler to work, so let's edit it : ShibUserPassAuth { // Example LDAP authentication // See: edu.vt.middleware.ldap.jaas.LdapLoginModule required ldapUrl="ldap://" baseDn="dc=yourdomain,dc=be" bindDn="cn=idp,dc=yourdomain,dc=be" bindCredential="password" ssl="false" userFilter="uid={0}" subtreeSearch="true"; };

This section let's enable the LDAP login module on which the username/password's JAAS method is based on. You will need to modify all the fields with the ones corresponding to your situation (ldapUrl points to your LDAP server, the various bind are all the credentials needed to access you LDAP...)


6.5. attribute-resolver.xml

This file is used to access the data source for the attributes. You should uncomment all the schemas sections ( <!-- Schema: Core schema attributes-->, <!-- Schema: inetOrgPerson attributes--> and <!-- Schema: eduPerson attributes -->) as many of the attributes can be used, especially in the eduPerson schema).

At the very end of the file, you need to create a data connector linked with the source of your data; here is an example for a LDAP connector :

<!-- Example LDAP Connector --> <resolver:DataConnector xsi:type="LDAPDirectory" xmlns="urn:mace:shibboleth:2.0:resolver:dc" id="myLDAP" ldapURL="ldap://" baseDN="dc=your-domain,dc=be" principal="cn=idp,dc=your-domain,dc=be" principalCredential="password" searchScope="SUBTREE" > <FilterTemplate> <![CDATA[ (uid=$requestContext.principalName) ]]> </FilterTemplate> </resolver:DataConnector>


6.6. attribute-filter.xml

This file is used to configure the attributes you want to present to the SP where your users will connect to. It is called a policy. Find below an example of a release to all rule used to present by default some attributes to the connecting SP :

<!--Release to all SP--> <AttributeFilterPolicy id="releaseToAll"> <PolicyRequirementRule xsi:type="basic:ANY" /> <AttributeRule attributeID="eduPersonPrincipalName"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="uid"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="commonName"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="organizationalUnit"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="email"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="eduPersonNickname"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="eduPersonOrgDN"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="eduPersonPrimaryAffiliation"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="organizationName"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="preferredLanguage"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="eduPersonEntitlement"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="surname"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> <AttributeRule attributeID="givenName"> <PermitValueRule xsi:type="basic:ANY" /> </AttributeRule> </AttributeFilterPolicy>


6.7. logging.xml

The file is used to setup the logging process of the Shibboleth system. To start the system, it is better to modify all the settings to the DEBUG value to get the most informations needed to troubleshoot the problems. Later on, you could adapt it to your own desires of info levels.


6.8. Set permissions to directories

In order to make Tomcat work properly, it will need to have some write permissions to some directories (like /opt/shibboleth-idp/logging/, /opt/shibboleth-idp/metadata/). The easiest way to do it, is to change the owner of the Shibboleth directory to the Unix user tomcat6 :

chown -R tomcat6:tomcat6 /opt/shibboleth-idp

7. Certificates

A federated trust system uses public key cryptography to achieve authentication and encryption of the various exchanged messages between all the entities in the system.

Your IdP will use 3 different certificates :

  1. a self-signed one, used to secure the communication between the attributes resolver and the authentication system itself;
  2. a public one, used to offer the HTTPS web interface to the users that will authenticate;
  3. the certificate used by Belnet to sign the Metadata file.

The first one is generated during the installation phase of the Shibboleth IdP software and is located in /opt/shibboleth-idp/credentials/idp.{key,crt}

The second one needs to be obtained from a public certificate authority (CA). You may use the Digital Certificate Service (DCS) of Belnet to get it from Comodo (it is free! :-) ), or from any other available CA available on the Internet (not free ! :-( ). The certificate will be located in /etc/ssl/certs/your-certificate.crt and /etc/ssl/private/your-certificate.key. You will also put the keychain file obtained from your CA in /etc/ssl/certs/your-CA-keychain-file.crt.

The third one needs to be downloaded from and installed in /etc/ssl/certs/

8. WAR file

This file contains the web interface and the Java/Javascript needed to interact with the IdP. It is in fact a Java archive (~a zip archive file). You will need to edit the content of this file to customize the interface, adapted to your institution needs. To modify it, simply use the following command to get the files :

jar xvf /opt/shibboleth-idp/war/idp.war

Then, edit the login.jsp, login.css add images files, whatever, and regenerate the WAR file :

jar cvfm /opt/shibboleth-idp/war/idp.war t -C thedirectory/ .

9. Restart Tomcat

To start you Identity Provider, you need to restart Tomcat :

/etc/init.d/tomcat6 restart

10. Troubleshooting

The first thing to look at are the Shibboleth logs files (/opt/shibboleth-idp/logs/idp-process.log); you will find a lot of informations over the error.