Skip to content

Upgrade Keycloak on Docker

Jump to bottom Edit New page
Gunter Zeilinger edited this page Sep 23, 2024 · 12 revisions

Overview

Following page guides users with upgrading their application setups (connected to Keycloak 11.0.3 or lower versions) to Keycloak version 18+.

Starting with Keycloak 12+ versions, Keycloak no longer initializes default client scopes of standard clients on realm import. This causes Forbidden error whenever users login to their account console. To work around this issue, latest LDAP images from dcm4chee contain scripts to initialize and add account permissions to default users as well as any other users added previously in Keycloak.

Starting with Keycloak 18+ versions based on Quarkus distribution, there are several significant configuration changes involving environment variables. Complete list of environment variables new Keycloak image can be found here

Upgrade steps differ slightly depending upon which LDAP version one is upgrading from, as well as the type of DB backend used for Keycloak. Ensure to upgrade to latest Keycloak (dcm4che/keycloak:25.0.5) and LDAP (dcm4che/slapd-dcm4chee:2.6.7-33.0) images. Note: These upgrade steps are effective only for Keycloak setups with LDAP User Federation

Upgrade Steps

Initial few upgrade steps are common irrespective of which LDAP version one is upgrading from.

Stop and remove containers with previous version

$ docker stop ldap keycloak
ldap
keycloak
$ docker rm -v ldap keycloak
ldap
keycloak

or using Docker Composite

$ docker-compose down
Stopping keycloak_1  ... done
Stopping ldap_1 ... done
Removing keycloak_1  ... done
Removing ldap_1 ... done
Removing network default

External DB

If Keycloak is connected to an external DB (eg. mariadb), stop and remove database container as well.

$ docker stop ldap mariadb keycloak
ldap
mariadb
keycloak
$ docker rm -v ldap mariadb keycloak
ldap
mariadb
keycloak

or using Docker Composite

$ docker-compose down
Stopping keycloak_1  ... done
Stopping mariadb_1  ... done
Stopping ldap_1 ... done
Removing keycloak_1  ... done
Removing mariadb_1  ... done
Removing ldap_1 ... done
Removing network default

Remove previous mapped out Keycloak volume

Remove or rename the directory, which was mapped to /opt/keycloak/standalone, e.g.:

$ sudo mv /var/local/dcm4chee-arc/keycloak /tmp

Note: Retain the mapped out LDAP volume

Run new version of OpenLDAP and Keycloak Servers

Run new version of OpenLDAP and Keycloak servers, mounting the same host directories as used with the previous version.

Note: Ensure to set the environment variables on startup of new Keycloak.

E.g.:

$ docker run --network=default --name ldap \
           -p 389:389 \
           -e ARCHIVE_HOST=vrinda-pc \
           -v /etc/localtime:/etc/localtime:ro \
           -v /etc/timezone:/etc/timezone:ro \
           -v /var/local/dcm4chee-arc/ldap:/var/lib/openldap/openldap-data \
           -v /var/local/dcm4chee-arc/slapd.d:/etc/openldap/slapd.d \
           -d dcm4che/slapd-dcm4chee:2.6.7-33.0
           
$ docker run --network=default --name keycloak \
           -p 8880:8880 \
           -p 8843:8843 \
           -e ARCHIVE_HOST=vrinda-pc \
           -e KC_HOSTNAME=https://vrinda-pc:8843 \
           -e KC_HTTP_PORT=8880 \
           -e KC_HTTPS_PORT=8843 \
           -e DEBUG=true \
           -e KC_HTTP_ENABLED=true \
           -e KC_HTTP_RELATIVE_PATH=/auth \
           -e KC_LOG=file \
           -e KC_LOG_LEVEL=INFO \
           -e KEYCLOAK_ADMIN=admin \
           -e KEYCLOAK_ADMIN_PASSWORD=changeit \
           -e KEYCLOAK_WAIT_FOR=ldap:389 \
           -v /etc/localtime:/etc/localtime:ro \
           -v /etc/timezone:/etc/timezone:ro \
           -v /var/local/dcm4chee-arc/keycloak/data:/opt/keycloak/data \
           -v /var/local/dcm4chee-arc/keycloak/themes:/opt/keycloak/themes \
           -d dcm4che/keycloak:25.0.5

