41 lines
1.7 KiB
Markdown
41 lines
1.7 KiB
Markdown
## 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. |