Keycloak Configuration Settings

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

Within kdb Insights Enterprise, 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 kdb Insights Enterprise 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 kdb Insights Enterprise 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 kdb Insights Enterprise 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
`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>