Image Customizations

Add additional jars

Adding additional jars to Keycloak’s deployment is as simple as adding that jar to the src/extra-jars directory.

Adding new jars will require building a new identity-config image for uds-core.

See Testing custom image in UDS Core for building, publishing, and using the new image with uds-core.

Once uds-core has sucessfully deployed with your new image, viewing the Keycloak pod can provide insight into a successful deployment or not. Also describing the Keycloak pod, should display your new image being pulled instead of the default image defined here in the events section.

Customizing Theme

Official Theming Docs

• Official Keycloak Theme Docs
• Official Keycloak Theme Github

Changes can be made to the src/theme directory. At this time only Account and Login themes are included, but c email, admin, and welcome themes could be added as well.

Testing Changes

To test the identity-config theme changes, a local running Keycloak instance is required.

Don’t have a local Keycloak instance? The simplest testing path is utilizing uds-core, specifically the dev-identity task. This will create a k3d cluster with Istio, Pepr, Keycloak, and Authservice.

Once that cluster is up and healthy and after making theme changes, utilize this task to :

1. Execute this command:

      uds run dev-theme

2. View the changes in the browser

Customizing Realm

The UDS Identity realm is defined in the realm.json found in src/realm.json. This can be modified and will require a new uds-identity-config image for uds-core.

Note

Be aware that changing values in the realm may also need to be updated throughout the configuration of Keycloak and Authservice in uds-core. For example, changing the realm name will break a few different things within Keycloak unless those values are changed in uds-core as well.

See the Testing custom image in UDS Core for building, publishing, and using the new image with uds-core.

Templated Realm Values

Keycloak supports using environment variables within the realm configuration, see docs.

These environment variables have default values set in the realm.json that uses the following syntax:

  ${REALM_GOOGLE_IDP_ENABLED:false}

In the uds-core keycloak values.yaml, the realmInitEnv defines set of environment variables that can be used to configure the realm different from default values.

These environment variables will be created with a prefix REALM_ to avoid collisions with keycloak environment variables. If necessary to add additional template variables within the realm.json must be prefixed with REALM_.

For example, this bundle override contains all the available overrides:

overrides:
   keycloak:
      keycloak:
         values:
            path: realmInitEnv
            value:
               GOOGLE_IDP_ENABLED: true
               GOOGLE_IDP_ID: <fill in value here>
               GOOGLE_IDP_SIGNING_CERT: <fill in value here>
               GOOGLE_IDP_NAME_ID_FORMAT: <fill in value here>
               GOOGLE_IDP_CORE_ENTITY_ID: <fill in value here>
               GOOGLE_IDP_ADMIN_GROUP: <fill in value here>
               GOOGLE_IDP_AUDITOR_GROUP: <fill in value here>
               EMAIL_VERIFICATION_ENABLED: true
               OTP_ENABLED: true
               TERMS_AND_CONDITIONS_ENABLED: true
               PASSWORD_POLICY: <fill in value here>
               X509_OCSP_FAIL_OPEN: true
               ACCESS_TOKEN_LIFESPAN: 600
               SSO_SESSION_LIFESPAN_TIMEOUT: 1200
               SSO_SESSION_MAX_LIFESPAN: 36000
               USERNAME_PASSWORD_AUTH_ENABLED: true
               X509_AUTH_ENABLED: true
               SOCIAL_AUTH_ENABLED: true
               DISABLE_REGISTRATION_FIELDS: true

These environment variables can be found in the realm.json.

Customizing Session and Access Token Timeouts

The SSO_SESSION_IDLE_TIMEOUT specifies how long a session remains active without user activity, while the ACCESS_TOKEN_LIFESPAN defines the validity duration of an access token before it requires refreshing. The SSO_SESSION_MAX_LIFESPAN determines the maximum duration a session can remain active, regardless of user activity.

To ensure smooth session management, configure the idle timeout to be longer than the access token lifespan (e.g., 10 minutes idle, 5 minutes lifespan) so tokens can be refreshed before the session expires, and ensure the max lifespan is set appropriately (e.g., 8 hours) to enforce session limits. Misalignment, such as setting a longer token lifespan than the idle timeout or not aligning the max lifespan with session requirements, can result in sessions ending unexpectedly or persisting longer than intended.