Keycloak

Configuring Extra Environment Variables

Keycloak Extra Environment Variables is only supported if the platform is deployed with the Axual Helm Charts. At the moment, Axual CLI doesn’t support configuring Extra Environment Variables.

In case you need to override or configure some aspect of Keycloak via environment variables, it is possible to do so by adding the custom variable to the mgmt.keycloak.extraEnv object, as shown below.

mgmt:
  keycloak:
    extraEnv: |
      - name: KEY_1
        value: 'custom-env-var-1'
      - name: KEY_2
        value: 'custom-env-var-1'

After updating the configuration, upgrade the Axual platform release using the above modified values.yaml:

helm upgrade --install platform axual-stable/platform -f values.yaml --version=<helm-chart-version> -n kafka

You can also configure additional environment variables for Keycloak mapped from a Secret or ConfigMap. To do so, you can either configure a new secret or use a secret not managed by the Axual platform release. The example below shows how to create one using the mgmt.keycloak.secrets object:

mgmt:
  keycloak:
    secrets:
      customSecret:
        stringData:
          KEY_1: 'custom-env-var-1'
          KEY_2: 'custom-env-var-1'
    extraEnvFrom: |
      - secretRef:
          name: '{{ include "keycloak.fullname" . }}-customSecret'

After updating the configuration, upgrade the Axual platform release using the above modified values.yaml:

helm upgrade --install platform axual-stable/platform -f values.yaml --version=<helm-chart-version> -n kafka

All these Keycloak configurations are supported.

Configuring Certificate Authority (CA) to Keycloak’s Truststore

Custom Certificate Authority (CA) configuration is only supported if the platform is deployed with the Axual Helm Charts. At the moment, Axual CLI doesn’t support configuring custom Certificate Authority (CA).

Sometimes custom Certificate Authority (CA) needs to be configured to enable Keycloak to connect to a 3rd party/external service. To do so, you will need to map the custom CA to Keycloak’s container as well as configure the X509_CA_BUNDLE environment variable as an extra environment variable. The custom CAs are provided as PEM string, ending with the .crt extension, to the mgmt.keycloak.secrets.ssl-creds secret object, and the environment variable is configured as part of mgmt.keycloak.extraEnv.

A working example looks like the below:

mgmt:
  keycloak:
    secrets:
      ssl-creds:
        stringData:
          your_custom_ca.crt: |
            -----BEGIN CERTIFICATE-----
            MIIFJjCCAw6gAwIBAgIJAINuAirfnRU6MA0GCSqGSIb3DQEBCwUAMCAxHjAcBgNV
            BAMMFUF4dWFsIER1bW15IFJvb3QgMjAxODAeFw0xODA1MjkxMDM0MTRaFw0zODA1
            ...
            okA2uUH/ZuJlR/BEmqbLt5HWPRNT/GgLfPY=
            -----END CERTIFICATE-----
    extraEnv: |
      - name: X509_CA_BUNDLE
        value: "/etc/x509/https/your_custom_ca.crt"

If you need to configure multiple Certificate Authorities, you can do so by informing them by separating them with a blank space, as shown below:

mgmt:
  keycloak:
    secrets:
      ssl-creds:
        stringData:
          your_custom_ca.crt: |
            -----BEGIN CERTIFICATE-----
            MIIFJjCCAw6gAwIBAgIJAINuAirfnRU6MA0GCSqGSIb3DQEBCwUAMCAxHjAcBgNV
            BAMMFUF4dWFsIER1bW15IFJvb3QgMjAxODAeFw0xODA1MjkxMDM0MTRaFw0zODA1
            ...
            okA2uUH/ZuJlR/BEmqbLt5HWPRNT/GgLfPY=
            -----END CERTIFICATE-----
          your_another_custom_ca.crt: |
            -----BEGIN CERTIFICATE-----
            MIIFJjCCAw6gAwIBAgIJAINuAirfnRU6MA0GCSqGSIb3DQEBCwUAMCAxHjAcBgNV
            BAMMFUF4dWFsIER1bW15IFJvb3QgMjAxODAeFw0xODA1MjkxMDM0MTRaFw0zODA1
            ...
            okA2uUH/ZuJlR/BEmqbLt5HWPRNT/GgLfPY=
            -----END CERTIFICATE-----
    extraEnv: |
      - name: X509_CA_BUNDLE
        value: "/etc/x509/https/your_custom_ca.crt /etc/x509/https/your_another_custom_ca.crt"

