# 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`.