Shibboleth Identity Provider Installation

The basic installation of a Shibboleth Identity Provider into Tomcat and Apache uses mod_jk as a bridge. The steps below will leave you with a fully configured IdP which is ready to test against the federation environment of your choice or TestShib. There are also a few iterative tests that can be performed along the way. Once this system is operational, explore configuration options in a stepwise fashion to simplify debugging as the deployment moves to production.

The instructions will work on most Linux, OS X, and Solaris environments. To simplify the instructions, we presume the following about your installation:

mod_jk (mod_jk2) works, but is deprecated. Apache 2.2.x uses mod_proxy_ajp instead of mod_jk. This is bundled with the Apache distribution, so enable and configure it instead.)
Tomcat 5.5.x (Tomcat 5.0.x and Tomcat 4.1.x work)
Apache 2.0.x with SSL support (Apache 1.3.x and 2.2.x work.) If you don't have SSL installed/configured (e.g.: clean Apache 2.2 installation on Windows) you should enable it.
Java 1.5 (5.0) (1.4+ works, but must be paired with an older Tomcat)

A source of data about users from this IdP must be available for production use. An LDAP directory is recommended, but a relational database or anything with a JNDI/JDBC connector will work as well. A built-in echo responder that always sends the same basic information will be used in this test deployment.

Since Shibboleth 1.3 doesn't authenticate users itself, an authentication mechanism must be either integrated directly into Tomcat or used to protect a <Location> block in Apache. Basic authentication built into Apache is assumed for this guide.

Firewall Alert

Some institutions and server operating systems firewall ports that may be used by Shibboleth. Many operating systems enable this by default, and it can cause certain flows to timeout. Port 8443, which will host a specialized SSL server protecting the attribute query handler, must be publicly accessible.

1. Install and Configure the Pre-requisite Infrastructure

Configure mod_jk: Apache must use mod_jk to redirect queries for Shibboleth components to Tomcat. Include the following text directly in httpd.conf or make a separate file and Include it in httpd.conf .

<IfModule !mod_jk.c>
	LoadModule jk_module libexec/mod_jk.so
</IfModule>

JkWorkersFile /usr/local/tomcat/conf/jk/workers.properties
JkLogFile /var/log/httpd/mod_jk.log

JkLogLevel emerg

