34 lines
2.6 KiB
Markdown
34 lines
2.6 KiB
Markdown
# 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`.
|