If using Docker Compose adjust the version tags of the images in docker-compose.yaml and environment variables accordingly,

version: "3"
services:
  ldap:
    image: dcm4che/slapd-dcm4chee:2.6.7-33.0
    logging:
      driver: json-file
      options:
        max-size: "10m"
    ports:
      - "389:389"
    environment:
      STORAGE_DIR: /storage/fs1
    volumes:
      - /var/local/dcm4chee-arc/ldap:/var/lib/openldap/openldap-data
      - /var/local/dcm4chee-arc/slapd.d:/etc/openldap/slapd.d
  keycloak:
    image: dcm4che/keycloak:25.0.5
    logging:
      driver: json-file
      options:
        max-size: "10m"
    ports:
      - "8880:8880"
      - "8843:8843"
    environment:
      KC_HTTP_PORT: 8880
      KC_HTTPS_PORT: 8843
      ARCHIVE_HOST: vrinda-pc
      KC_HOSTNAME: vrinda-pc
      KC_HOSTNAME_BACKCHANNEL_DYNAMIC: "true"
      DEBUG: "true"
      KC_HTTP_ENABLED: "true"
      KC_HTTP_RELATIVE_PATH: /auth
      KC_LOG: file
      KC_LOG_LEVEL: INFO
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: changeit
      KEYCLOAK_WAIT_FOR: ldap:389
    depends_on:
      - ldap
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone:ro
      - /var/local/dcm4chee-arc/keycloak/data:/opt/keycloak/data
      - /var/local/dcm4chee-arc/keycloak/themes:/opt/keycloak/themes

before starting the OpenLDAP and Keycloak servers by

$ docker-compose -p default up -d ldap keycloak
Creating network "default" with the default driver
Creating ldap_1 ... done
Creating keycloak_1 ... done

Note: Replace vrinda-pc with hostnames of your archive / keycloak.

Upgrade Steps based on previous LDAP version / DB backend

Upgrading from LDAP 2.4.57-23.3 (or lower)

  • Initialize account for default admin user. 
    $ docker exec ldap_1 init-account admin
adding new entry "ou=account,dc=dcm4che,dc=org"

adding new entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

adding new entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"
  • Add account permissions to other default user i.e. to user user 
    $ docker exec ldap_1 add-account user
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"
  • For all other additional users previously configured in Keycloak, repeat the add-account script for each of the users. 
    $ docker exec ldap_1 add-account my_user1
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"

    $ docker exec ldap_1 add-account my_user2
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"
    ........ 
    $ docker exec ldap_1 add-account my_user10
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"
  • Login to Keycloak admin console at http[s]://<KC_HOSTNAME>:<KC_HTTP[S]_PORT>/<KC_RELATIVE_PATH>/admin/dcm4che/console and Synchronize all users in ldap User Federation.
  • In Role Mappings tab of each user, select account in Client Roles and verify 
    Assigned Roles: manage-account
             view-profile
Effective Roles: manage-account
              manage-account-links
              view-profile
  • Login to account console at http[s]://<KC_HOSTNAME>:<KC_HTTP[S]_PORT>/<KC_RELATIVE_PATH>/realms/dcm4che/account. User should be able to login and navigate to Personal Info section to edit account details.

Upgrading from LDAP 2.4.57-24.0 (or higher)

  • Initializing account for default users is not required, as the ldap images starting from 2.4.57-24.0 already enables it at startup.
  • For all other additional users previously configured in Keycloak, repeat the add-account script for each of the users. 
    $ docker exec ldap_1 add-account my_user1
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"

    $ docker exec ldap_1 add-account my_user2
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"
    ........ 
    $ docker exec ldap_1 add-account my_user10
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"
  • Login to Keycloak admin console at http[s]://<KC_HOSTNAME>:<KC_HTTP[S]_PORT>/<KC_RELATIVE_PATH>/admin/dcm4che/console and Synchronize all users in ldap User Federation.
  • In Role Mappings tab of each user, select account in Client Roles and verify 
    Assigned Roles: manage-account
             view-profile
Effective Roles: manage-account
              manage-account-links
              view-profile
  • Login to account console at http[s]://<KC_HOSTNAME>:<KC_HTTP[S]_PORT>/<KC_RELATIVE_PATH>/realms/dcm4che/account. User should be able to login and navigate to Personal Info section to edit account details.

