Re3gistry - ECAS insallation guide

 

This install guide shows you a way to configure ECAS authentication for Apache Tomcat 6.0, 7.0 and 8.0. The described mechanism was tested on Apache Tomcat 6.0.35, 7.0.57 with Java 6.0. It was also tested on Apache Tomcat 7.0.57 and 8.0.15 with Java 7.0 and Tomcat 8.0.15 with Java 8.0.

Note: the ECAS client for Tomcat 6.0 is the same as for version 5.5. References to the client version 5.5 even for the client version 6.0 installation are on purpose. The ECAS client for Tomcat 7.0 is different from 5.5 and requires at least Java 6.0. The ECAS client for Tomcat 7.0 is different from 5.5 and requires at least Java 6.0. The ECAS client for Tomcat 8.0 is different from Tomcat 7.0 and requires at least Java 7.0 while Java 8.0 also works fine with it.

 

Trusting the CommisSign PKI

First, you need to be able to open SSL connections from your application to the ECAS server in order to validate ECAS tickets.

For that purpose, you need to import the CommisSign PKI certificates into your Java trustStore as the SSL certificate of the ECAS server is issued by the CommisSign PKI.

The two CommisSign PKI certificates (called "EuropeanCommission.cer" and "CommisSign.cer") are available in the project package. You have to import them into the Java trustStore of the JVM you will use.

This default trustStore is usually located at ${JRE_HOME}/lib/security/cacerts and its default password is "changeit".

You can do the import with the keytool command-line utility from the JDK or a GUI tool such as portecle, keytoolGUI or KeyMan.

With keytool, it would look like:

D:\java\jdk1.5.0_07\jre\lib\security>keytool -import -v -keystore cacerts -storepass changeit -alias EuropeanCommissionRootCA -file EuropeanCommissionRootCA.cer
Owner : CN=European Commission Root CA
Issuer : CN=European Commission Root CA
Serial Number : 1
Valid from : Tue Jan 21 19:01:38 CET 2003 to : Mon Dec 31 19:01:38 CET 2012
Certificate Fingerprint :
         MD5 :  18:C1:AC:06:B0:C1:55:79:2F:A8:79:72:D3:6A:8F:3B
         SHA1: 8B:E9:C1:E9:68:93:A3:3C:19:3F:52:2C:8F:F1:E1:00:E7:7F:70:83
Trust this certificate ? [no] :  yes
Certificate added to Keystore
[Storing cacerts]
D:\java\jdk1.5.0_07\jre\lib\security>keytool -import -v -keystore cacerts -storepass changeit -alias CommisSignClassA -file CommisSignClassA.cer
Certificate added to Keystore
[Storing cacerts]

 

For Tomcat 5.5 (Obsolete and Insecure)

Copy the client JAR

Get the version of the ECAS client for Apache Tomcat 5.5 in the project package and copy into your installation of Tomcat at ${tomcat.home}/ server /lib (where ${tomcat.home} is the directory where you installed tomcat)

The ECAS client uses Log4J for its logging statements, so you also have to copy log4j jar (for instance log4j-1.2.14.jar) to ${tomcat.home}/ common /lib

Your /server/lib folder should look like:

24/08/2007  17:34            23.322 catalina-ant-jmx.jar
24/08/2007  17:34            26.349 catalina-ant.jar
24/08/2007  17:34           227.278 catalina-cluster.jar
24/08/2007  17:34           115.486 catalina-optional.jar
24/08/2007  17:34            63.265 catalina-storeconfig.jar
24/08/2007  17:34           654.094 catalina.jar
24/08/2007  17:34           112.005 commons-modeler-2.0.1.jar
06/11/2007  17:23         7.307.219 ecas-tomcat55-$\{LAST.VERSOIN\}.jar
24/08/2007  17:34            20.153 servlets-cgi.renametojar
24/08/2007  17:34            18.819 servlets-default.jar
24/08/2007  17:34             6.012 servlets-invoker.jar
24/08/2007  17:34            52.916 servlets-ssi.renametojar
24/08/2007  17:34            22.501 servlets-webdav.jar
24/08/2007  17:34           167.840 tomcat-ajp.jar
24/08/2007  17:34            25.172 tomcat-apr.jar
24/08/2007  17:34            19.220 tomcat-coyote.jar
24/08/2007  17:34            88.695 tomcat-http.jar
24/08/2007  17:34            30.056 tomcat-jkstatus-ant.jar
24/08/2007  17:34           257.381 tomcat-util.jar

Add the ECAS Authenticator for Tomcat

