Keycloak Deployment

This repos contains all files required to deploy the keycloak service using docker-compose.

The deployment is tailored towards a setup using postgres as the database and running keycloak behind a reverse proxy using HTTP. If you want to use it with any other configuration, you will have to adapt the compose file. Furthermore, the setup utilizes a custom Keycloak image that is built without impersonation features.

Setup

Copy the sample.env file into a .env file and choose secure passwords. Then run docker compose up -d

Updating

Change the Postgres and Keycloak version in your .env file and run docker compose build (only required for updating Keycloak). Then run docker compose up -d again.

Configuration

The Keycloak configuration is not quite straight forward, which is why the following section contains some configuration examples. It is recommended to create a custom realm first instead of simply using the master realm.

Map groups to OIDC claims

To handle authorization centrally, groups can be created and assigned directly in Keycloak. Those groups are not sent to the OIDC client by default. To enable such functionality, create a new client scope named groups. For this scope, add a new mapper ('By Configuration') and select 'Group Membership'. Give it a descriptive name and set the token claim name to groups.

For each client that relies on those group, explicitly add the groups scope to client scopes. The groups will now be sent to client upon request.

Note: A group named foo will be displayed as /foo. For this reason, I recommend using group names like appname/rolename which will be sent to the client as /appname/rolename.

Enforcing 2FA

In the realm management console under Authentication > Required Actions certain actions can be enabled and set to be the default action. Useful defaults might be to enforce Configure OTP, Update Password, Update Profile and Verify Email.

Creating a realm admin

Managing the custom realm can happen by using the global Keycloak admin, but it might make more sense to create per-realm admins. To do so, a new Realm Role can be added (e.g. named realm-admin). After creating this role, the action Add associated roles can be chosen. Choose to filter by clients and search for realm-management. Then choose all of the given roles and assign them to the realm-admin role. This role can be added to a given user under the Role Mapping tab in the users profile. Afterwards, the given realm can be managed using its web console on https://<keycloak>/admin/<realm>/console.