Customization

This page will describe how you can customize your Keycloak instance.

Themes and providers

VSHNKeycloak allows to use custom providers and themes. Create a custom container image and use it to customize your Keycloak instance as described below.

Example to create a Keycloak instance an image containing custom themes and providers

apiVersion: vshn.appcat.vshn.io/v1
kind: VSHNKeycloak
metadata:
  name: keycloak-app1-prod
  namespace: prod-app
spec:
  parameters:
    service:
      version: "26"
      customizationImage:
        image: https://registry/user/image:tag (1)
        imagePullSecretRef:
          name: secret-name (2)
          namespace: secret-namespace (3)
    size:
      plan: standard-2
  writeConnectionSecretToRef:
    name: keycloak-creds

1	Container image url.
2	Secret name containing credentials for the registry.
3	Secret namespace

Configuration

You can provide a custom configuration to Keycloak using a ConfigMap. The content of the ConfigMap is a JSON file based on the Keycloak export files. You can logically separate different configurations inside the ConfigMap by using different keys. However, each key must end in .json.

The configuration will be read during the startup of Keycloak and loaded into the database.

An extensive set of configuration examples can be found here.

The configuration also supports variable substitution.

Variables exposed by Spring Boot (through configtree or external configuration) can be accessed by $(property.name)

In additional, the string substitution support multiple prefixes for different approaches:

Base64 Decoder:        $(base64Decoder:SGVsbG9Xb3JsZCE=)
Base64 Encoder:        $(base64Encoder:HelloWorld!)
Java Constant:         $(const:java.awt.event.KeyEvent.VK_ESCAPE)
Date:                  $(date:yyyy-MM-dd)
DNS:                   $(dns:address|apache.org)
Environment Variable:  $(env:USERNAME)
File Content:          $(file:UTF-8:src/test/resources/document.properties)
Java:                  $(java:version)
Localhost:             $(localhost:canonical-name)
Properties File:       $(properties:src/test/resources/document.properties::mykey)
Resource Bundle:       $(resourceBundle:org.example.testResourceBundleLookup:mykey)
Script:                $(script:javascript:3 + 4)
System Property:       $(sys:user.dir)
URL Decoder:           $(urlDecoder:Hello%20World%21)
URL Encoder:           $(urlEncoder:Hello World!)
URL Content (HTTP):    $(url:UTF-8:http://www.apache.org)
URL Content (HTTPS):   $(url:UTF-8:https://www.apache.org)
URL Content (File):    $(url:UTF-8:file:///$(sys:user.dir)/src/test/resources/document.properties)
XML XPath:             $(xml:src/test/resources/document.xml:/root/path/to/node)

Example

The following example demonstrates how a custom configuration that creates a new realm looks like:

Configmap definition for a custom realm to be created when starting up keycloak.

apiVersion: v1
kind: ConfigMap
metadata:
  name: keycloak-app1-prod-config
  namespace: prod-app
data:
  keycloak-config.json: |
    {
      "enabled": true,
      "realm": "prod-app"
    }

Keycloak instance with custom configuration

apiVersion: vshn.appcat.vshn.io/v1
kind: VSHNKeycloak
metadata:
  name: keycloak-app1-prod
  namespace: prod-app
spec:
  parameters:
    service:
      customConfigurationRef: keycloak-app1-prod-config (1)

1	The name of the `ConfigMap`. Must be in the same namespace as the Keycloak claim.

Environment variables

You can pass custom environment variables to your Keycloak instance. Those can then either be used by your custom providers or by your custom configuration.

Example

The following example demonstrates how a custom configuration that creates a new realm and uses environment variables looks like:

Secret containing a custom environment variable

apiVersion: v1
kind: Secret
metadata:
  name: keycloak-app2-prod-env
  namespace: prod-app
stringData:
  REALM_NAME: prod-app
type: Opaque

Configmap definition referencing an environmental variable

apiVersion: v1
kind: ConfigMap
metadata:
  name: keycloak-app2-prod-config
  namespace: prod-app
data:
  keycloak-config.json: |
    {
      "enabled": true,
      "$(env:REALM_NAME)"
    }

Keycloak instance with custom configuration and environment variables

apiVersion: vshn.appcat.vshn.io/v1
kind: VSHNKeycloak
metadata:
  name: keycloak-app2-prod
  namespace: prod-app
spec:
  parameters:
    service:
      customConfigurationRef: keycloak-app2-prod-config (1)
      customEnvVariablesRef: keycloak-app2-prod-env (2)

1	The name of the `ConfigMap`. Must be in the same namespace as the Keycloak claim.
2	The name of the `Secret` that contains the environment variables. Must be in the same namespace as the Keycloak claim.