Compatibility

This authentication plugin will work with an ICAT version of 4.3 or greater.

Prerequisites

• The authn_db distribution: authn_db-1.1.1-distro.zip
• A suitable deployed container (here assumed to be glassfish though tomcat should be sufficient) to support a web application. Testing has been carried out with Glassfish 3.1.2. Glassfish installation instructions are available.
• A database as described in Database installation instructions installed on the server
• Python (version 2.4 to 2.7) installed on the server.

Summary of steps

1. Please follow the generic installation instructions
2. Update the icat.properties file for icat to see the authenticator.
3. Add users
4. Check that it works.

The authn_db.setup.properties file

driver

is the name of the jdbc driver and must match the jar file for your database that you stored in the previous step.

authn_dbProperties

identifies the password database and how to connect to it.

glassfish

is the top level of the glassfish installation. It must contain "glassfish/domains", and will be referred to here as GLASSFISH_HOME as if an environment variable had been set.

port

is the administration port of the chosen glassfish domain which is typically 4848.

For a local oracle-xe installation the following values of driver, authn_dbProperties should be good except for the user and password values:

driver=oracle.jdbc.pool.OracleDataSource
authn_dbProperties=url="'"jdbc:oracle:thin:@//localhost:1521/XE"'":ImplicitCachingEnabled=true:MaxStatements=200:user=authn_db:password=secret

Note the "'" which is needed because the url contains colons which also separate individual properties.

For MySQL:

driver=com.mysql.jdbc.jdbc2.optional.MysqlDataSource
authn_dbProperties=user=icat:password=secret:databaseName=authn_db

The authn_db.properties file

ip

If access to the DB authentication should only be allowed from certain IP addresses then provide a space separated list of allowed values. These take the form of an IPV4 or IPV6 address followed by the number of bits (starting from the most significant) to consider.

mechanism

if specified is a label to appear before the user name as it is made available to ICAT for authorization. For example if this is set to 'db' then the user 'root' will be provided to ICAT as 'db/root', but of no mechanism is specified it will be provided simply as 'root'.

Update the icat.properties file for your ICAT

This is required for icat to see the new authenticator. As any earlier version of this authenticator will have been removed then it is important to perform this next step promptly.

If you still have the installation directory for icat then edit the icat.properties to refer to the new authenticator and type: ./setup install Otherwise edit the icat.properties file in the config directory for your domain and restart the glassfish domain.

Add users

Users should be added by manually adding them to the database table PASSWD. This has two columns, one for the username and one for the password. The password may be entered as clear text without a leading "$" or a cryptographic hash of a password may be stored. A password hash must start with a "$" character and be in the same form as found in the shadow(5) password file. It may be created using the mkpasswd(1) utility on Debian systems or grub-crypt on Red Hat derived systems or the python crypt module. The supported hash algorithms are MD5, SHA-256, and SHA-512.

Check that authn_db works

Use testicat (which is installed with ICAT) with one of the entries in the database PASSWD table. It should report that it logs in but may or may not have the permission to run the rest of the test. If it does not report that it has logged in then please check the server.log and the authn_db.log files which can both be found in the logs directory below your domain.