InQueueIdPInstall

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 .

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

JkWorkersFile "/usr/local/tomcat/conf/jk/workers.properties"
JkLogFile "/usr/local/apache/logs/mod_jk.log"

JkLogLevel emerg

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

--------- end ---------

• 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 :

--------- begin ---------

<IfModule !mod_jk2.c>
	LoadModule jk2_module libexec/mod_jk2.so
</IfModule>

--------- end ---------

• 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.

----- BEGIN workers2.properties -----

[channel.socket:localhost:8009]
info=Ajp13 forwarding over socket
tomcatId=localhost:8009

[shm:]
info=Scoreboard. Required for reconfiguration and status with multiprocess servers
file=${serverRoot}/logs/jk2.shm

[uri:/shibboleth-idp/*]
info=Shibboleth

[uri:/jsp-examples/*]
info=A set of JSP examples for testing

----- END workers2.properties -----

• 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.

• 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_jk2 and Coyote 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 /usr/local/apache/conf/user.db
	 require valid-user
</Location>

• One or more dummy users must be added to a users file in the Apache tree to test the deployment. These users have UID's in the test Internet2 LDAP server; if another attribute source is used, principal names should correspond to that.

  htpasswd -c /usr/local/apache/conf/user.db Test_User_01
  htpasswd /usr/local/apache/conf/user.db Test_User_02
  

* 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. With Apache 1.3, port 443 (SSL) must be open for inbound requests from Service Providers.
* Firewall Alert: Some institutions and server operating systems firewall ports that are typically used by Shibboleth when installed under Apache 2.0. 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 attibute query handler, must be available.

2. Generate and Use the Required PKI Elements

The Shibboleth !IdP uses PKI in two different ways:

The SSO handler digitally signs the SAML Assertion that it sends to the Service Provider. In Section 3, you will configure Shibboleth's main configuration, idp.xml , to use the PKI elements generated in this section.

The attribute query handler listens behind an SSL-enabled server; currently, Apache + mod_ssl provide part of this SSL functionality and part of the PKI support. In this section, you will configure and test this SSL functionality.

• Generate a Bossie Key/Cert Pair: The following files should be kept in a secure directory, but there is no level of assurance for any certificate issued by Bossie. It must not be used in production.
  • Generate a public/private keypair using !OpenSSL. Sharing these keys with those in a Java keystore is described in detail in the configuration section. The following OpenSSL commands generate a new keypair and a certificate request, assuming 2048 bit RSA keys are to be used:

    	OpenSSL genrsa -out supervillain.key 2048
    	OpenSSL req -new -key supervillain.key -out supervillain.csr
    

    Complete the various DN components when prompted by !OpenSSL. When OpenSSL requests Common Name (eg, YOUR name) , it wants This must match the value input for the CN of the !IdP's certificate in joining InQueue in Section 3.
  • cat out the contents of the signing request:

    		cat supervillain.csr
    

    and paste the resulting block into the web form available for Bossie, a free CA operated by Wisconsin. You get what you pay for. The PIN is 4304538 .
  • Use any text editor(e.g. vi=) to take the resultant certificate from the webpage, including =----BEGIN CERTIFICATE--- and ---END CERTIFICATE---- , and put it in a matching .crt file.

• Configure the SSL Directives for Apache: It is required that the attribute query handler 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 now performed by Shibboleth, but Apache is still required to secure a connection to retrieve and feed the certificate to the !IdP.

For Apache 1.3, within =httpd.conf}} add the following Location block inside the definition of the SSL-protected virtual host.

<Location /shibboleth-idp/AA>
	 SSLVerifyClient optional_no_ca
	 SSLOptions +StdEnvVars +ExportCertData
</Location>

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 and add the following to that vhost configuration:

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/supervillain.crt
	 SSLCertificateKeyFile /etc/httpd/conf/supervillain.key
	 ErrorLog logs/ssl_error_log
	 TransferLog logs/ssl_access_log
</VirtualHost>

• Edit the values of the SSLCertificateFile and SSLCertificateKeyFile directives to refer to the certificate and private key generated in the previous step ("Generate a Bossie Key/Cert Pair").

• Test Apache and mod_ssl

3. Install and Configure the Shibboleth Software

Install Shibboleth:

• Download and expand the Shibboleth Identity Provider package.
• Please read this step carefully to avoid common problems. 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. Use a command like the following:

	 cp /opt/shibboleth-idp-1.3a-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-idp-1.3a-install directory. Apache's Ant tool is to Java what ./make is to C/C++ and is used to build the Shibboleth !IdP. The new build mechanism for Shibboleth 1.3 and later represents a major improvement in simplifying the upgrade process and maintaining the persistence of configuration, now located in a separate directory, during this.

The build script will ask a series of questions. Most are self-explanatory. 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 appropriate permissions to perform these copies.

• Restart Tomcat, which will detect that a new .war file has been added and expand it into a shibboleth-idp directory within /webapps . Most Shibboleth configuration is no longer located in this directory.

• Apply for membership in InQueue. Note the following before completing your application to join InQueue:
  • The CN of the !IdP's certificate will be
  • The URLs for the attribute query handler and the SSO handler should both be prefixed by https:// . If Apache 2 is being used, recall the bug that prevents use of the standard SSL v-host for the attribute query handler; the attribute query handler URL should be port 8443, and take the form =https://gotham.supervillain.edu:8443/shibboleth-idp/AA}} .

When your application is accepted, and the values are confirmed and added to the InQueue Federation metadata, you will receive an email from the federation administrator containing the values for your !IdP site. Note the values in the boxes below:

The EntityDescriptor entityID attribute will be in the main XML element in your confirmation e-mail and will take the form urn:mace:inqueue:supervillain.edu .

Identity Provider Name:

The Attribute query handler <Location> attribute will also be in your confirmation e-mail and will generally take the form https://gotham.supervillain.edu:8443/shibboleth-idp/AA .

Attribute query handler URL:

• Configure idp.xml . This file can be found by default at /usr/local/shibboleth-idp/etc/idp.xml .
  • IdPConfig must be modified as follows.
    • The providerId must be changed to
    • The defaultRelyingParty must be changed to urn:mace:inqueue .
  • Add a FileResolver element pointing to the credentials you generated in Section 2. Remember that paths are relative to, by default, /usr/local/tomcat/webapps/shibboleth/WEB-INF/classes/ , and a file:/// URL must be used to point outside this tree. It must have an id of inqueue_cred and be placed within the Credentials element:

<Credentials xmlns="urn:mace:shibboleth:credentials:1.0">
	<FileResolver Id="inqueue_cred">
		<Key format="PEM">
			<Path>file:///usr/local/apache/conf/supervillain.key</Path>
		</Key>
		<Certificate format="PEM">
			<Path>file:///usr/local/apache/conf/supervillain.crt</Path>
		</Certificate>
	</FileResolver>
</Credentials>

• Increase the level of warning for the ErrorLog and TransactionLog elements to DEBUG . Remember to change this back later or enormously large logs will be generated.

Reboot Apache, start Tomcat, then test and validate your new !IdP:

• Access the InQueue sample SP with any web browser. Success looks like this (with appropriate changes to the attribute values):

Shibboleth Inter-institutional Access Control System

This is an example of a page protected by the Shibboleth system. The
Apache server hosting this page contains the following configuration
block in its httpd.conf file:

<Location /InQueue/sample.jsp>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Location>

Because of the "require valid-user" rule, any user from a trusted
origin-site is allowed access, once they establish a session using
Shibboleth.

Here are some pieces of information I can tell about you using
the information Shibboleth gives me:

shib-origin-site is: urn:mace:inqueue:brown.edu
shib-authentication-method is: urn:oasis:names:tc:SAML:1.0:am:unspecified
shib-ep-affiliation is: *staff@brown.edu;member@brown.edu (mailto:*staff@brown.edu;member@brown.edu)*

The raw SAML attribute assertion I received is below. If it makes sense to
you, seek medical attention immediately.

<textarea wrap="soft" rows="20" cols="60"><Assertion xmlns="urn:oasis:names:tc:SAML:1.0:assertion" AssertionID="b446aa1ac78f9ecc0986fee97cf1871c" IssueInstant="2004-11-16T16:52:15.050Z" Issuer="urn:mace:inqueue:brown.edu" MajorVersion="1" MinorVersion="1" xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><Conditions NotBefore="2004-11-16T16:52:15.049Z" NotOnOrAfter="2004-11-16T17:22:15.049Z"><AudienceRestrictionCondition><Audience>urn:mace:inqueue:example.edu</Audience><Audience>urn:mace:inqueue</Audience></AudienceRestrictionCondition></Conditions><AttributeStatement><Subject><NameIdentifier Format="urn:mace:shibboleth:1.0:nameIdentifier" NameQualifier="urn:mace:inqueue:brown.edu">7576e2a5-7425-4f66-bac8-30d94be947d0</NameIdentifier></Subject><Attribute AttributeName="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri" xmlns:typens="urn:mace:shibboleth:1.0"><AttributeValue Scope="brown.edu" xsi:type="typens:AttributeValueType">staff</AttributeValue><AttributeValue Scope="brown.edu" xsi:type="typens:AttributeValueType">member</AttributeValue></Attribute><Attribute AttributeName="urn:mace:dir:attribute-def:eduPersonPrincipalName" AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri" xmlns:typens="urn:mace:shibboleth:1.0"><AttributeValue Scope="brown.edu" xsi:type="typens:AttributeValueType">stc</AttributeValue></Attribute></AttributeStatement></Assertion></textarea>

4. Use Your Local Authentication System and Attribute Repository

This section describes the steps necessary to customize a Shibboleth !IdP to use a local Authentication system and an Attribute Repository.

• Shibboleth 1.3 doesn't perform authentication on its own. There's a variety of ways external authentication systems can integrate with Shibboleth, but in essence, the SSO handler needs to be protected by an authentication mechanism that can supply REMOTE_USER either through Tomcat or Apache and mod_jk . Detailed instructions are in IdPUserAuthnConfig.
• By default, the Shibboleth Identity Provider is configured to use an Attribute echo responder. At this point, you can configure the new identity provider to use your attribute repository. Detailed information on the connection of many different attribute sources to the Shibboleth !IdP is available in IdPAttributeConfig.

%COMMENT%

• JK2 has been unsupported by the Apache people for some time now, see for example http://tomcat.apache.org/faq/connectors.html#vs -- I'd suggest this page should therefore be less even-handed about jk vs. jk2 for new installations. -- Main.IanYoung - 26 Apr 2006 20:47:10