Installation

Compatibility

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

Prerequisites

Summary of steps

  1. Please follow the generic installation instructions
  2. If you are introducing the simple authenticator then update the run.properties file for 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. Check that it works.

The setup.properties file

container
Values must be chosen from: TargetServer Though only Glassfish is working properly at the moment.
home
is the top level of the container installation. For Glassfish it must contain "glassfish/domains" and for JBoss (wildfly) it must contain jboss-modules.jar.
port
is the administration port of the container which is typically 4848 for Glassfish and 9990 for JBoss.
secure
must be set to true or false. If true then only https and not http connections will be allowed.

The logback.xml file

If you wish to modify the provided logging levels then rename logback.xml.example to logback.xml and edit it to suit your needs.

The run.properties file

user.list
Space separated list of user names that this plugin authenticates.
user.<user>.password
For each user given in user.list, this sets the password this user. This may either be a clear text password or a cryptographic hash of a password.
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.
A clear text password must not start with a "$" character.
ip
If access to the SIMPLE 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 'simple' then a user with an entry of 'fred' will be provided to ICAT as 'simple/fred', but if no mechanism is specified it will be provided simply as 'fred'.

Update the icat.properties file for your ICAT

This is required for icat to see the new authenticator if this is the first time that a RestFul (2.0.0 and greater) LDAP authenticator has been used by the icat.server.

Go to the installation directory for icat.server then edit the run.properties to refer to the new authenticator and type: ./setup install

Check that authn.simple works

Use testicat (which is installed with ICAT) with valid ldap credentials. 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_simple.log files which can both be found in the logs directory.

A simple standalone test is to run:
curl -k https://localhost:8181/authn.simple/description -w "\n" which returns a description,
curl -k https://localhost:8181/authn.simple/version -w "\n" which returns the version and
curl -k https://localhost:8181/authn.simple/authenticate -w "\n" -d 'json={"credentials":[{"username":"<username>"},{"password":"<secret>"}]}' to authenticate.