Authentication Admin Guide (How to setup the Tomcat in the server)

General

The authentication mechanism is a replacement of the normal Tomcat implementation of the SSLServerSocketFactory.

Before setting up you should have at least the server credentials (server certificate and private key or server proxy) and the Certificate Authority (CA) certificates. Preferably you also have the certificate revocation lists (CRLs) and the mechanism to update them set up.

The credentials are used to authenticate the server to the client and the CA certificates (and CRLs) are used to verify the identity of the client.

To begin you need to have a Tomcat installed. The installation can be a new clean installation or an older one. When using older installation that already contains something, please notice that the installation will overwrite the ssl setup in the tomcat/conf/server.xml for the port that will be used. The authentication has been tested with Tomcat 4.0.x and 4.1.x.

Requirements

The authentication package requires that there is a Jakarta Tomcat 4.x installed.

Dependencies

To have the Authentication working you need the following:

Also during installation the Xerces library might be needed (if the ChangeFactory program is used).

Obtaining the edg-java-security packages

rpm

The packages are available as RPMs in http://datagrid.in2p3.fr/distribution/datagrid/wp2/RPMS as two files:

edg-java-security-xxxxxxxx.rpm edg-java-security-tomcat-xxxxxxxx.rpm

The tomcat version should be used for the tomcat installation.

tarball

The packages are also available as tarballs for more manual installation. http://grid-data-management.web.cern.ch/grid-data-management/security/releases/index.html Use the edg-java-security-tomcat-xxxxxx.tar.gz version.

Deployment

Before starting make sure you have the Tomcat installed, but it doesn't have to be configured.

rpm

To install the rpm package just issue the command:

rpm -in edg-java-security-xxxxxxxxxx.noarch.rpm

tarball

If you use the tarball package, just untar it over the tomcat installation. This will install all the necessary libraries to the tomcat/server/lib directory.

Semimanual setup

After installing the package, just edit the authentication.props file according to your local setup. The authentication.props was copied into tomcat/conf during the rpm/untar. For additonal information about the settings, see TrustManagerOptions.

Then add the xerces and the security libraries to your classpath and issue the command

java org.edg.security.trustmanager.tomcat.ChangeFactory server.xml auhtentication.props temp.xml

If you want to check that the new server.xml (called temp.xml) is ok, please do so.

Then just copy the temp.xml over the old server.xml.

Start your tomcat.

Manual setup

To make the Authentication work with the Tomcat, you need to do 2 things.

First add the needed jar libraries to tomcat/server/lib. If you are using the tar distribution, untarring it over the tomcat puts these jars automatically to the right place. Otherwise you need to manually put the bouncycastle, log4j and the security jars there.

Second, you need to edit the tomcat/conf/server.xml according to the information in TrustManagerOptions. Below is an example.

<!-- Define an SSL HTTP/1.1 Connector on port 8443 -->
<Connector className="org.apache.catalina.connector.http.HttpConnector"
port="8443" minProcessors="5" maxProcessors="75"
enableLookups="true"
acceptCount="10" debug="0" scheme="https" secure="true">
<Factory className="org.edg.security.trustmanager.tomcat.SSLServerSocketFactory"
caFiles="/etc/grid-security/certificates/*.0"
clientAuth="true"
crlFiles="/etc/grid-security/certificates/*.r0"
crlRequired="false"
crlUpdateInterval="1h"
gridProxyFile="/etc/grid-security/server.proxy"
credentialsUpdateInterval="10min"
logConf="/opt/edg/etc/log4j.conf"
protocol="TLS"/>
</Connector>