General Information

Introduction

This authentication plugin enables users to log in to ICAT via an external OpenID Connect (OIDC) identity provider such as Keycloak. Unlike other ICAT authentication plugins, it doesn't check the user's credentials by itself. Instead, it leaves this part to the identity provider (IdP) and relies on a so-called token to actually authenticate the user.

Example authentication flow for TopCAT login

  • Step 1: A user wants to log in to ICAT from a web interface (here assumed to be TopCAT) and chooses to do so via OpenID Connect.
  • Step 2: The user gets redirected to the IdP.
  • Step 3: The user enters their credentials at the IdP.
  • Step 4: If the credentials are valid, the user gets redirected back to a registered callback URL. Along with the redirection comes an authorization code included in the URL.
  • Step 5: The authorization code is used to obtain a signed token from the IdP.
  • Step 6: The authn.oidc plugin takes the token as input and verifies its signature. If the token is valid, authn.oidc extracts the ICAT username from the token and returns it.
  • Step 7: The ICAT server creates a session for the user that can be used for TopCAT.

Note that the authn.oidc plugin is only responsible for step 6. The other steps require some more work on your end.

Work items needed for the above authentication flow

  • To enable step 1, you need to add a corresponding link or button to the login page of TopCAT.
  • For the steps 2 and 5, you must put in place a service that handles the communication with the IdP to obtain the token.
  • In steps 6 and 7, you have to use the token to log in to ICAT via the authn.oidc authenticator on behalf of the user. You then have to store the obtained ICAT session in the browser's session storage such that TopCAT can make use of it.

Tokens

OpenID Connect defines (among others) two types of tokens: The access token and the identity token. By definition, the identity token is always a so-called JSON Web Token (JWT). While the access token does not have such a strictly defined format, some identity providers (including Keycloak) also issue access tokens in the JWK format as well. Note, however, that this is not required.

The authn.oidc plugin accepts any token that uses the JWT format. It doesn't matter whether this is an access token or an identity token. What matters is that the token must include a claim with the ICAT username to identify the user.

Note that the token must be issued and signed by the IdP which authn.oidc is configured to trust. This includes two aspects: (1) The iss claim in the token must match the tokenIssuer specified in run.properties; and (2) the token's signature must be verifiable using a public key (jwks_uri) from the wellKnownUrl specified in run.properties.