InQueueIdPInstall

This page did not make it through the conversion process and is no longer very usable.

Shibboleth Identity Provider Installation

This checklist is intended to help a site perform an initial deployment of a Shibboleth Identity Provider. It presents few choices, and is organized as a cookbook. Very little customization is provided to allow for quick and relatively painless installation to get a working system as quickly as possible. Once this system is operational it is possible to explore configuration options in a stepwise fashion, thus greatly simplifying the process of debugging configuration changes as the deployment moves to production.

It is strongly recommended that you select the radio buttons and fill in the text box in Sections A and B to describe your planned configuration before reading or printing the checklist. The content of the guide will customize itself based on your selections, in order to remove information irrelevant to your situation and to track your choices.

The checklist is divided into four sections; each section addresses a different part of the install process and is disjoint from the others. In addition, most sections conclude with a testing step. Make sure the test works successfully before moving on to the next section. After completing the first three sections, you will have a functioning Shibboleth !IdP component, but it will not be using your local middleware infrastructure. Instead, authentication will be done using Basic Auth (userids and passwords in a local text file), and attribute values will be supplied using the "echo responder" (which generates values on the fly, and does not rely on an attribute repository). Section Four describes the basics of connecting your newly installed !IdP to your local authentication and directory infrastructures.

On completing this checklist, a site will be a member of the InQueue Federation, and will be using a certificate issued by the Bossie CA (believed to live under Eric Norman's desk). This deployment is insecure in several ways and must be modified before moving to production. More detailed information on deployments, particularly for other environments, is available in the Shibboleth Identity Provider deploy guide.

The following installation instructions will work on most Linux, OS X, and Solaris environments. There are special Debian instructions provided by Patrik Schnellmann, Valery Tschopp, and Lukas Haemmerle of SWITCH. Wolfgang Hommel of the Leibniz Supercomputing Center has prepared documentation for installation on SuSE 10.0.

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. If you are running Apache 2, port 8443, which will host a specialized SSL server protecting the attribute query handler, must be available. Under Apache 1.3, port 443 (SSL) must be open.

Bossie will retire

The good news is that I (Eric) can confirm that Bossie does indeed live under my desk.

The bad news is that Bossie will retire by February, 2008.

1. Install and Configure the Pre-requisite Infrastructure

• Deploy surrounding infrastructure:

  • 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 else with a JNDI/JDBC connector will work as well. Custom connectors are available for less standard repositories. A built-in echo responder can be used for test deployments without a data source.

  • A mechanism to authenticate users can be either integrated directly into Tomcat or used to protect a <Location> block in Apache. Without this, Shibboleth can't function even. Basic authentication built into Apache is assumed for this guide.

  • The full DNS name of the server on which Shibboleth will be installed:

The server name will be needed when creating the certificate for the !IdP, and when applying to join the InQueue Federation.

• Install prerequisite components:

  • Choose a web server: 

    

    Apache version 1.3.26+ or Apache version 2

    

    (both with SSL support)

  • Java and servlet container: Java 1.5 must be paired with Tomcat 5.5 and older versions of Java with older versions of Tomcat.

    • Java 1.5 (5.0) and Tomcat 5.5

      

      
      Tomcat 5.5 and Java 1.5 are the officially supported Java servlet container and JDK for running Shibboleth. Unless there are compelling reasons not to, all installations should use this infrastructure.

•  

  •  

    • Java 1.4.2 and

      

      Tomcat 4.1.18+ or Tomcat 5.0.x

      
      If a version of Java and Tomcat must be used other than v1.5/v5.5, v1.4.2/5.0.x are recommended and tested; other versions of the JDK are not supported and may cause errors. Kaffe Java libraries do not work with Shibboleth.

•  

  • JK connector. This is used to pipe requests between Apache and Tomcat; mod_jk2 will be deprecated, but both modules work with all listed infrastructure choices. Use whichever is most convenient.
    

    
    mod_jk or mod_jk2
    

    
    mod_jk has binaries available or may be built from source; an OS X binary is provided courtesy of Walter Hoehn of the University of Memphis.

• Configure Tomcat and the chosen jk connector:

For mod_jk, the following configuration directs Apache to use =mod_jk}} to redirect queries for Shibboleth components to Tomcat. This may be done by including the following text directly in httpd.conf or making a separate file and Include it in httpd.conf .

• Add address="127.0.0.1" to Tomcat's server.xml inside the <Ajp13Connector> configuration element to prevent off-host access.
  

  For Tomcat 5.0.x or older, add =tomcatAuthentication="false"}} to the <Ajp13Connector> configuration element in server.xml to ensure that the user's identity is passed from Apache to the servlet environment.

  
  

  For Tomcat 5.5 or newer, add =request.tomcatAuthentication="false"}} to the <Ajp13Connector> configuration element in server.xml to ensure that the user's identity is passed from Apache to the servlet environment.

  
  

• Tomcat 4.1.x defaults to having the Coyote connector enabled in /conf/server.xml . This fails with mod_jk and must be commented out. Then, uncomment and modify the traditional AJP 1.3 connector as indicated above.

• The AJP13Connector for tomcat is not compatible with the new JMX support. To remove some warnings that will appear in the Tomcat log every time Tomcat is restarted, comment out all of the JMX stuff (anything that says "mbeans") from server.xml.
  

For mod_jk2, the following lines must be added to or placed in a separate configuration file pointed to by httpd.conf :

• mod_jk2 must also be told separately to map URL's to the servlets in Tomcat using /conf/workers2.properties file in the Apache tree (usually =/etc/httpd/conf/workers2.properties=). The simplest approach is to replace the entire contents of the file with the following, which is the simplest configuration that will work.

• By default, the Coyote/JK2 connector will not permit the REMOTE_USER value set by Apache to pass into Tomcat, and thus into Shibboleth. If user authentication will be handled by Apache, then the definition of the Coyote/JK2 AJP 1.3 connector in Tomcat's /conf/server.xml file must be changed as follows to include a request.tomcatAuthentication attribute:

  <!-- Define a Coyote/JK2 AJP 1.3 Connector on port 8009 --> <Connector port="8009" enableLookups="false" redirectPort="8443" debug="0" protocol="AJP/1.3" request.tomcatAuthentication="false" />

• Test that the entire mod_jk2/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.edu_/jsp-examples/ . Success will reveal a bunch of code examples and demonstrates that Tomcat, Apache, mod_ssl, and mod_jk2 are all functional.