Installation

Compatibility

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

Prerequisites

Summary of steps

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

The authn_ldap.setup.properties file

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.

The authn_ldap.properties file

This file configures from where calls may be made, properties to pass to the ldap server and mappings to perform on the provided user name to get the returned value.

Control of IP address from which a call is allowed

ip
If access to the LDAP 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.

Overriding or supplementing key value pairs in the LDAP context.

This is to cater for possibilities not otherwise covered

context.props
an optional space separated list of keys to be added to or overridden in the ldap context
context.props.<key>
the value for the specified key. For example you might have:
context.props = java.naming.factory.initial java.naming.security.authentication
context.props.java.naming.factory.initial = com.sun.jndi.ldap.LdapCtxFactory
context.props.java.naming.security.authentication = simple
which are actually the default values.

ldap mapping

It is possible to specify a query which will map the user name provided onto a new name. This is controlled by the three properties listed below. If one is present they must all be present. For example:

ldap.base = DC=fed,DC=cclrc,DC=ac,DC=uk
ldap.filter = (&(CN=%)(objectclass=user))
ldap.attribute = name
will work at RAL to replace the user name identified by the CN value with that held in the name attribute.
ldap.base
the base for the search
ldap.filter
an LDAP filter which should return one result - the first one returned is used
ldap.attribute
the attribute name to use

Control of case of returned name

In addition to the ability to use an ldap search to map the name you can simple specify case = upper or case = lower to simply convert the case. This is applied after the ldap mapping described above.
case
optional case specification - if specified must be "upper" or "lower".

Control of mechanism part of the returned name

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 'ldap' then the user 'root' will be provided to ICAT as 'ldap/root', but if 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.

Check that authn_ldap 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_ldap.log files which can both be found in the logs directory below your domain.