Compatibility

Prerequisites

• The authn.db distribution: authn.db-3.0.1-SNAPSHOT-distro.zip
• A suitable deployed application server that supports JakartaEE 10+. Testing has been carried out with Payara Server Community 6. Other applications servers such as GlassFish and WildFly may work but have not been tested. Glassfish/Payara installation instructions are available.
• A database as described in Database installation instructions installed on the server or accessible from it.
• Python 3.6+ installed on the server.

Summary of steps

1. Please follow the generic installation instructions
2. Update the run.properties file if necessary for the icat.server to see the authenticator and restart icat to see the change. The easiest way is to rerun the setup script for the icat.server. Remember that restful authenticators are identified by url rather than jndi.
3. Add users
4. Check that it works.

The setup.properties file

container

May be either Glassfish or JBoss - though only glassfish is working fully at the moment.

home

is the top level of the container installation. For glasssfish it must contain "glassfish/domains" and for wildfly it must contain jboss-modules.jar.

port

is the administration port of the container which is typically 4848 for glassfish and 9990 for wildfly.

secure

must be set to true or false. If true then only https and not http connections will be allowed.

db.target

This is optional and may be used to control the SQL generated by the JPA. Values must be chosen from: TargetDatabase

db.driver

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

db.url

url to connect to your database. For example: jdbc:mysql://localhost:3306/icat

db.username

username to connect to your database.

db.password

password to connect to your database.

The run.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 the icat.server 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 run.properties file for your ICAT

This is required for the icat.server to see a new authenticator. If you are just updating an existing restful authenticator then the run.properties of the icat.server will not need changing.

Assuming that you still have the installation directory for icat.server then edit the run.properties to refer to the new authenticator and type: ./setup install

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 Modular Crypt Format. The supported hash algorithms are MD5, SHA-256, and SHA-512. Do not use MD5 because it is insecure.

Use the following command to create a SHA-256 hash: openssl passwd -5

The mkpasswd(1) utility can also be used. It is provided by the whois package on Debian-based systems: mkpasswd --method=SHA-256

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.