Skip to content

Keycloak Configuration Settings

The KX Insights Platform utilizes Keycloak to offer a full range of authentication and authorization services. Full documentation on these topics is available here.

Within the KX Insights Platform, there are a number of service level configurations available within the Keycloak service, configuration that needs to be shared across multiple charts is placed under the global key.

global:
  keycloak:
    guiClientSecret: "gui-client-secret"
    operatorClientSecret: "kxi-operator-client-secret"

keycloak:
  auth:
    existingSecret: kxi-keycloak
  postgresql:
    auth:
        existingSecret: kxi-postgresql
  initUser:
    enabled: false
    name: "demoinsights"
    auth: "<redacted>"
  initClient:
    enabled: false
    clientId: "test-publisher"
    clientSecret: "<redacted>"
  resetPasswordAllowed: true
  smtpServer:
    host: smtp.host.net
    from: admin@host.com
    user: apikey
    password: <redacted>
  passwordPolicy:
    enabled: true
    policy:
      length: 14
      upperCase: 1
      lowerCase: 1
      specialChars: 1
      digits: 1
      forceExpiredPasswordChange: 90
    text: |
        <p>Password policy:</p>
        <ul>
            <li>At least one uppercase letter</li>
            <li>At least one lowercase letter</li>
            <li>At least one symbol</li>
            <li>At least one number</li>
            <li>Minimum length of 14 or greater</li>
        </ul>

global.keycloak

The configuration below is shared between multiple charts. Client secrets allow microservices to communicate securely via Keycloak to request access tokens, giving secure access to other microservices.

variable type example default
global.keycloak.guiClientSecret string gui-client-secret
global.keycloak.operatorClientSecret string kxi-operator-client-secret

auth.existingSecret

Administrator authentication secret. Used by administrator user account to login when setting and updating user and permissions within the system. Set at install time.

variable type example default
auth.existingSecret string kxi-keycloak NA

postgresql.auth.existingSecret

Backend secret used to allow keycloak to communicate securely with the backend persistence layer. Also set at install time

variable type example default
postgresql.auth.existingSecret string kxi-postgresql NA

initUser

initUser configuration allows the system administrator to provide a default user to login to KX Insights Platform UI and API endpoints. On first login the user will have to update their password.

initUser.enabled allows the system administrator to set whether the default user is enabled on install

variable type example default
initUser.enabled bool true false
initUser.name string demoinsights demoinsights
initUser.auth string Sup3RS3cretPa$$ <redacted>

initClient

initClient configuration allows the system administrator to provide a default service account to login to use for programmatic access to the KX Insights Platform API.

initClient.enabled allows the system administrator to set whether the default client is enabled on install

variable type example default
initClient.enabled bool true false
initClient.clientId string test-publisher test-publisher
initClient.clientSecret string Ajfjksjwe121 <redacted>

keycloakConfigCli

keycloakConfigCli configuration allows you to control how the keycloak config CLI runs after install or upgrade. These settings are useful if you want to store your Keycloak configuration as code.

If the keycloak config CLI job is enabled, then the realm defined in the secret keycloak-realm or inside the files defined in another secret can be imported into the Keycloak instance.

variable type example default
keycloakConfigCli.enabled bool true false
keycloakConfigCli.extraVolumeMounts map
keycloakConfigCli.extraVolumes map

The extraVolumeMounts and extraVolumes keys can used if there is already an existing secret with a realm defined in it.

If you want to automatically import the default realm defined by the KX Insights Platform on upgrade, simply enabled the keycloakConfigCli job and the default realm will be imported.

keycloak:
  keycloakConfigCli:
    enabled: true

If you want to maintain a separate realm secret, you would specify this as

keycloak:
  keycloakConfigCli:
    enabled: true
    extraVolumeMounts:
      - name: config
        mountPath: "/config"
        readOnly: true
    extraVolumes:
      - name: config
        secret:
          secretName: my-separate-keycloak-realm # replacing this with the name of the secret you want to use
          items:
          - key: "realm.json" # replace this with the key in the secret that contains the realm
            path: "realm.json"

If there are multiple files inside the secret and you want them all to be imported, you would specify this as

keycloak:
  keycloakConfigCli:
    enabled: true
    extraVolumeMounts:
      - name: config
        mountPath: "/config"
        readOnly: true
    extraVolumes:
      - name: config
        secret:
          secretName: my-separate-keycloak-realm # replacing this with the name of the secret you want to use

Other settings for the keycloak config CLI that may be of use can be found here

resetPasswordAllowed

When enabled, this allows users to reset their forgotten password via email. SMTP server credentials should be provided via smtpServer to prompt users for their forgotten password. With password resets enabled, users will have a "Forgot Password?" prompt appear on their login screen. Clicking this will take the user through the keycloak forgot password flow. The user must have a configured email address.

variable type example default
smtpServer.resetPasswordAllowed string true false

smtpServer

SMTP server credentials used by keycloak to prompt users for their forgotten password when resetPasswordAllowed is enabled

variable type example default
smtpServer.host string smtp.host.net
smtpServer.from string admin@host.com
smtpServer.user string apikey
smtpServer.password string Pa$$w0rd!

passwordPolicy

This defines the password policy that is enforced in the system. By default, a password policy is enabled which aims to provide a decent baseline that supports further modification.

The values listed below can be adjusted at deployment time to change the password policy to suit your needs. For example, if you are running in a development environment, you might want to disable the password policy completely. On the other hand, if you are running in a production environment, you might want to enforce a stricter policy.

variable type description default
passwordPolicy.enabled bool Whether a password policy is enabled true
passwordPolicy.policy.length number Minimum password length 14
passwordPolicy.policy.upperCase number Minimum number of upper case characters 1
passwordPolicy.policy.lowerCase number Minimum number of lower case characters 1
passwordPolicy.policy.specialChars number Minimum number of special characters 1
passwordPolicy.policy.digits number Minimum number of digits 1
passwordPolicy.policy.forceExpiredPasswordChange number Time until password expiry in days 90
passwordPolicy.text string HTML text to display the policy on the password update page See here

The password policy text is shown on the 'Update password' screen

Password policy text

Post deployment, the password policy settings can be adjusted by following the Keycloak password policy documentation.

Password policies

The password policy text can be adjusted post deployment by following the steps in the advanced docs. This does not automatically update if the settings are changed in Keycloak, so you must ensure it is kept in sync if the settings are changed.

Shared Keycloak Instances

When using a shared Keycloak instance, the password policy text displayed on the 'Update password' screen is shared across all realms.

This means you should ensure that all realms have the same password policy settings in order for the password policy text to accurately reflect the policy.

If this is not ensured, it can lead to situations where the text on the screen doesn't accurately reflect the policy being enforced.

Default password policy text

<p>Password policy:</p>
<ul>
    <li>At least one uppercase letter</li>
    <li>At least one lowercase letter</li>
    <li>At least one symbol</li>
    <li>At least one number</li>
    <li>Minimum length of 14 or greater</li>
</ul>