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_shib2local.setup.properties file

driver
is the name of the jdbc driver and must match the jar file for your database that you stored in the previous step.
dbProperties
identifies the mapping database and how to connect to it.
glassfish
is the top level of the glassfish installation. It must contain "glassfish/domains".
port
is the administration port of the chosen glassfish domain which is typically 4848.

For a local oracle-xe installation the following values of driver, dbProperties should be good except for the user and password values:

driver=oracle.jdbc.pool.OracleDataSource
dbProperties=url="'"jdbc:oracle:thin:@//localhost:1521/XE"'":ImplicitCachingEnabled=true:MaxStatements=200:user=authn_shib2local:password=secret

Note the "'" which is needed because the url contains colons which also separate individual properties.

For MySQL:

driver=com.mysql.jdbc.jdbc2.optional.MysqlDataSource
dbProperties=user=icat:password=secret:databaseName=authn_shib2local

authn_shib2local.properties

ip
If access to Shibboleth-to-Local 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.
service_provider_url
The Shibboleth-protected web location with which to initiate authentication.
identity_provider_url
Points directly at the Shibboleth ECP profile endpoint on the Shibboleth IdP. The URL looks similar to this: https://MY-IDP-HOST/idp/profile/SAML2/SOAP/ECP
lookup_attribute
which attribute in the resulting SAML assertion to use as lookup in the database holding local account names. You can specify this attribute either as the URN/OID or the more friendly, human-readable FriendlyName. Example: <saml2:Attribute FriendlyName="uid" Name="urn:oid:0.9.2342.19200300.100.1.1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> You can either specify "uid" or "urn:oid:0.9.2342.19200300.100.1.1" as attribute
mapping
Flag with case-insensitive value ALWAYS, NEVER or TRY. If the flag is ALWAYS, mapping will be attempted and a failure will result in a failed login. If the flag is NEVER then no mapping is performed. If the flag is TRY then mapping will be attempted.
unmapped_user
Optional user name to return if no succesful mapping has been performed. If no value is specifed the SAML attribute will be returned
proxy_host
Optional name of proxy host. If specified the proxy_port must also be specified
proxy_port
Optional name of proxy port. If specified the proxy_host must also be specified
disable_cert_check
Optionally set to true to disabling certificate checking
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 'shibboleth' then the user 'xyz123' will be provided to ICAT as 'shibboleth/xyz123', but of no mechanism is specified it will be provided simply as 'xyz123'.

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.

Add user mappings

Users should be added to the database table ACCOUNTIDMAP. This has two columns, one for the EAAHash value and one for the ICAT username to map it onto. The table may be manually edited. It is expected that a facility will provide a web based mechanism to authenticate simultaneously to Shibboleth and to something that guarantees his ICAT user name and then put an entry in the table.

Check that authn_shib2local works

Use testicat (which is installed with ICAT) for someone with a Shibboleth account and for which a mapping has been provided in the database ACCOUNTIDMAP table if required by the configured mapping property. 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_shib2local.log files which can both be found in the logs directory below your domain. If you modify the authn_shib2local.properties file you can use the setup script to reinstall but you must also restart ICAT (which will have a stale handle to the old instance) and which can be done by restarting the glassfish domain.