Keycloak

Functionality

Overview

API

No direct interaction with the Keycloak should be necessary.

In some cases, the operator could access the Keycloak Admin Console to change the themes.

Installation

Keycloak is dependent on an MySQL database, preferably a managed DB.

Helm Charts

As part of the Governance charts, the component can be installed following the guide Axual Streaming & Governance Installation.

Configuration

Any configuration available in the public Keycloak Documentation can be used.

Keycloak setup

The configuration of Keycloak is described in page Configure Keycloak

Helm configuration

Refer to Codecentric KeycloakX repository.

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 governance.keycloak.extraEnv object, as shown below.

governance:
  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/axual-governance -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 governance.keycloak.secrets object:

governance:
  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/axual-governance -f values.yaml --version=<helm-chart-version> -n kafka

All these Keycloak configurations are supported.

Configure `extraVolumes`, `extraVolumeMounts`, or `extraInitContainers`

The Keycloak dependency comes with a default values.yaml that contains extraVolumes, extraVolumeMounts, and extraInitContainers to configure the Keycloak stateful set with Axual specific theme and realm.

In case you want to provide your own extraVolumes, extraVolumeMounts, or extraInitContainers we advise you to include also the ones coming from the default values.yaml.

These are the default extraVolumes, extraVolumeMounts, and extraInitContainers defined in the values.yaml

extraVolumes: |
  - name: keycloak-init-realm
    configMap:
      name: governance-local-realm
  - name: themes
    emptyDir: { }
#   -- Add here your `extraVolumes`

extraVolumeMounts: |
  - name: keycloak-init-realm
    mountPath: "/opt/keycloak/data/import"
    readOnly: true
  - name: themes
    mountPath: /opt/keycloak/themes
# -- Add here your `extraVolumeMounts`

extraInitContainers: |
  - name: theme-provider
    image: registry.axual.io/opensource/images/axual/keycloak-themes:0.1.1
    imagePullPolicy: IfNotPresent
    command:
      - sh
    args:
      - -c
      - |
        echo "Copying themes..."
        cp -R /axual-themes/* /themes
    volumeMounts:
      - name: themes
        mountPath: /themes
# -- Add here your `extraInitContainers`

Configuring Certificate Authority (CA) to Keycloak’s Truststore

Sometimes custom Certificate Authority (CA) needs to be configured to enable Keycloak to connect to a third party/external service.

To do so, you need to have the additional extra Certificate Authority (CA) in a p12 file with a password.

Then you can create a kubernetes secret from that file.

Finally, you can configure the extraVolumes, extraVolumeMounts and extraEnv to use the kubernetes secret.

A working example looks like the below:

k8s-secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: keycloak-extra-ca
type: Opaque
data:
  keycloak-extra-ca.p12: [base64 encoded p12 file]

k8s-values.yaml

extraVolumes: |
  # Default `extraVolumes`
  - name: keycloak-init-realm
    configMap:
      name: governance-local-realm
  - name: themes
    emptyDir: { }
  # new `extraVolume` to mount the k8s-secret
  - name: extra-ca-certs
    secret:
      secretName: keycloak-extra-ca

extraVolumeMounts: |
  # Default `extraVolumeMounts`
  - name: keycloak-init-realm
    mountPath: "/opt/keycloak/data/import"
    readOnly: true
  - name: themes
    mountPath: /opt/keycloak/themes
  # new `extraVolumeMounts` to mount the k8s-secret
  - name: extra-ca-certs
    mountPath: /etc/keystores

extraEnv: |
  # updated `extraEnv` with ssl values
  - name: JAVA_OPTS_APPEND
    value: -Djavax.net.ssl.trustStore=/etc/keystores/keycloak-extra-ca.p12 -Djavax.net.ssl.trustStorePassword=[your-p12-file-passowrd] -Djgroups.dns.query={{ template "keycloak.serviceDnsName" . }}

Control Keycloak Admin console Access

By default, the Keycloak deployed as part of the platform has its ingress disabled. This will restrict access to the Keycloak Admin console.

To open up access to the Keycloak Admin console, you will need to enable its ingress.

values.yaml

axual-governance:
  keycloak:
    # This control access to the Keycloak Admin Console
    ingress:
      enabled: true
      ingressClassName: "nginx"
      rules:
        - # -- The fully qualified domain name of a network host.
          host: "keycloak.host"
          paths:
            - # -- Matched against the path of an incoming request.
              path: "/auth"
              # -- Determines the interpretation of the Path matching.
              # Can be one of the following values: `Exact`, `Prefix`, `ImplementationSpecific`.
              pathType: "ImplementationSpecific"
      tls:
        - secretName: "existing-ingress-cert"
          hosts:
            - "keycloak.host"

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

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

Realm Settings

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

You can also refer to the public Keycloak Documentation

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	30 minutes	Time a Session is allowed to be idle
SSO Session Max	10 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

Parameter

Default

Description

SSO Session Idle

30 minutes

Time a Session is allowed to be idle

SSO Session Max

10 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