Upgrading from LDAP 2.4.57-23.3 (or lower) with externalized DB

  • Initialize account for default admin user. 
    $ docker exec ldap_1 init-account admin
adding new entry "ou=account,dc=dcm4che,dc=org"

adding new entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

adding new entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"
  • Add account permissions to other default user i.e. to user user 
    $ docker exec ldap_1 add-account user
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"
  • For all other additional users previously configured in Keycloak, repeat the add-account script for each of the users. 
    $ docker exec ldap_1 add-account my_user1
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"

    $ docker exec ldap_1 add-account my_user2
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"
    ........ 
    $ docker exec ldap_1 add-account my_user10
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"
  • Login to Keycloak admin console at http[s]://<KC_HOSTNAME>:<KC_HTTP[S]_PORT>/<KC_RELATIVE_PATH>/admin/dcm4che/console and navigate to ldap User Federation.
  • Create an account mapper with following details 
    Name: account
Mapper Type: role-ldap-mapper
LDAP Roles DN: ou=account,dc=dcm4che,dc=org
Use Realm Roles Mapping: OFF
Client ID: account
    Note: Default pre-selected value of account in Client ID dropdown is not effective due to a Keycloak bug. Hence, explicitly select the account value in this dropdown before saving the mapper configuration.
  • Once the mapper configuration is created, Sync LDAP Roles to Keycloak
  • Going back to ldap User Federation settings, Synchronize all users.
  • For Clients account, account-console, admin-cli and security-admin-console, assign the Default and Optional Client Scopes 
    Default Client Scopes:  acr
                        email
                        profile
                        roles
                        web-origins
Optional Client Scopes: address
                        microprofile-jwt
                        offline_access
                        phone
  • In Role Mappings tab of each user, select account in Client Roles and verify 
    Assigned Roles:  manage-account
                 view-profile
Effective Roles: manage-account
                 manage-account-links
                 view-profile
  • Login to account console at http[s]://<KC_HOSTNAME>:<KC_HTTP[S]_PORT>/<KC_RELATIVE_PATH>/realms/dcm4che/account. User should be able to login and navigate to Personal Info section to edit account details.

Upgrading from LDAP 2.4.57-24.0 (or higher) with externalized DB

  • Initializing account for default users is not required, as the ldap images starting from 2.4.57-24.0 already enables it at startup.
  • For all other additional users previously configured in Keycloak, repeat the add-account script for each of the users. 
    $ docker exec ldap_1 add-account my_user1
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"

    $ docker exec ldap_1 add-account my_user2
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"
    ........ 
    $ docker exec ldap_1 add-account my_user10
modifying entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"

modifying entry "cn=manage-account,ou=account,dc=dcm4che,dc=org"
  • Login to Keycloak admin console at http[s]://<KC_HOSTNAME>:<KC_HTTP[S]_PORT>/<KC_RELATIVE_PATH>/admin/dcm4che/console and navigate to ldap User Federation.
  • Create an account mapper with following details 
    Name: account
Mapper Type: role-ldap-mapper
LDAP Roles DN: ou=account,dc=dcm4che,dc=org
Use Realm Roles Mapping: OFF
Client ID: account
    Note: Default pre-selected value of account in Client ID dropdown is not effective due to a Keycloak bug. Hence, explicitly select the account value in this dropdown before saving the mapper configuration.
  • Once the mapper configuration is created, Sync LDAP Roles to Keycloak
  • Going back to ldap User Federation settings, Synchronize all users.
  • For Clients account, account-console, admin-cli and security-admin-console, assign the Default and Optional Client Scopes 
    Default Client Scopes:  acr
                        email
                        profile
                        roles
                        web-origins
Optional Client Scopes: address
                        microprofile-jwt
                        offline_access
                        phone
  • In Role Mappings tab of each user, select account in Client Roles and verify 
    Assigned Roles:  manage-account
                 view-profile
Effective Roles: manage-account
                 manage-account-links
                 view-profile
  • Login to account console at http[s]://<KC_HOSTNAME>:<KC_HTTP[S]_PORT>/<KC_RELATIVE_PATH>/realms/dcm4che/account. User should be able to login and navigate to Personal Info section to edit account details.
Add a custom footer

DCM4CHEE 5 Documentation

Clone this wiki locally