Home

The ACLS-tomcat-realm project provides Tomcat realm implementations that provide container-based authentication using an ACLS service as a backend authentication provider.

To use the realm implementation, you need to do the following:

1. Add the elvis6.jar or elvis7.jar file to the tomcat container classpath. (You can't put it in the webapp.)
2. Add an slf4j logging adapter to map logger events to your container's logger.
3. Add realm declarations to either the global context or the relevant webapp contexts. The Elvis bean parameters include the hostname or IP address of the ACLS service (or proxy) and its port number, and a "dummy" ACLS facility name and (optional) "local host id" string to identify this service.

Here is an example realm declaration that combines the ACLS realm and another realm (for local accounts) within a "lockout" realm. The lockout realm is designed to slow down attempts to break security by guessing passwords.

<?xml version="1.0" encoding="UTF-8"?>
<Context>
    <Realm className="org.apache.catalina.realm.LockOutRealm">
        <Realm className="org.apache.catalina.realm.MemoryRealm"/>
	    <Realm className="au.edu.uq.cmm.tomcat.realm.ACLSRealm" 
           serverHost="acls.example.com" serverPort="1024" 
           timeout="10000" dummyFacility="The Proxy" localHostId="FISH"/>
    </Realm>
</Context>

The meaning of the parameters to the ACLSRealm bean are as follows:

• The serverHost and serverPort parameters give the hostname (or IP address) and the port number of the ACLS server / proxy to use for authentication. (Port 1024 is hard-wired into current generation ACLS servers, but this is configurable for an Eccles proxy.)
• The timeout parameter gives the time that Tomcat should wait before giving up on an ACLS connect or a request. If you are talking to a proxy that does credential caching, you need to factor in the proxy's timeout when talking to the ACLS server. The timeout is specified in milliseconds, and defaults to twice the Eccles proxy default timeout.
• The dummyFacility parameter gives the ACLS facility name to be used in the authentication requests. (What we are doing is pretending to login to a "dummy" ACLS facility / instrument, and using the success / failure as an indication that the username / password pair is valid and active.)
• The localHostId parameter gives an optional identifier for this service. (This will be explained in the Aclslib documentation.)