Extract the content of tomcatFiles.zip into ${tomcat.home}/server/classes

This way, you added two files in /server/classes:

  • in org/apache/catalina/authenticator you now have mbeans-descriptors.xml which is the JMX xml description of the ECAS Authenticator for Tomcat
  • in org/apache/catalina/startup/Authenticators.properties which registers the ECAS auth-method besides the standard authentication methods you can specify in web.xml descriptors

Put the server context in privileged mode

Add the privileged="true" attribute to the Context tag in ${tomcat.home}/conf/context.xml:

<Context>

becomes

<Context privileged="true">

 

 

For Tomcat 6.0

Copy the client JAR

Get the version of the ECAS client for Apache Tomcat 5.5 in the project package and copy into your installation of Tomcat at ${tomcat.home}/lib (where ${tomcat.home} is the directory where you installed tomcat)

The ECAS client uses Log4J for its logging statements, so you also have to copy log4j jar (for instance log4j-1.2.14.jar) to ${tomcat.home}/lib

Add the ECAS Authenticator for Tomcat

Extract the content of tomcatFiles.zip into ${tomcat.home}/lib

This way, you added two files in /lib:

  • in org/apache/catalina/authenticator you now have mbeans-descriptors.xml which is the JMX xml description of the ECAS Authenticator for Tomcat
  • in org/apache/catalina/startup/Authenticators.properties which registers the ECAS auth-method besides the standard authentication methods you can specify in web.xml descriptors

Your ${tomcat.home}/lib folder should look like:

20/07/2007  04:20            10.368 annotations-api.jar
20/07/2007  04:20            47.524 catalina-ant.jar
20/07/2007  04:20           117.853 catalina-ha.jar
20/07/2007  04:20           220.995 catalina-tribes.jar
20/07/2007  04:20         1.106.069 catalina.jar
07/11/2007  13:45         7.309.646 ecas-tomcat55-${LAST.VERSION}.jar
20/07/2007  04:20            27.699 el-api.jar
20/07/2007  04:20           101.456 jasper-el.jar
20/07/2007  04:20         1.375.531 jasper-jdt.jar
20/07/2007  04:20           509.617 jasper.jar
20/07/2007  04:20            80.800 jsp-api.jar
04/12/2005  19:00           358.180 log4j-1.2.14.jar
07/11/2007  13:45    <DIR>          org
20/07/2007  04:20            88.537 servlet-api.jar
20/07/2007  04:20           726.744 tomcat-coyote.jar
20/07/2007  04:20           172.732 tomcat-dbcp.jar
20/07/2007  04:20            36.414 tomcat-i18n-es.jar
20/07/2007  04:20            33.610 tomcat-i18n-fr.jar
20/07/2007  04:20            39.719 tomcat-i18n-ja.jar

 

For Tomcat 7.0

Copy the client JAR

Get the last version of the ECAS client for Apache Tomcat 7.0 in the project package and copy into your installation of Tomcat at ${tomcat.home}/lib (where ${tomcat.home} is the directory where you installed tomcat)

The ECAS client uses Log4J for its logging statements, so you also have to copy log4j jar (for instance log4j-1.2.14.jar) to ${tomcat.home}/lib

Add the ECAS Authenticator for Tomcat

Extract the content of ecas-tomcat-7.0-1.14.0-config.zip into ${tomcat.home}/lib

This way, you added two files in /lib:

  • in org/apache/catalina/authenticator you now have mbeans-descriptors.xml which is the JMX xml description of the ECAS Authenticator for Tomcat
  • in org/apache/catalina/startup/Authenticators.properties which registers the ECAS auth-method besides the standard authentication methods you can specify in web.xml descriptors

Your ${tomcat.home}/lib folder should look like:

 Directory of apache-tomcat-7.0.4\lib

14/10/2010  20:27            15.262 annotations-api.jar
14/10/2010  20:27            54.062 catalina-ant.jar
14/10/2010  20:27           130.621 catalina-ha.jar
14/10/2010  20:27           251.050 catalina-tribes.jar
14/10/2010  20:27         1.409.887 catalina.jar
29/10/2010  00:47         1.111.182 ecas-tomcat-7.0-1.14.0.jar
14/10/2010  20:27         1.690.519 ecj-3.6.jar
14/10/2010  20:27            42.803 el-api.jar
14/10/2010  20:27           123.413 jasper-el.jar
14/10/2010  20:27           580.922 jasper.jar
14/10/2010  20:27            88.487 jsp-api.jar
16/01/2009  14:42           358.085 log4j-1.2.12.jar
13/10/2010  13:23    <DIR>          org
14/10/2010  20:27           176.389 servlet-api.jar
14/10/2010  20:27             6.869 tomcat-api.jar
14/10/2010  20:27           742.709 tomcat-coyote.jar
14/10/2010  20:27           234.639 tomcat-dbcp.jar
14/10/2010  20:27            69.638 tomcat-i18n-es.jar
14/10/2010  20:27            51.731 tomcat-i18n-fr.jar
14/10/2010  20:27            53.778 tomcat-i18n-ja.jar
14/10/2010  20:27            18.422 tomcat-util.jar

 

