-
Notifications
You must be signed in to change notification settings - Fork 235
Upgrade Keycloak on Docker
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:24.0.4) and LDAP (dcm4che/slapd-dcm4chee:2.6.6-32.0) images. Note: These upgrade steps are effective only for Keycloak setups with LDAP User Federation
Initial few upgrade steps are common irrespective of which LDAP version one is upgrading from.
$ 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
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 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, 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.6-32.0
$ docker run --network=default --name keycloak \
-p 8880:8880 \
-p 8843:8843 \
-e ARCHIVE_HOST=vrinda-pc \
-e KC_HOSTNAME=vrinda-pc \
-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:24.0.4
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.6-32.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:24.0.4
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
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.
- Upgrading from LDAP 2.4.57-23.3 (or lower)
- Upgrading from LDAP 2.4.57-24.0 (or higher)
- Upgrading from LDAP 2.4.57-23.3 (or lower) with externalized DB
- Upgrading from LDAP 2.4.57-24.0 (or higher) 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 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.
- 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.
- 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
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.
Name: account Mapper Type: role-ldap-mapper LDAP Roles DN: ou=account,dc=dcm4che,dc=org Use Realm Roles Mapping: OFF Client ID: account
- 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.
- 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
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.
Name: account Mapper Type: role-ldap-mapper LDAP Roles DN: ou=account,dc=dcm4che,dc=org Use Realm Roles Mapping: OFF Client ID: account
- 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.
DCM4CHEE 5 Documentation