Installation

Compatibility

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

Prerequisites

  • The authn.ldap distribution: authn.ldap-1.2.1-distro.zip
  • A suitable deployed container (here assumed to be Glassfish/Payara) to support a web application. Testing has been carried out with payara41. Glassfish/Payara installation instructions are available. If domain1 is not being used then line 21 of the setup script must be modified to match the actual domain name.
  • Python (version 2.4 to 2.7) installed on the server.

Summary of steps

  1. Please follow the generic installation instructions
  2. 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 authn_ldap.setup.properties file

container
May be either glassfish or wildfly - 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.

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