Installing Shibboleth 1.3c on SuSE Linux 10.0


Document version 0.2b - last change: June 14th, 2006

Wolfgang Hommel
Leibniz Supercomputing Center, Munich, Germany
Contact e-mail address: hommel [at] lrz [dot] de


Overview

This document describes how to set up basic Shibboleth 1.3c identity and service providers on SuSE Linux 10.0 and test them by joining the InQueue federation. It complements the official Shibboleth wiki installation guides and focusses on leveraging SuSE 10.0 packages to spare busy administrators the hassle of installing and configuring components such as Apache 2 and Tomcat 5 from scratch. Your mileage with different Shibboleth versions or Linux distributions may vary.

Several parts of this howto are based on German Shibboleth installation guidelines written by the University of Freiburg, Germany, for the German AAR federation. I owe them my gratitude for saving me a lot of frustration during the sometimes tricky Shibboleth deployment.

If you run into any troubles not covered in this document, you may want to use the search function of the Shibboleth mailing list archives; the community support given for Shibboleth is excellent.

Any feedback helping me to improve this howto will be greatly appreciated.

Content

Shibboleth 1.3c Identity Provider installation on SuSE Linux 10.0
Shibboleth 1.3c Service Provider installation on SuSE Linux 10.0

Conventions

Shibboleth 1.3c Identity Provider installation on SuSE Linux 10.0

Goal

Install the Shibboleth 1.3c Identity Provider software on a SuSE Linux 10.0 machine and join the InQueue federation for testing.

Preparation

I recommend to use a dedicated testing machine with a fresh installation of SuSE 10.0; for joining InQueue, it is required that this machine will have a public IP address and can be contacted via the internet. Details on which ports must be accessible are provided below, so firewalls should be configured accordingly.

Installation

Step 1

Set up SuSE 10.0 as usual; make sure to also install the following SuSE 10.0 packages:
Please note that if you are also using the installation instructions on the Shibboleth wiki, the configuration "Java 1.4.2 + Tomcat 5.0.x" must be selected.

Step 2

Step 3

Enable SSL for Apache2 with a test certificate by following the instructions in /usr/share/doc/packages/apache2/README.QUICKSTART.SSL .

Step 4

Restart Apache2 (rcapache2 restart) and test whether Apache2 and Tomcat5 have been installed correctly by pointing a web browser to
SuSE's pre-configuration should work out of the box; if it doesn't, here's a list of the relevant configuration files:

Step 5

