Setting up Shibboleth Identity Provider on Windows XP (Part 1)

I'm setting up a small Shibboleth Identity Provider to test some ideas. Although I plan to use virtual ubuntu servers eventually, I'm using Windows for now. The official guidance from Internet2 is written for Linux, and is a little terse, so I thought I'd try to document the process carefully in case it helps anyone else (or in case I need to do it again!).

Most of the differences that I've found relate to paths - where things are stored on Windows, and the silly spaces that Microsoft loves in filenames. The jsp-examples path seems to be examples/jsp on my version of Tomcat.

Basic Installation of Apache HTTPD, Tomcat, Java

1. Download the latest Apache2.2 and do a "typical" install, accepting all default options. I used version 2.2.8

2. Download the latest Java SE JDK, and do a "typical" install with default options. I used version jdk-6u5

3. Download the latest Tomcat, and install with all defaults, except install the Examples as well. My version was 6.0.16. I had to supply an administrator password during installation. I noticed that it proposed an HTTP connector at port 8080.

4. Download the mod_jk. (This lets Apache talk to Tomcat.) I selected win32, jk-1.2.26, and then found the "so" file mod_jk-1.2.26-httpd-2.2.4.so. Save or copy this file into C:\Program Files\Apache Software Foundation\Apache2.2\modules

5. Create the file C:\Program Files\Apache Software Foundation\Apache2.2\conf\extra\mod_jk.conf with the following contents. Note that the last two lines show URL pathnames that will be routed to Tomcat.

<Ifmodule !mod_jk.c>
LoadModule jk_module modules/mod_jk.so
</ifmodule>
JkWorkersFile "C:/Program Files/Apache Software Foundation/Tomcat 6.0/conf/workers.properties"
JkLogFile logs/mod_jk.log
JkLogLevel emerg

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

6. Create the file C:\Program Files\Apache Software Foundation\Tomcat 6.0\conf\workers.properties with the following contents:

# Define 1 real worker using ajp13
worker.list=ajp13
# Set properties for the ajp13 workerworker.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

7. Include the new jk_mod.conf into the main conf, by appending the following lines to C:\Program Files\Apache Software Foundation\Apache2.2\conf\httpd.conf :

# Add mod_jk settings for shibboleth IdP
Include conf/extra/mod_jk.conf

