# Keycloak

Upgrading Keycloak is not so difficult as supports automatically migrating the database to a new version.

Nonetheless, Keycloak is a critical piece of software in every infrastructure. Under no circumstances you want the upgrade to fail. I will show you some upgrade preparations for a docker-based setup that ensure you can restore the service in the worst case scenario.

Before upgrading the docker image, ensure you have:

Created a database backup

Use pg_dump to dump the Keycloak database.

Exported realms including groups, roles and clients

Open the realm in the Keycloak backend navigate to Mange > Export. Tick on all options and export the realm. Repeat this process for all realms.

Stopped and renamed the old container

Stop the existing container and rename it.

docker stop $KEYCLOAKD_CONTAINER && docker rename $KEYCLOAKD_CONTAINER $NEW_NAME

In the worst case scenario we can restore the database and restore to old container and state.

# Upgrade

Executing the upgrade is simple. In my case I simply had to change the image tag to a newer version.

jboss/keycloak:9.0.2 -> jboss/keycloak:12.0.4

Avoid using the latest tag!

# Troubleshooting

After upgrade the connected OAuth clients must be tested. While doing so errors might occur due to new restrictions from the Keycloak side.

Invalid scope parameter

After the upgrade I could not longer login with one of the OAuth providers. Whenever I tried to initiate the login flow it was immediately aborted. The Keycloak log threw this error: KC-SERVICES0093: Invalid parameter value for: scope.

When I checked the login url on the client, I saw that the OAuth provider set scope=False. Explicitly setting the scope param of the OAuth provider resolved the issue.