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_proxy_ajp instead of mod_jk. This is bundled with the Apache distribution, so enable and configure it instead.)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. |
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 |
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 |
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
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.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.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> |
AuthUserFile to test the deployment.htpasswd -c /etc/httpd/conf/user.db myself htpasswd /etc/httpd/conf/user.db alterego |
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.
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> |
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.Install Shibboleth:
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.
./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..war file has been added and expand it into a shibboleth-idp directory within /webapps.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.