---
tags:
- HowTo
---
## Keycloak Upgrade

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.