Enrich keycloak token

Warning

Beta version This feature is currently in beta. It may change in a future version without prior notice. See the Beta Features page for the full list of beta features and their planned release. If you’re using this feature, we encourage you to share your feedback to help with the evaluation process.

Overview

When a user logs into Keycloak, an ID token is generated and signed. This token is then utilized by various services (frontend and backend) to perform user-specific actions. A common scenario is the association of users with groups to define their permissions. If Keycloak cannot natively populate group information, this functionality provides the ability to fetch and integrate data from external sources not directly supported by Keycloak, ensuring seamless rights management.

Note

The enrichment can by disable permanently by setting the environment variable DISABLE_ENRICH_TOKEN to true for the osp-keycloak.

Capabilities

Capability

Support

Comment

Incorporating permissions from an external source

Supported feature

See documentation

Use multiples scripts to configure the token

Not supported feature

The system will execute a single script, which should manage all the necessary logic if multiple actions are required.

Replace existing IdToken field

Not supported feature

The order does not permit to replace an existing field.

Force refreshing a token

Not supported feature

See token refresh for when a token is refreshed

Token refresh rules

Tokens are updated only during the following events:

  • When a user logs in.

  • When the token expires, requiring the generation of a new token.

Incorporating permissions from an external source

Concept

Use an external source of trust or collection to adding rights to the groups. In some case, the rights cannot be forwarded to keycloak in a standard manner. This feature permit to use a custom script to fetch this data from elsewhere and inject them.

Usage

A single script can be configured to enhance the generated token. This script will be executed during each token generation process. Be sure to avoid using blocking calls and manage the timeout of external services to prevent the risk of losing all login access to your installation.

Warning

The maximum allowed time to complete the process is 10 seconds.

The configuration of the script is done on the file authorization.keycloak which must be placed in the same folder than module.keycloak.

The field sourceFile of authorization.keycloak contains the link to the script to use. This must be a .js or .mjs file.

The script will receive a representation of the user, which will allow to find the information to add new claim. This is available as tokenRequest.

The definition of the claim is done with the Authorization controller.

Below, an example that add the claim test when the user with email test@localhost is accessing OnSphere.

function main() {
  log.info("Request is [{}]", tokenRequest);

  if (tokenRequest.email === "test@localhost") {
    log.info("User test detected");
    authorization.add("test");
  }

  return true;
}

main();

Note

The script support the import the same way as the script module.

Use-case

  • Utilize a collection to enable certain users to manage the permissions of others.

  • Employ an HTTP REST API to populate user permissions dynamically.

Examples