Installation
Compatibility
This plugin will work with an ICAT version of 4.9.0 or greater.
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
- wellKnownUrl
-
The well-known OpenID configuration URL of the token issuer. It is
expected to specify a jwks_uri. Only tokens that can be validated
using a key from the jwks_uri will be accepted by authn.oidc.
-
In the case of Keycloak, it should look like this:
https://example.org/auth/realms/example/.well-known/openid-configuration
- tokenIssuer
-
The name or URL of the token issuer. This must exactly match the
'iss' claim encoded within the token and the 'issuer' attribute
found at the wellKnownUrl.
-
In the case of Keycloak, it should look like this:
https://example.org/auth/realms/example
- icatUserClaim
-
The claim encoded within the token that shall be used as the ICAT
username.
- icatUserClaimException
-
By default, if no icatUserClaim is present in the token, authn.oidc
falls back to using the 'sub' claim. If you would prefer an
AuthnException to be thrown in this case, set this property to
'true'.
- ip
-
If access to the OIDC 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.
- mechanism
-
If specified is a label to appear before the username as it is made
available to ICAT for authorization. By default, this only affects
usernames obtained from the 'sub' claim. For usernames from the
icatUserClaim, authn.oidc tries to extract the
mechanism from the username itself.
-
For example, let's assume this is set to 'oidc'. If a token contains
the icatUserClaim 'db/fred', then the username would be
provided to ICAT as 'db/fred'. But if a token only contains the
'sub' claim '37715', then the username would be provided to ICAT as
'oidc/37715'.
- icatUserPrependMechanism
-
Set this property to 'true' if you also want to prepend usernames
from the icatUserClaim with the mechanism label. This
only makes sense if the usernames encoded within the tokens don't
already include a mechanism.
-
For example, let's assume this is set to 'true' and the mechanism is
set to 'oidc'. If a token contains the icatUserClaim
'fred', then the username would be provided to ICAT as 'oidc/fred'.
But if a token contains the icatUserClaim 'db/fred',
then the username would be provided to ICAT as 'oidc/db/fred'.
Check that authn.oidc works
A simple standalone test is to run:
curl -k https://localhost:8181/authn.oidc/description -w "\n"
which returns a description,
curl -k https://localhost:8181/authn.oidc/version -w "\n"
which returns the version,
curl -k https://localhost:8181/authn.oidc/jwkupdate -X POST
which triggers an update of the JWK configuration, and
curl -k https://localhost:8181/authn.oidc/authenticate -w "\n"
-d 'json={"credentials":[{"token":"<token>"}]}'
to authenticate.