Note the path of the certificate authority is always /etc/x509/https, and its filename is the same as the secret key name. If you’re using a secret not managed by Axual platform release, make sure to put the CA files in the /etc/x509/https directory in the container.

After updating the configuration, upgrade the Axual platform release using the above modified values.yaml:

helm upgrade --install platform axual-stable/platform -f values.yaml --version=<helm-chart-version> -n kafka

Import Keycloak’s realm for the default tenant

If you’re deploying the platform from scratch and you are using Keycloak, you might need to enable the default’s tenant realm creation. To do so, set the global.mgmt.keycloak.importInitialRealm value to true, as in the example below:

values.yaml
global:
  mgmt:
    keycloak:
      importInitialRealm: true

You will then need to run a helm upgrade command specifying the values.yaml to upgrade the release:

helm upgrade --install platform axual-stable/platform -n kafka -f values.yaml

Alternatively, you can override the specific property with the --set option

helm upgrade --install platform axual-stable/platform --set global.mgmt.keycloak.importInitialRealm="true" -n kafka

Restrict Keycloak Admin console Access

Restricting Keycloak admin console access is only supported if the platform is deployed with the Axual Helm Charts. At the moment, Axual CLI doesn’t support restricting Keycloak admin console access.

If Keycloak is deployed as part of the platform, its admin console will be publicly accessible by default on the same port and hostname as its APIs. Once the Keycloak is configured, we might not need or want the admin console to be publicly reachable. To restrict its access, set the global.mgmt.keycloak.publicAdminConsole value to false, as in the example below:

values.yaml
global:
  mgmt:
    keycloak:
      publicAdminConsole: false

You will then need to run a helm upgrade command specifying the values.yaml to upgrade the release:

helm upgrade --install platform axual-stable/platform -n kafka -f values.yaml

Alternatively, you can override the specific property with the --set option

helm upgrade --install platform axual-stable/platform --set global.mgmt.keycloak.publicAdminConsole="false" -n kafka

Realm Settings

  • In the Keycloak realm settings you can configure Session Settings.

  • You can go to the realm settings:

    • In the Main Menu, Select Realm Settings

    • In the top Menu, Select Tokens

  • You will see the following screen

keycloak realm settings

  • The following timeouts can be adjusted according to your needs, only if the defaults don’t match your needs.

Parameter Default Description

SSO Session Idle

1 hour

Time a Session is allowed to be idle

SSO Session Max

8 hours

Maximum length of any session, irrespective of activity

Client Session Idle

0 minutes

Time a Session is allowed to be idle

Client Session Max

0 minutes

Maximum length of a client session, irrespective of activity

Access Token Lifespan

5 minutes

Maximum Time before an access token is expired. This should be short
Client Session Max and Client Session Idle are set to 0 and values for SSO Session Max and SSO Session Idle override them respectively.

Theme Settings

In the Keycloak Admin Console, you can change the theme globally or specifically for a client

Global login theme

  • To change global Keycloak login theme, in the Main Menu, select Realm Settings and then Themes tab.

keycloak global login theme

Specific client login theme needs to be unselected because otherwise specific client login theme overrides global login theme.

Client specific login theme

  • To change Keycloak login theme for Self-Service client, in the Main Menu, select Clients, then select Self-Service and click the Login theme dropdown to update the login theme

keycloak selfservice login theme