Skip to main content

OIDC Integration

For better user experience, security and identity federation, Cafe Variome V4 supports authentication via OpenID Connect (OIDC) providers. This allows users to log in using their accounts from trusted identity providers, such as institutional login systems or third-party services like Life Science AAI. Additionally, this provides an extra token to the data query, which Cafe Variome can use to determine additional user access rights, or to pass the token to other services.

Configuring OIDC Provider​

Cafe Variome V4 can use multiple OIDC providers simultaneously. Each provider must be configured via the interface. The configuration is stored in the database, and the client secret is stored in the KMS. Before configuring the provider in Cafe Variome, you must first register the application with the OIDC provider to obtain the client ID and client secret. Using KeyCloak as an example, the client needs to be set up as follows:

  • root URL: https://your.cafe-variome-instance.org/
  • home URL: https://your.cafe-variome-instance.org/
  • valid redirect URIs: https://your.cafe-variome-instance.org/api/auth/oidc/your-idp-identifier/callback*
  • enable Client Authentication and Standard Flow, disable all other flows unless needed for other purposes.
  • enable token refresh if supported.
  • to use group claims for authorisation, configure the Group Membership mapper to include the groups in the ID token.
  • to allow different instances to inspect the token, configure the Audience mapper to include the client ID as an audience.

* The your-idp-identifier is a unique identifier for the OIDC provider in Cafe Variome. You may need to create the client in OIDC provider first, supply the credentials to Cafe Variome to create the provider entry, then get the correct redirect URI from Cafe Variome to update the client configuration in the OIDC provider.

OIDC token issuance and management​

Cafe Variome V4 uses the standard browser redirection flow to authenticate users via OIDC providers, with Backend for Frontend (BFF) pattern to manage the tokens securely. The flow to log in a user via OIDC is as follows:

  • * PKCE is used when the OIDC IdP supports it. This is automatically detected by checking the well-known configuration of the OIDC provider.
  • ** The access token is stored in-memory if configured to use in-memory cache (usually in single-process deployments) in plaintext, or stored in the cache/broker (e.g., Redis) encrypted with a symmetric key managed by the KMS.
  • *** The self-issued access token is a JWT token signed by Cafe Variome, not the OIDC token.

Token retention and session sync​

There is a design choice to be made regarding how to manage the tokens issued by OIDC providers. We recognise two main use cases:

  • The token is used to query other Cafe Variome instances, Beacon services, or other network-based services that require the token for authorisation.
  • The token is only used to determine user access rights within the Cafe Variome instance.

So we decided to maintain the access token, which is supposed to be short-lived, in the backend for the duration of the token's lifetime. When sending requests to other services, Cafe Variome will decide whether the token is needed, and attach it if necessary. However, there is still the refresh token. There are two options to manage the refresh token:

  • The refresh token is sent back to the user as a secure, HTTP-only cookie. When the user makes a query, the backend checks if the access token is still valid. If not, it asks the frontend to send the refresh token cookie to get a new access token. This approach minimises the storage requirement on the backend, but introduces more complexity in synchronising the session state between multiple user sessions (e.g., multiple browser tabs), and if the user is not actively using the system, the session may expire and the user needs to log in again.
  • The refresh token is stored in the backend in KMS, and is refreshed automatically when needed. This means that the user will only need to log in once, and the session will be maintained as long as the refresh token is valid. This approach simplifies the user experience, but turns the backend into a custodian of long-lived tokens, which may have security implications.

In practice, we added a switch to choose between the two approaches. By setting the environment variable CV_MAINTAIN_SSO_SESSION to true, the backend will store the refresh token and manage the session automatically. If this setting is changed while there are active sessions, the cache will be purged at next restart, and all stored refresh tokens will be deleted. Ensure you understand the implications before changing this setting in a production environment.

OIDC token usage for authorisation​

Cafe Variome V4 can extract claims from the OIDC ID token to determine user access rights. For the details of how to configure access groups and permissions, please refer to the Local Authorisation documentation. The group and attribute is regex matched, so when configuring the access groups, ensure the regex is correct to match the claims and only the intended claims.

Additionally, various data sources may be configured in Cafe Variome to be marked as "using some IdP". When a user queries data from such data sources, Cafe Variome will attach the corresponding IdP tokens to the query, if the user has logged in via that IdP (through identity linking). Only one matched IdP token is sent in the Authorization header, as a standard Bearer token. The first matched IdP that the user also has a session for will be used.

Within a network, Cafe Variome V4 instances also reports to each other which IdPs they support. When a user queries data from another Cafe Variome instance, the sender instance will attach all IdP tokens that the receiver instance supports, if the user has logged in via those IdPs, in a custom message format. This allows the receiving instance to determine user access rights based on the IdP tokens if it's configured to do so.

Identity linking​

After logging in via OIDC, the remote OIDC account still must be linked to a local account in Cafe Variome to determine the access rights. If the CV_SSO_REGISTRATION is set to true, then after the first login via OIDC, if there is no existing local account linked to the OIDC account, it will attempt to auto-link the identity. If a local user already use the same email address as the OIDC account, then the OIDC account will be linked to that local user. Otherwise, a new local account will be automatically created and linked to the OIDC account, using the user ID (usually the preferred_username or username claim) and the email from the OIDC provider. If the username is not available in the introspection response, the username will be set to the sub claim, or a random UUID if the sub claim is also not available. This means that the claims used must be unique and not conflicting with anything in the local user database, otherwise the creation will fail. We recommend not to toggle this option if there are already existing users in the system.

If the CV_SSO_REGISTRATION is set to false, then after the first login via OIDC, if there is no existing local account linked to the OIDC account, the user will be prompted to link their local account to the OIDC account. They must already have a local account, and will be prompted to login to that account and finish the linking process. This means that if both the SSO registration and local registration are disabled, no new users can be created or logged in via OIDC, and the system can only be used by existing users that are created by administrators.