Working with Keycloak

Overview

Keycloak frequently asked questions.

How to get Keycloak Admin Password

When Kublr sets up Kublr Platform, it automatically generates a password for the admin user. This password is saved as a Kubernetes secret, so that the Kublr Administrator can use it to log in to the Keycloak Console.

Pre-requisites

You need the following executables available in your path:

kubectl
base64

Getting the Password

On Linux:

echo $(kubectl get secret -n kublr kcp-keycloak-secret -o jsonpath='{.data.password}' | base64 -d)

On MacOS:

echo $(kubectl get secret -n kublr kcp-keycloak-secret -o jsonpath='{.data.password}' | base64 -D)

The link to Keycloak is available on the System Cluster Overview tab.

The Secret object storing the KeyCloak master password changed between Kublr 1.16 and 1.17 releases, so for pre-1.17 Kublr use the following commands:

# Linux
echo $(kubectl get secret -n kublr kcp-keycloak-master -o jsonpath='{.data.keycloakPass}' | base64 -d)

# MacOS
echo $(kubectl get secret -n kublr kcp-keycloak-master -o jsonpath='{.data.keycloakPass}' | base64 -D)

Users Migration

User migration may be necessary when upgrading Kublr Control Plane to a new minor version (e.g. from 1.17 to 1.18 or from 1.18 to 1.19). Please contact Kublr support team to plan critical (e.g. production) environments upgrade.

Backup (Export) Users from an Old Keycloak deployment

Open shell into the previous KCP version keyclock pod:
```
kubectl exec -it kcp-keycloak-0 -n kublr bash
```

Execute:

/opt/jboss/keycloak/bin/standalone.sh \
        -Dkeycloak.migration.action=export \
        -Dkeycloak.migration.provider=dir \
        -Dkeycloak.migration.dir=/tmp/keycloak-export \
        -Dkeycloak.migration.usersExportStrategy=DIFFERENT_FILES \
        -Dkeycloak.migration.realmName=kublr-ui \
        -Djboss.http.port=8888 \
        -Djboss.https.port=9999 \
        -Djboss.management.http.port=7777

Two files are created in /tmp/keycloak-export:

kublr-ui-realm.json
kublr-ui-users-0.json

Copy both files to the local machine for further use.

Restore Users in a New Keycloak deployment

Login to Keycloak using admin username and master password.
Select the kublr-ui realm.
Please ensure that the Clients section contains all the client objects from the old Keycloak. Otherwise, perform the steps below:
- To upload missing clients from old Keycloak, run:
```
jq '{ "clients": .clients }' kublr-ui-realm.json > kublr-ui-clients.json
```
- Import kublr-ui-clients.json into kublr-ui realm in with If a resource exists set to “Skip” mode.
Please ensure that Groups section contains all groups from old keycloak. Otherwise, perform the steps below:
- To upload missing groups from old Keycloak, run:
```
jq '{ "groups": .groups }' kublr-ui-realm.json > kublr-ui-groups.json
```
- Import kublr-ui-groups.json into kublr-ui realm in with If a resource exists set to “Skip” mode.
Go to Import, select kublr-ui-users-0.json file from your local machine.
Set If a resource exists to “Skip”.
Click the Import button. Users will be imported, some of them (existing) will be skipped.

Known Issues

You can get “Script upload is disabled” error in the process of importing objects:

Keycloak - Partial Import - Error

Workaround: go to KCP cluster and modify Keycloak StateFullSet env section and restart the keycloak pod:

...
      containers:
        - name: keycloak
          image: 'jboss/keycloak:10.0.0'
          command:
            - /scripts/keycloak.sh
          env:
            - name: JAVA_OPTS
              value: "-Dkeycloak.profile.feature.scripts=enabled -Dkeycloak.profile.feature.upload_scripts=enabled"
...