KeyCloak Credentials and Account

Client authentication

To secure the authentication flow and authenticate the backend service with (Keycloak), the client must be set to confidential. This is also required to enable a service account role. Enabling this generates a client secret, which is used to authenticate the backend service with Keycloak. By design, the client secret CANNOT BE CHANGED IN RUNTIME, as the backend must always be able to interact with Keycloak at any point. To rotate the client secret, the backend service must be stopped. The new secret can then be updated externally in the vault or entered manually using the CLI tool before restarting the service.

The Cafe Variome Assistant tool can also rotate the secrets of an instance it manages. Refer to its documentation for more details.

Standard flow

Both the CV3 frontend and backend are designed exclusively to use the standard flow. This approach is chosen for its high compatibility and security while minimizing the risk of credential leaks. The client secret is stored in the backend, while the frontend sends an authorization code to exchange for an access token.

Unlike standard designs, where tokens are stored in the backend to authenticate with other resources, CV3 keeps the tokens in the frontend. This is because all authorization is independent of the OIDC service, and the tokens have only minimal scopes. By doing so, the backend remains RESTful and can potentially be used with any other tools or interfaces that provide the correct tokens.

Service account role

CV3 backend requires a service account to perform elevated privilege operations inside KeyCloak. There are two reasons for this:

• It allows the user token to have minimal scopes, as the backend does not need it to authenticate with Keycloak or perform operations.

• It enables the backend to perform operations outside the context of a request and execute background tasks.

Token exchange

CV3 uses a token exchange service to translate tokens between realms or broaden their audience, enabling introspection by another client. This supports the federated nature of user authentication in the federated network model. This feature must be explicitly enabled in Keycloak by rebuilding the server with it activated. This is also why Keycloak is necessary, as other OIDC providers are not compatible with CV3.

view-users

CV3 needs visibility of all users within the realm. This is because any user registered with a CV3 instance could send a query to any other CV3 instance in the same realm. To handle this, CV3 must be aware of all users in advance, allowing admins to preemptively grant permissions. This differs from the V2 user management model, where each instance only managed users within its local database.

manage-users

CV3 must be able to create users and update their information. This role allows admins to add users directly through the admin interface and modify affiliation details stored in Keycloak.

read-token

CV3 must be able to read a user's token to perform a token exchange. This allows the backend to translate the token into another realm or expand its audience, enabling introspection by another client. This supports the federated nature of user authentication within a federated network model.

manage-account

This role allows CV3 to manage its own service account, which has an associated email address used as the primary admin contact. CV3 instances or the CVA tool can send alerts to this address to notify admins of important events. This must be updated accordingly.

create-client, manage-clients, view-clients and manage-realm

"These roles are required only when nexus mode is enabled in the config file. Nexus mode requires a CV3 instance to create credentials for CV2 instances, meaning it must have permission to view, create, and manage all clients within this realm. Use this permission with caution, as any mistakes could impact not only CV2 clients but also other applications. It is recommended to enable nexus mode on a single CV3 instance and use it to manage all CV2 instances within the realm. This is a strict limitation in the CVA tool.