8. Test that Apache starts, using the Apache Service Monitor, which is accessible from one of the feather icons in the System Tray (there's one for Apache HTTP server, and one for Tomcat). If there is a typo or some other problem, you'll see a dialog box saying "The requested operation has failed!", with no indication about the error. You can find the error by Start > All Programs > Apache HTTP Server 2.2 > Configure Apache Server > Test Configuration. This will show a command window with any errors -- for about 30 seconds: enough time to work out what the mistake is.

9. Test that your browser can get to the Apache, by navigating to http://localhost/ . You should see "It works!" in the browser. (This file is C:\Program Files\Apache Software Foundation\Apache2.2\htdocs\index.html)

10. Start Tomcat (using the other feather in the system tray).

11. Check that Tomcat is working by browsing http://localhost:8080/ and http://localhost:8080/examples/jsp/ (note that this path is different from that suggested by Internet2's guidance: localhost/jsp-examples/)

12. Check that the mod_jk connector is working by browsing http://localhost/examples/jsp/

13. To be able to browse these from a different machine, you'll need to make sure the Windows Firewall lets through the right connections. In Control Panel, choose Windows Firewall. On the Exceptions tab, you'll need to "Add Port..." to enter HTTP on port 80, and then again for SSL on port 443. On the Advanced tab, look at the ICMP settings, and tick "Allow incoming echo request" (the top option).

Set up SSL

Note: this section describes how you can get a test implementation of SSL running quickly. You would be unwise to rely on these instructions for "production" systems. For reference info about openssl and keytool, I recommend this guide. There's also some guidance from apache.

1. It would be nice to use java's keytool, but I don't think it quite does everything we need, so best to use openssl. You could download and compile it all from there, but the nice people at Shining Light Productions have made an easy to install version. The Win32 OpenSSL Light version is sufficient. Download and install with defaults. It may ask about having to overwrite a couple of files (libssl32.dll and libeay32.dll). I kept backups of the originals, and made the libeay32.dll file not-readonly (right-click, properties) for this to work.

2. Add c:\opensssl\bin to your path. Windows-break (System properties) > Advanced tab > Environment Variables. Double click on Path, and then at the end of the "value" box, add a semicolon (path separator) and c:\openssl\bin.

3. Start a command prompt (Windows-R cmd), and cd C:\Program Files\Apache Software Foundation\Apache2.2\conf.

4. Generate a private key (in server.key) and self-signed certificate (in server.crt) by typing

openssl req -new -x509 -nodes -out server.crt -keyout server.key

You'll need to supply various information about your server's identity. The common name should ideally be your computer's hostname.

5. Open the httpd-ssl.conf file in C:\Program Files\Apache Software Foundation\Apache2.2\conf\extra and check that the SSLCertificateFile and SSLCertificateKeyFile directives point to the files you've just created. Make sure they are uncommented.

SSLCertificateFile "C:/Program Files/Apache Software Foundation/Apache2.2/conf/server.crt"
SSLCertificateKeyFile "C:/Program Files/Apache Software Foundation/Apache2.2/conf/server.key"

6. In the main http.conf file (in C:\Program Files\Apache Software Foundation\Apache2.2\conf), uncomment the "Include conf/extra/httpd-ssl.conf" directive. Restart Apache. If it fails to start, use the Start > All programs > Apache HTTPD Server 2.2 > Configure Apache Server > Test Configuration to debug.

7. Test Apache SSL, by browsing to https://localhost/ (and finding "It works!"). You should find that your browser doesn't accept the certificate by default. With IE, you can view the certificate, and then choose to install it, so that it will be accepted in the future. This takes a few clicks. You will probably find that you can't browse to also be able to browse to https://localhost/examples/jsp/ , because although we've set up Apache SSL, we now need to set up Tomcat SSL.

8. Tomcat Native could use the same key & certificate files that we've already made for Apache, but we haven't installed Tomcat Native. (You might want to do so eventually for performance.) So we'll use the java keytool to make tomcat's keystore. Add C:\Program Files\Java\jdk1.6.0_05\bin to your path environment variable using the details in step 2 above.
9. Close any existing command window, and start another (to inherit the latest Path). Change to the tomcat configuration directory: cd \Program Files\Apache Software Foundation\Tomcat 6.0\conf and then enter the following command

keytool -genkey -alias tomcat -keyalg RSA -keystore keystore.jks

You'll need to enter a password (twice), and the default tomcat one is "changeit". You'll need to enter all the same information as before, although in the opposite order! Instead of First and Last name, I'd suggest using the computer's hostname.

10. Edit tomcat's server.xml configuration file (from C:\Program Files\Apache Software Foundation\Tomcat 6.0\conf). Look for the Connector that uses port 8443, and change it from this:

<Connector port="8443" protocol="HTTP/1.1"
SSLEnabled="true"
maxThreads="150" scheme="https" secure="true" clientAuth="false"
sslProtocol="TLS" />

to this:

<Connector port="8443" protocol="HTTP/1.1"
SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
keystoreFile="conf/keystore.jks"
keystorePass="changeit"
clientAuth="false" sslProtocol="TLS" />

11. Stop tomcat and start it again. (If there are any errors, you should find them in the log file in C:\Program Files\Apache Software Foundation\Tomcat 6.0\logs. Look for the newest "catalina" file.) Try browsing directly to the Tomcat SSL port at https://localhost:8443/examples/jsp/ (you'll probably want to install the certificate again)

12. Finally, we need apache to be able to redirect SSL queries via mod_jk to tomcat. You'll know this works when you can browse to https://localhost/examples/jsp/ . I was stumped for a while, but the underpaid fellow who sits behind me (thanks Dave!) helped to discover that the httpd-ssl.conf file (in C:\Program Files\Apache Software Foundation\Apache2.2\conf\extra) needs to have the two JkMount directives inside the <VirtualHost> block. The end of the block, showing the two new lines in blue looks like this:

JkMount /shibboleth-idp/* ajp13
JkMount /examples/* ajp13
</VirtualHost>

Authentication

1. Modify Tomcat's server.xml (I set all xml files to open with Wordpad by default. At least until I install eclipse!). Tell tomcat that it can rely on authentication provided on this connector, and therefore that it should only accept local connections. Find the line that describes the AJP 1.3 connector

<!-- Define an AJP 1.3 Connector on port 8009
-->
<Connector port="8009" protocol="AJP/1.3"
redirectPort="8443" />

and replace it with

<!-- Define an AJP 1.3 Connector on port 8009
--><Connector port="8009" protocol="AJP/1.3" redirectPort="8443"
request.tomcatAuthentication="false" address="127.0.0.1" />

2. For now, we'll authenticate from a simple file. Later you may want to use LDAP or similar. In a command window, change to the Apache conf directory C:\Program Files\Apache Software Foundation\Apache2.2\conf. Enter the command
..\bin\htpasswd -c user.db myself
You will be asked to invent a password for the user "myself", and to enter it twice. The "-c" option creates the password database. The next time you use that command, omit the "-c", otherwise you'll be deleting any users you've already created. The Shibboleth IdP example script also creates an "alterego" user (for demo purposes).

3. Adjust apache so that it knows to authenticate users before going off to shibboleth. At the very end of the httpd.conf file (in C:\Program Files\Apache Software Foundation\Apache2.2\conf), add these lines:

<Location>
AuthType Basic
AuthName "Villain Verification Service (VVS)"
AuthUserFile conf/user.db
require valid-user
</Location>

4. Restart apache, and then point your browser to http://localhost/shibboleth-idp/SSO . You should find that the system wants to authenticate you. If you make a mistake once or twice, you should get another chance. But entering a correct password should lead to a 404 error from Tomcat noting that the requested resource is not available. If the request gets to tomcat, that's a success.

You're now up to step 3 of the Internet2 instructions for installing the IdP. If you're in a hurry, you'll have to follow those instructions for now. I'll write more here when I can. One final note: the testshib site that they talk about only works if your system is contactable from the internet. If it's behind a corporate firewall, you may not have any luck.