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_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.
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_jkto redirect queries for Shibboleth components to Tomcat. Include the following text directly in
httpd.confor make a separate file and
- Create a
mod_jkto use at
- Or configure mod_proxy_ajp: if you are using
mod_jk, add to
httpd.confor one of the files it includes
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
tomcatAuthentication="false"for Tomcat 5.0.x and older) to the AJP 1.3 port 8009
address="127.0.0.1"to prevent off-host access as well.
- Test that the entire
mod_jk/Apache/Tomcatassembly 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_jkto Tomcat. For initial testing, use Apache's built-in basic authentication. Add the following to
- One or more dummy users must be added to the referenced
AuthUserFileto test the deployment.
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
ssl.conf on port 8443 by adding the following. If the
SSLCertificateKeyFile referenced don't exist, Apache may fail to start until you point to key and certificate files appropriate for your installation.
- You'll need to return and edit the values of the
SSLCertificateKeyFiledirectives 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
- 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
endorsedfolder to override obsolete classes that Sun includes with their JVM. Tomcat 5.0.x additionally requires that endorsed Xerces libraries packaged with it,
xmlParserAPIs.jar, be deleted first.
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.
shibboleth-1.3.2-installdirectory. 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
- Restart Tomcat, which will detect that a new
.warfile has been added and expand it into a
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.