Installation

Compatibility

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

Prerequisites

  • The authn.ldap distribution: authn.ldap-2.0.0-distro.zip
  • A suitable deployed container (here assumed to be Payara/Glassfish) to support a web application. Testing has been carried out with payara41. Payara/Glassfish installation instructions are available.
  • Python (version 2.4 to 2.7) installed on the server.
  • If you wish to connect to the ldap server with SASL i.e. a url starting ldaps: rather than ldap: then you may need to store a certificate to say that you trust the ldap server. If this is necessary then, in the case of Payara/Glassfish, it should be added to keystore.jks in the config directory of the domain you are using and the domain stopped and started again.

Summary of steps

  1. Please follow the generic installation instructions
  2. If you are introducing the ldap 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

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.

provider_url
Space separated list of ldap url values. Each must start with ldap or ldaps.
security_principal
The % character in the security_principal will be replaced by the specified user name. If you just use % then the user must enter a complete security_principal as his user name.

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 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.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.

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