Edit /etc/apache2/conf.d/jk.conf to add the following lines:
        JkMount /shibboleth             ajp13
        JkMount /shibboleth/*           ajp13
        JkMount /shibboleth-idp/*       ajp13
Place them within the <IfModule mod_jk.c> ... </IfModule> block, e.g. next to the other JkMount commands for the JSP-examples.

Step 6

Shibboleth ships with various updated Java classes (.jar files) which use the Java endorsement mechanism to override the older versions. SuSE's Tomcat5 start script must be modified so it finds them (we will install them in step 8).
Edit the file /usr/share/tomcat5/bin/catalina.sh and add the following line - I've inserted it as line number 182 in catalina.sh:
JAVA_ENDORSED_DIRS=/usr/share/tomcat5/common/endorsed

Step 7

Download shibboleth-idp-1.3c.tar.gz from http://shibboleth.internet2.edu/downloads/ and unpack it in /opt, so you get the archive's content into /opt/shibboleth-idp-13c-install/.

Step 8

Delete the endorsed Java classes which are shipped with SuSE's Tomcat5 and copy Shibboleth's replacement files into the directory specified in step 6:

Step 9

Run the Shibboleth IDP installation script by executing ./ant in the /opt/shibboleth-idp-13c-install directory. Please note that you must execute the script file "ant" in this directory (hence ./ant) and not run the "ant" command itself.
You will be asked several questions and should accept the defaults for the first three of them. Then,

Step 10

If step 9 completed successfully, you should have a shibboleth.war file in /srv/www/tomcat5/base/webapps . When you restart Tomcat5 the next time, this .war file must be unpacked. SuSE's Tomcat5 is already pre-configured to unpack .war files; however, the permissions in the web-apps directory must be set appropriately:
Restart Tomcat5 now (rctomcat5 restart); it will take some time until Tomcat5 is fully loaded and started (check /var/log/tomcat5/base/catalina.out and wait for a message "Server startup in xxxx ms").

Verify that the war file has been unpacked: A directory /srv/www/tomcat5/base/webapps/shibboleth-idp should have been created.
You should delete /srv/www/tomcat5/base/webapps/shibboleth.war now.

Step 11

In order to join the InQueue federation, you'll need to acquire a Bossie certificate. To do so, follow chapter 2 ("Generate and Use the Required PKI Elements") of the official Shibboleth IDP installation guide in the Shibboleth wiki. It will guide you through
Place your private key, the generated certificate and the CA certificate into a directory of your choice and adjust the following lines in /etc/apache2/vhosts.d/vhost-ssl.conf:
Run the "SuSEconfig" command and restart Apache2 (SuSEconfig ; rcapache2 restart). Verify that it starts without error and check whether it's using the new certificate by browsing https://myidp.example.com/.

Step 12

Finally, we are ready to do some Shibboleth-specific configuration of the installed components.
First, edit /etc/tomcat5/base/server.xml and turn off Tomcat's authentication for its connectors, by adding 
	tomcatAuthentication="false"
to all <Connector ... /> tags. You will have two of them (for ports 8009 and 8080). In my case, they now look as follows:
<Connector port="8080"
            maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
            enableLookups="false" redirectPort="8443" acceptCount="100"
            debug="0" connectionTimeout="20000"
            disableUploadTimeout="true" tomcatAuthentication="false" />
<Connector port="8009"
            enableLookups="false" redirectPort="8443" debug="0"
            protocol="AJP/1.3" tomcatAuthentication="false" />

Step 13

We are going to use Tomcat's built-in authentication mechanisms in this installation. Edit /etc/tomcat5/base/server.xml and add the following Context block within the <Server><Service><Engine><Host>...</Host></Engine></Service></Server> block:
 <Context path="/shibboleth-idp" 
	docBase="/srv/www/tomcat5/base/webapps/shibboleth-idp" 
	debug="99" reloadable="true">
         <Logger className="org.apache.catalina.logger.FileLogger" 
	prefix="localhost-shibboleth-idp-" 
	suffix=".log" timestamp="true"/>
         <Realm className="org.apache.catalina.realm.MemoryRealm" debug="0"
	pathname="conf/tomcat-users.xml"/>
 </Context>
To add a test user, edit /etc/tomcat5/base/tomcat-users.xml and add the following lines within the <tomcat-users>...</tomcat-users> block:
 <role rolename="demo"/> 
 <user username="user1" password="secret1" roles="demo"/>
Other Tomcat5 realms can be used for authentication, e.g. using LDAP servers or relational databases. However, this is outside the scope of this howto, but detailed documentation on this topic exists (see, for example, the realm howto, which is part of the Tomcat5 documentation).

Step 14

Edit Apache2's /etc/apache2/vhosts.d/vhost-ssl.conf file and add the following lines within the <IfDefine ...><IfDefine ...> ... </IfDefine></IfDefine> block:
Listen 8443
<VirtualHost _default_:8443>
    SSLEngine on
    SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
    SSLVerifyClient optional_no_ca
    SSLVerifyDepth 10
    SSLOptions +StdEnvVars +ExportCertData
    SSLCACertificateFile  /etc/apache2/shibcert/ca.crt
    SSLCertificateFile    /etc/apache2/shibcert/supervillain.crt
    SSLCertificateKeyFile /etc/apache2/shibcert/supervillain.key
    ErrorLog     /var/log/apache2/ssl_8443_error_log
    TransferLog  /var/log/apache2/ssl_8443_access_log
    ServerName      myidp.example.com
    ServerAdmin     you@example.com
    DocumentRoot    /srv/www/tomcat5/base/webapps
    <Location /shibboleth/AA>
            SSLOptions      +StdEnvVars +ExportCertData
    </Location>
</VirtualHost>
Be aware that you may have to change your firewall's settings to allow connections on port 8443. According to the official Shibboleth installation guidelines, this second port is required due to a bug in Apache2 concerning SSL parameters within <Location> blocks.

Step 15

Step 16

Edit /srv/www/tomcat5/base/webapps/shibboleth-idp/WEB-INF/web.xml. Basically, you have to add the following lines within the <web-app>...</web-app> block:
<security-constraint>
  <web-resource-collection>
    <web-resource-name>SSO servlet</web-resource-name>
    <url-pattern>/SSO</url-pattern>
  </web-resource-collection>
  <auth-constraint>
    <role-name>*</role-name>
  </auth-constraint>
</security-constraint>
<login-config>
  <auth-method>FORM</auth-method>
  <realm-name>Shibboleth form-based authentication</realm-name>
  <form-login-config>
    <form-login-page>/login.jsp</form-login-page>
    <form-error-page>/login-error.jsp</form-error-page>
  </form-login-config>
</login-config>
For details, you may want to have a look at the "Java-based User Authentication" section in https://authdev.it.ohio-state.edu/twiki/bin/view/Shibboleth/IdPUserAuthnConfig.

Step 17

Edit /opt/shibboleth-idp-13c/etc/idp.xml as follows:

Step 18

Now it's time to restart Apache2 and Tomcat5 (rcapache2 restart; rctomcat5 restart). Make sure you wait long enough until Tomcat5 has successfully started (see step 10 about checking Tomcat5's log files for this).

To test your setup, browse the InQueue sample Service Provider at https://wayf.internet2.edu/InQueue/sample.jsp:
Good luck for debugging if it doesn't work. :-) I'd really appreciate feedback about configuration steps missing in this howto.

Step 19

You've successfully completed the basic IDP setup. Your next steps most likely include

Shibboleth 1.3c Service Provider installation on SuSE Linux 10.0

Goal

Install the Shibboleth 1.3c Service Provider software on a SuSE Linux 10.0 machine and join the InQueue federation for testing.

Additional conventions

Preparation

I recommend to use a dedicated testing machine with a fresh installation of SuSE 10.0; for joining InQueue, it is required that this machine will have a public IP address and can be contacted via the internet.

Installation

Step 1

Set up SuSE 10.0 as usual; make sure to also install the following SuSE 10.0 packages:

Step 2

Step 3

Enable SSL for Apache2 with a test certificate by following the instructions in /usr/share/doc/packages/apache2/README.QUICKSTART.SSL .

Step 4

Restart Apache2 (rcapache2 restart) and test whether Apache2 has been installed correctly by pointing a web browser to
SuSE's pre-configuration should work out of the box; if it doesn't, here's a list of the relevant configuration files:

Note:
As an alternative to steps 5-9 below, you can install the required libraries and software from source RPMs (SRPMs) as described in
https://authdev.it.ohio-state.edu/twiki/bin/view/Shibboleth/SPBuildRPMs
Building from SRPMs is the officially preferred way, although I found it a bit more cumbersome. If you go for SRPM building, you will have to
  • edit OpenSAML's spec file to remove a samltest-specific line as mentioned on the above web site.
  • edit Shibboleth-SP's spec file to change the "httpd-devel" dependency into "apache2-devel".
    		•

    Step 5

    Install the log4cpp library:

    Step 6

    Install Xerces-C++:

    Step 7

    Install XML-Security C++:

    Step 8

    Install OpenSAML:

    Step 9

    Install the Shibboleth Service Provider:

    Step 10

    Edit /etc/apache2/httpd.conf and add the following line at its end:

    Step 11

    Edit SuSE's apache2 start script (/etc/init.d/apache2) so it automatically starts and stops the Shibboleth demon (shibd):
    ...
    #
    # main part
    #
    case "$action" in
        start*)
            if [ -e $pidfile ]; then
    ...
            fi
            echo "Starting shibd..."
            /opt/shibboleth-1.3/sbin/shibd -fc /opt/shibboleth-1.3/etc/shibboleth/shibboleth.xml &
            echo -n "Starting httpd2 (${APACHE_MPM:-${apache_bin#*-}}) "
            cmdline=$(echo $apache_bin -f $httpd_conf $server_flags "$@")
    ...
        stop)
            echo "Stopping shibd..."
            killall shibd
            echo -n "Shutting down httpd2 "
            if [ ! -f $pidfile -a -f $pidfile.rpmsave ]; then mv $pidfile.rpmsave $pidfile; fi
    ...

    Step 12

    In order to join the InQueue federation, you'll need to acquire a Bossie certificate. To do so, follow the section "obtain a Bossie test certificate" in the official Shibboleth SP installation guide in the Shibboleth wiki. It will guide you through
    Place your private key, the generated certificate and the CA certificate into a directory of your choice and adjust the following lines in /etc/apache2/vhosts.d/vhost-ssl.conf:
    Run the "SuSEconfig" command and restart Apache2 (SuSEconfig ; rcapache2 restart). Verify that it starts without error and check whether it's using the new certificate by browsing https://mysp.example.com/.

    Step 13

    Sign up for InQueue as described in the "Join InQueue" part of the official installation documentation:
    Wait for a confirmation e-mail (you will receive an automatically generated e-mail after filling out the form, and the confirmation e-mail a little bit later).
    Download IQ-metadata.xml from the link given in this e-mail and place the file into /opt/shibboleth-1.3/etc/shibboleth/.

    Step 14

    Edit /etc/sysconfig/apache2 and adjust the following settings:

    Run "SuSEconfig" to activate these changes.

    Step 15

    In /opt/shibboleth-1.3/etc/shibboleth/apache2.config, there is an example configuration on how to Shibboleth-protect access to http(s)://mysp.example.com/secure:
    <Location /secure>
      AuthType shibboleth
      ShibRequireSession On
      require valid-user
    </Location>
    Create the directory /srv/www/htdocs/secure and put a simple index.html file into it (mkdir /srv/www/htdocs/secure; date > /srv/www/htdocs/secure/index.html).

    Step 16

    Edit /opt/shibboleth-1.3/etc/shibboleth/shibboleth.xml:

    Step 17

    Now it's time to test your installation:
    Good luck for debugging if it doesn't work. :-) I'd really appreciate feedback about configuration steps missing in this howto.

    Step 18

    You've successfully completed the basic SP setup. Your next steps most likely include
    Impressum, a2822bj