Installation
Compatibility
This authentication plugin will work with an ICAT version of 4.3 or greater.
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.