JkMount /shibboleth-idp/* ajp13
JkMount /jsp-examples/* ajp13

Create a workers.properties file for mod_jk to use at /usr/local/tomcat/conf/jk/workers.properties :

# Define 1 real worker using ajp13
worker.list=ajp13
# Set properties for the ajp13 worker
worker.ajp13.type=ajp13
worker.ajp13.host=localhost
worker.ajp13.port=8009
worker.ajp13.lbfactor=50
worker.ajp13.cachesize=1
worker.ajp13.cache_timeout=600
worker.ajp13.socket_keepalive=1
worker.ajp13.recycle_timeout=300

Or configure mod_proxy_ajp: if you are using mod_proxy_ajp instead of mod_jk, add to httpd.conf or one of the files it includes

# mod_proxy is a prerequisite to mod_proxy_ajp, required if you did a clean install of Apache 2.2.4
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
ProxyPass /shibboleth-idp/ ajp://localhost:8009/shibboleth-idp/
# this is needed ONLY FOR TESTING, so REMOVE IT after the installation
ProxyPass /jsp-examples/ ajp://127.0.0.1:8009/jsp-examples/

There are several factors to consider when choosing which mechanism to use, the mod_proxy_ajp method is easiest to setup for those with apache 2.2+ but can lack some options. There is a good comparison of the two methods (mod_jk and mod_proxy) posted by one of the tomcat lead developers at http://blogs.jboss.com/blog/mturk/2007/07/16/Comparing_mod_proxy_and_mod_jk.txt

Configure Tomcat: Tomcat must be directed to accept the authentication information coming from Apache. Add request.tomcatAuthentication="false" ( tomcatAuthentication="false" for Tomcat 5.0.x and older) to the AJP 1.3 port 8009 <Connector/> element in /usr/local/tomcat/conf/server.xml . Specify address="127.0.0.1" to prevent off-host access as well.
Test that the entire mod_jk/Apache/Tomcat assembly is functional. First, check that all the components are active: reboot Apache, and start Tomcat using sh /usr/local/tomcat/bin/catalina.sh start . Then, using any web browser, access https://_yourhost.org_/jsp-examples/ . Success will reveal a bunch of code examples and demonstrates that Tomcat, Apache, mod_ssl, and mod_jk are all functional.

Configure Authentication: The SSO handler has to be protected with a location block to trigger some form of authentication using Apache. The user's identity will then be passed through mod_jk to Tomcat. For initial testing, use Apache's built-in basic authentication. Add the following to httpd.conf :

<Location /shibboleth-idp/SSO>
	 AuthType Basic
	 AuthName "Villain Verification Service (VVS)"
	 AuthUserFile /etc/httpd/conf/user.db
	 require valid-user
</Location>

One or more dummy users must be added to the referenced AuthUserFile to test the deployment.

htpasswd -c /etc/httpd/conf/user.db myself
htpasswd /etc/httpd/conf/user.db alterego

2. Configure SSL for the Attribute Authority

There are two ways that the Shibboleth IdP uses keys and certificates. The SSO handler digitally signs the SAML Assertion that it sends to the Service Provider using configuration in idp.xml <Credentials> elements. The attribute query handler connects to the Shibboleth daemon through a mutually authenticated SSL channel. Consequently, Apache and mod_ssl support this part of Shibboleth's PKI. These should almost always be the same key/cert pair.

Configure SSL for the Attribute Authority: The attribute query handler needs to be SSL-protected to enable authentication of attribute requests. These directives tell the Apache server to request a client certificate during the SSL exchange. The actual certificate processing is performed by Shibboleth, but Apache is still required to secure a connection to retrieve and feed the certificate to the IdP.

Unfortunately, Apache 2.0 has a bug related to the declaration of SSL parameters within location blocks. Consequently, define a new SSL vhost in httpd.conf or ssl.conf on port 8443 by adding the following. If the SSLCertificateFile and SSLCertificateKeyFile referenced don't exist, Apache may fail to start until you point to key and certificate files appropriate for your installation.

Listen 8443

<VirtualHost _default_:8443>
	 SSLEngine on
	 SSLProtocol -All +SSLv3 +TLSv1
	 SSLHonorCipherOrder On
	 SSLCipherSuite ECDHE-RSA-AES128-SHA256:AES128-GCM-SHA256:RC4:HIGH:!MD5:!aNULL:!EDH
	 SSLVerifyClient optional_no_ca
	 SSLVerifyDepth 10
	 SSLOptions +StdEnvVars +ExportCertData
	 SSLCertificateFile /etc/httpd/conf/ssl.crt/server.crt
	 SSLCertificateKeyFile /etc/httpd/conf/ssl.key/server.key
	 ErrorLog logs/ssl_error_log
	 TransferLog logs/ssl_access_log
</VirtualHost>

You'll need to return and edit the values of the SSLCertificateFile and SSLCertificateKeyFile directives to refer to the proper key and certificate for your federation or testing service. If you don't, there will be trust errors.

3. Install and Configure the Shibboleth IdP

Install Shibboleth:

Download and expand the Shibboleth Identity Provider package.
All versions of Java and Tomcat run with Shibboleth require that several Java jarfiles used by Shibboleth be located in a special endorsed folder to override obsolete classes that Sun includes with their JVM. Tomcat 5.0.x additionally requires that endorsed Xerces libraries packaged with it, xercesImpl.jar , xml-apis.jar , and xmlParserAPIs.jar , be deleted first.

cp /opt/shibboleth-1.3.2-install/endorsed/*.jar /usr/local/tomcat/common/endorsed

Depending on your Tomcat package and startup scripts, this endorsed directory may be in different locations or not be checked at all. The best way to prevent this is to only use binaries directly from Jakarta and only use the startup scripts provided in the /tomcat/bin folder. Other Java servers may have other locations in which to place these files or deal with this problem. Refer to your application server's documentation to find out how to properly endorse classes, if necessary.

Run ./ant in the shibboleth-1.3.2-install directory. The build script will ask a series of fairly self-explanatory questions. The Tomcat Web Application Manager allows for consolidated management of deployed webapps but is an added layer not necessary for most deployments. By default, the Shibboleth configuration will be deployed to /usr/local/shibboleth-idp/ and the WAR file will be built inside Tomcat at /usr/local/tomcat/. Make sure Ant has permissions to perform these copies. Tomcat must also have write permission for the logging directory, which defaults to /usr/local/shibboleth-idp/logs.
Restart Tomcat, which will detect that a new .war file has been added and expand it into a shibboleth-idp directory within /webapps.

4. Test with your Federation or a Testing Service

At this point, you should have a fully functional IdP, but before it can be tested, you'll need to configure it to interoperate with an SP. Many federations will provide these for their community, and the completely insecure TestShib is available for anyone to test with.