How to set up Project Liberty (IPL) under AOLserver
Prerequisites:
These are the versions that were testing. Later versions may work as well.
- AOLserver 4.0.7 [1]
- nsjk2 2.02b [2]
- IPL 0.1 [3]
- ant 1.6.0 [4]
- Tomcat 5.0.19 [5]
- Apache XML Security 1.1.0 [6]
- Log4J 1.2.8 [7]
- Axis 1.1 [8]
- JavaMail 1.3.1 [9]
- JAXM 1.1.2 [10]
- IPL Sample data [11]
- IPL schema [12]
- Netscape Directory Server 6.21 [13]
- openSSL 0.9.7 [14]
Instructions:
We have a lot of packages to download, build and install. Lets start with the web server and go from there. The assumption is that this is going to be installed in /home/joe/liberty.
Step 1. Build and install Tcl and AOLserver.
You can use a binary distribution of Tcl provided it is a threaded build of Tcl.
Building both Tcl and AOLserver is outside the scope of this document and should be covered in a separate document.
I did:
$ cd /home/joe/liberty $ tar xzvf tcl8.4.3-src.tar.gz $ cd tcl8.4.3/unix $ ./configure --prefix=/home/joe/liberty/aolserver --enable-threads $ make $ make install
$ cd /home/joe/liberty $ tar xzvf aolserver-4.0.7-src.tar.gz $ cd aolserver-4.0.7 $ ./configure --with-tcl=/home/joe/liberty/aolserver/lib --prefix=/home/joe/liberty/aolserver $ make $ make install
The assumption is that AOLserver will be installed into /home/joe/liberty/aolserver.
Step 2. Unpack and install Tomcat.
You just need to untar the distribution into /home/joe/liberty and set CATALINA_HOME to /home/joe/liberty/jakarta-tomcat-5.0.19 or wherever you installed it. The nsjk2 connector is known to work with this version of Tomcat and it is strongly recommended. There are known problems with 5.0.27.
Step 3. Build and install Ant.
Ant is used to install IPL and nsjk2 (the AOLserver Java connector). If you don't already have Ant installed, download it and do this:
$ cd /home/joe/liberty $ bzip -dc ant-apache-1.6.0-bin.tar.gz2 | tar xf - $ cd apache-ant-1.6.0 $ export ANT_HOME=`pwd` $ export PATH=$PATH:$ANT_HOME/bin
Step 4. Build and install nsjk2.
There are very good installation instructions included in the nsjk2 package. Follow those to install nsjk2 into AOLserver/Tomcat. Don't forget to set JAVA_HOME before installing.
Checkpoint
Now would be a good time to startup AOLserver/tomcat at this point and verify that Java is working properly before continuing.
To do this, start AOLserver and use a browser to hit the sample servlets page.
$ cd /home/joe/liberty/aolserver $ bin/start-java
Wait until a message like: INFO: JK2: Initialized apr. AOLserver itself will listen for requests before Tomcat has finished initializing completely. This can result in 500 errors if you request a servlet before it is ready.
In a browser go to http://hostname:8000/servlets-examples/ and run a few of the tests.
To quit AOLserver press ^C in the shell window.
Step 5. Build and install IPL.
The IPL build process uses an external package, xml-security. It is designed to build against the Sun Java Web package JWSDP which contains a lot of the other external packages needed. To reduce the number of changes to the build process we'll just put all external jars into xml-security/libs for building purposes. This is the lazy way out. You can also refer to the README.txt file found in the docs directory of the IPL distribution for more information on building and deploying IPL.
$ cd /home/joe/liberty $ unzip ipl-0.1.zip $ mkdir -p xml-security/libs
Now we have to unpackage the rest of the the Java libraries. These are needed to build and run IPL. Here is the rundown:
$ unzip xml-security-bin-1_1_0.zip $ tar xzf axis-1_1.tar.gz $ tar xzf javamail-1_3_1-upd.zip $ tar xzf jaxm-1_1_2.zip
$ cp xml-security-1_1_0/build/xmlsec.jar xml-security/libs $ cp axis-1_1/lib/saaj.jar xml-security/libs $ cp axis-1_1/lib/log4j-1.2.8.jar xml-security/libs $ cp javamail-1.3.1/mail.jar xml-security/libs $ cp jaxm1.1.2/lib/jaxm-api.jar xml-security/libs
Now onto building IPL.
Edit build.properties in ipl-1.0/impl/ and set the correct location for tomcat (in our sample that is /home/joe/liberty/jakarta-tomcat-5.0.19). It will look something like:
tomcat=/home/joe/liberty/jakarta-tomcat-5.0.19 jwsdp=../../jwsdp-1.0 xmlsec=../../xml-security idpwebapps=../../jwsdp-1.0/webapps spwebapps=../../jwsdp-1.0/webapps testwebapps=../../jwsdp-1.0/webapps
Now edit build.xml. We need to replace some of the classpath entries. First, replace fileset dir="${jwsdp}/common/lib" with fileset dir="${tomcat}/common/lib" since we are using the Tomcat servlet API. Next add fileset entries for xmlsec.jar, lib4j-1.2.8.jar, saaj.jar, mail.jar and jaxm-api.jar.
It should look something like this when you're done:
<path id="classpath">
<fileset dir="${tomcat}/common/lib" />
<pathelement location="${build}" />
<fileset dir="${xmlsec}/libs" includes="xmlsec.jar"/>
<fileset dir="${xmlsec}/libs" includes="log4j-1.2.8.jar"/>
<fileset dir="${xmlsec}/libs" includes="saaj.jar"/>
<fileset dir="${xmlsec}/libs" includes="mail.jar"/>
<fileset dir="${xmlsec}/libs" includes="jaxm-api.jar"/>
</path>
Now just run ant to build IPL. It should build cleanly and you should be left with 3 war files in the dist/ directory.
The ipl-1.0/impl/providers.xml file describes the IPL configuration. It gives URL information for the IDP and any SPs that are available. First, copy this to its final destination, /home/joe/liberty/providers.xml.
You will need to edit the hostname entries to match your configuration. If you change a URL then you will need to generate a new signature for it. To do this, use the openssl command.
$ echo -n provider-ID | openssl sha1
For example
$ echo -n "http://myhost:8000/idp" | openssl sha1
Take the output of this and put it into the ProviderSuccinctID field in providers.xml. You'll need to do this for the IDP and any SPs you configure.
The same providers.xml may be used for both the IDP and the SP.
We will also need the private keys used for signing. We can use the sample provided with IPL. Copy the impl/test/src/keystore to /home/joe/liberty/keystore.
I did testing using 2 separate machines. One was used for the IDP, the other for the SP. In my test configuration the directory service ran on the IDP machine. It is possible to run both the IDP and SP on the same machine but additional configuration/tweaking of the AOLserver and Tomcat configurations will be necessary to change the port configuration. This is not covered here.
To deploy the war file(s), copy the appropriate one to /home/joe/liberty/jakarta-tomcat-5.0.19/webapps. You need to manually deploy this because workers2.properties needs to be updated. AOLserver uses workers2.properties to identify which URLs are Java applications.
First, lets update the Tomcat configuration.
The JNI connector works for the most part but there is a bug related to POST data. Only the first POST seems to read the content data properly. Subsequent POSTs seem to have the data either lost or appended to the original data. This means that many times incorrect name/value pairs are presented as attributes and/or invalid data is presented. As such IPL simply doesn't work properly (notably logout doesn't work at all).
Switching to socket mode fixes the problem. To switch to socket mode, edit the Tomcat conf/workers2.properties file and set disabled=1 for channel.jni:jni and set disabled=0 for channel.socket:localhost:8009
It will look something like:
channel.jni:jni disabled=1 debug=0 channel.socket:localhost:8009 disabled=0 channel.socket:localhost:8019 disabled=1
Now add the URI for our IDP processing. I picked the URI idp, you can use whatever you'd like:
uri:/idp/* info=IDP context=/idp debug=0
To actually deploy the war file, use the unzip command (you can also use jar if you have it available). I'll use idp.war as an example. Deploying the sp is very similar. You will also need to copy the jars we used to build IPL to the deployment directory.
$ mkdir idp $ cd idp $ unzip /home/joe/liberty/ipl-0.1/impl/idp.war $ mkdir WEB-INF/lib $ cp /home/joe/liberty/xml-security/libs/* WEB-INF/lib
Go ahead and deploy the SP now too in a similar way as the IDP. The sp is contained in /home/joe/liberty/ipl-0.1/impl/sp.war. We can ignore sp2.war for now as we are only using one SP.
Now that the web application is deployed, we're almost there. We now need to configure the web applications themselves. webapps/idp/WEB-INF/web.xml contains the configuration for our IDP. We need to customize it for the current environment.
By default, AOLserver listens on port 8000 so we are using that here.
The directory configuration is done here even though we don't actually install it until the next step. The suffix and DN setup is driven by a sample dataset. It can be changed to match your environment at a future point.
The following changes are needed:
- Set localProviderID to the URL of your IDP (http://localhost:8000/idp)
- Set xmlProviderDescriptorFile to the filesystem location of your providers.xml (/home/joe/liberty/providers.xml)
- Set signingKeystore to the filesystem location of the file keystore which ships with IPL (/home/joe/liberty/keystore)
- Set userMetadataURL to the URL of your LDAP server (ldap://localhost:3389/ou=People,ou=idp,dc=example,dc=com)
- Set userMetadataPrin to a user with write privileges (cn=Directory Manager)
- Set userMetadataCred to the password of that user (secret)
- Set debugAuthn to true to set the user's password to be the same as their uid
- Set debug to true for copious output during testing
- Set cookieTransferURL to match your SP URL configuration (http://localhost:8000/idp/cookie-xfer)
- Set cookieWritingURL to match your SP URL configuration http://localhost:8000/idp/cookie-write)
The SP requires similar changes, they are:
- Set localProviderID to the URL of your SP (http://localhost:8000/sp)
- Set xmlProviderDescriptorFile to the filesystem location of your providers.xml (/home/joe/liberty/providers.xml)
- Set signingKeystore to the filesystem location of the file keystore which ships with IPL (/home/joe/liberty/keystore)
- Set userMetadataURL to the URL of your LDAP server (ldap://localhost:3389/ou=People,ou=sp1,dc=example,dc=com)
- Set userMetadataPrin to a user with write privileges (cn=Directory Manager)
- Set userMetadataCred to the password of that user (secret)
- Set debugAuthn to true to set the user's password to be the same as their uid
- Set useFormPost to true
- Set debug to true for copious output during testing
- Set cookieTransferURL to match your SP URL configuration (http://localhost:8000/sp/cookie-xfer)
- Set cookieWritingURL to match your SP URL configuration http://localhost:8000/sp/cookie-write)\
Setting up the LDAP Directory Server
Testing began using OpenLDAP but problems with Federation were encountered. There may be an easy solution for this problem but it was not followed up on. Instead I used a trial version of Netscape Directory Server. This works fine. The SunONE Directory Server should work as well.
To install, run the ./setup program after uncompressing and untarring the downloaded file.
You can probably ignore any warnings about your machine not being configured properly. This testing will not require a very fast server.
For the most part, stick to the defaults presented. The notable exceptions are:
Install location: put it where you want (/home/joe/liberty/directory) Computer name: enter your fully-qualified hostname System User: for testing purposes, run this as a user (joe), not root. Network port: I chose 3389 for testing Suffix: must be dc=example, dc=com Directory Manager DN: cn=Directory Manager
Password: secret
Once the server is installed it should be automatically started by the installation routine. Once that is done you can setup the schema required by issuing the following command. If you get an message about SASL/DIGEST-MD5 add the -x flag to the command (some versions of Linux ship with a sasl-enabled ldapsearch and ldapmodify).
$ ldapmodify -h localhost -p 3389 -D "cn=Directory Manager" -w password < ipl-0.1-schema.ldif
Now you can populate it with some sample users:
$ ldapmodify -h localhost -p 3389 -D "cn=Directory Manager" -w password -a < ipl-0.1-example.ldif
Testing
You are now ready to try out your new Liberty-enabled server!
Lets start with the IDP. Start it up with:
$ cd /home/joe/liberty/aolserver $ bin/start-java -ft sample-config.tcl
The -f flag will keep AOLserver in the foreground.
Bring up a browser to http://idphost:8000/idp/protected.jsp
You should be presented with a login screen.
Login in as idpuser/idpuser.
This should be successful.
Now log out.
Now start the SP. Start it up with:
$ cd /home/joe/liberty/aolserver $ bin/start-java -ft sample-config.tcl
Bring up a browser to http://sphost:8000/sp/protected.jsp
You should be presented with a login screen.
Login in as sp1user/sp1user.
This should be successful.
Now log out.
If everything has gone smoothly up to now it means that the basics are working. The two servers work independently of one another and can communicate with the LDAP database.
Now go back to http://sphost:8000/sp/protected.jsp and login as sp1user again.
Click Federate and choose to Federate the IDP.
You will be prompted for another login. Use idpuser/idpuser to log into the IDP and click accept to ok the federation.
Now log out of the SP.
Go back to http://sphost:8000/sp/protected.jsp
Select the Liberty Login to your IDP.
Log in with idpuser/idpuser
You should be redirected back to the SP and be connected as sp1user.
Congratulations, IPL is working.
Troubleshooting
Q. During login I get javax.servlet.ServletException: Cannot set user.
A. You will probably need to set debug to true in web.xml. This error can happen for several reasons and debug outlines them:
- [[[LDAP: error code 49 - Invalid Credentials]] - The userMetadataPrin DN is incorrect or the userMetadataCred password entry is incorrect.
- [[[Root exception is java.net.ConnectException: Connection refused]] - The ldap URL userMetadataURL is incorrect or the directory server is not running.
Q. I get java.lang.NoClassDefFoundError: javax/mail/internet/MimeUtility when logging out.
A. You need to copy the 5 additional jars need to build IPL into the web application (or they need to be in Tomcat's classpath). For example, for the IDP you would do:
$ cp /home/joe/liberty/xml-security/libs/* /home/joe/liberty/jakarta-tomcat-5.0.19/webapps/idp/WEB-INF/lib
Navigation Patch
During my testing I found it annoying to have to keep typing new URLs into the browser window whenever I wanted to log back in or so other normal navigation. I made the follow changes to the SP web application that made my life a little easier. This isn't required to get IPL working.
--- federate.jsp.orig 2004-08-11 10:27:13.840002000 -0400
+++ federate.jsp 2004-08-11 10:27:18.210000000 -0400
@@ -67,6 +67,7 @@
}
%>
</form>
+ <a href="protected.jsp">Go back</a>
$Id: federate.jsp,v 1.5.2.2 2002/09/17 01:52:19 jsergent Exp $ </body> --- logout-done.jsp.orig 2004-08-11 10:24:38.790001000 -0400 +++ logout-done.jsp 2004-08-11 10:25:52.170001000 -0400 @@ -24,6 +24,7 @@ <title>Logout</title> </head> <body> - Logout was successful. Goodbye. + Logout was successful. Goodbye.
+ You may <a href="protected.jsp">log in again</a>. </body> </html> --- index.html.orig 2004-08-11 10:23:39.430001000 -0400 +++ index.html 2004-08-11 10:23:53.090001000 -0400 @@ -25,6 +25,7 @@ <title>Service Provider</title> </head> <body> - This is only a test. + This is only a test. See also <a href="protected.jsp">protected + page</a>. </body> </html>