For Tomcat 8.0

Copy the client JAR

Get the last version of the ECAS client for Apache Tomcat 8.0 in the project package and copy into your installation of Tomcat at ${tomcat.home}/lib (where ${tomcat.home} is the directory where you installed tomcat)

The ECAS client uses Log4J for its logging statements, so you also have to copy log4j jar (for instance log4j-1.2.17.jar) to ${tomcat.home}/lib

Add the ECAS Authenticator for Tomcat

Extract the content of ecas-tomcat-8.0-3.11.2-config.zip into ${tomcat.home}/lib

This way, you added two files in /lib:

  • in org/apache/catalina/authenticator you now have mbeans-descriptors.xml which is the JMX xml description of the ECAS Authenticator for Tomcat
  • in org/apache/catalina/startup/Authenticators.properties which registers the ECAS auth-method besides the standard authentication methods you can specify in web.xml descriptors

Your ${tomcat.home}/lib folder should look like:

 Directory of apache-tomcat-8.0.15\lib

02/11/2014  20:27            15.262 annotations-api.jar
02/11/2014  20:27            54.062 catalina-ant.jar
02/11/2014  20:27            54.062 catalina-ant.jar
02/11/2014  20:27           130.621 catalina-ha.jar
02/11/2014  20:27            72.000 catalina-storeconfig.jar
02/11/2014  20:27           251.050 catalina-tribes.jar
02/11/2014  20:27         1.409.887 catalina.jar
22/12/2014  11:47         1.492.182 ecas-tomcat-8.0-3.11.2.jar
02/11/2014  20:27         1.690.519 ecj-4.4.jar
02/11/2014  20:27            42.803 el-api.jar
02/11/2014  20:27           123.413 jasper-el.jar
02/11/2014  20:27           580.922 jasper.jar
02/11/2014  20:27            88.487 jsp-api.jar
22/12/2014  14:42           358.085 log4j-1.2.17.jar
22/12/2014  13:23    <DIR>          org
02/11/2014  20:27           176.389 servlet-api.jar
02/11/2014  20:27             6.869 tomcat-api.jar
02/11/2014  20:27           742.709 tomcat-coyote.jar
02/11/2014  20:27           234.639 tomcat-dbcp.jar
02/11/2014  20:27            69.638 tomcat-i18n-es.jar
02/11/2014  20:27            51.731 tomcat-i18n-fr.jar
02/11/2014  20:27            53.778 tomcat-i18n-ja.jar
02/11/2014  20:27           132.000 tomcat-jdbc.jar
02/11/2014  20:27            64.000 tomcat-jni.jar
02/11/2014  20:27            54.000 tomcat-spdy.jar
02/11/2014  20:27            18.422 tomcat-util.jar
02/11/2014  20:27           194.000 tomcat-util-scan.jar
02/11/2014  20:27           197.000 tomcat-websocket.jar
02/11/2014  20:27            36.000 tomcat-util.jar

 

Allow authenticated users who have no roles

The meaning of <role-name>*</role-name> in the web.xml has changed.
It now means that only authenticated users that possess at least one role from the ones configured in your web.xml are authorized to proceed.

To get back the previous behaviour i.e. granting access to all authenticated users regardless of whether they possess a role or not, you have to edit the file ${tomcat.home}/conf/server.xml. Locate the Realm element. This should look like:

Tomcat 6 and below

<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
             resourceName="UserDatabase"/>

and add the allRolesMode="authOnly" attribute.
That is:

<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
             resourceName="UserDatabase" allRolesMode="authOnly"/>

You do not need this if you always use explicit roles instead of <role-name>*</role-name>.

Tomcat 7 & 8

<Realm className="org.apache.catalina.realm.LockOutRealm">
  <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
         resourceName="UserDatabase" />
</Realm>

and add the allRolesMode="authOnly" attribute.
That is:

<Realm className="org.apache.catalina.realm.LockOutRealm" allRolesMode="authOnly">
  <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
         resourceName="UserDatabase" />
</Realm>