docs: Add note for group name handling

https://www.keycloak.org/docs/latest/server_admin/#user-profile

.gitignore

@@ -0,0 +1,3 @@
+/data
+/.env
+/backup

Containerfile.keycloak

@@ -0,0 +1,12 @@
+ARG KEYCLOAK_VERSION
+FROM quay.io/keycloak/keycloak:${KEYCLOAK_VERSION} as builder
+
+RUN /opt/keycloak/bin/kc.sh build --features-disabled=impersonation --db=postgres --features=declarative-user-profile
+
+FROM quay.io/keycloak/keycloak:${KEYCLOAK_VERSION}
+WORKDIR /opt/keycloak
+COPY --from=builder /opt/keycloak/ /opt/keycloak/
+ENV KC_DB_URL=keycloak_db
+
+ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]
+CMD ["start", "--optimized"]

README.md

@@ -1,2 +1,34 @@
-# keycloak-deployment
+# 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`.

backup.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+time=$(date +"%Y-%m-%dT%H:%M:%S%z")
+dir=backup
+[ -d "${dir}" ] || mkdir -p "${dir}"
+docker compose run --rm -u postgres keycloak_db sh -c 'PGPASSWORD=$POSTGRES_PASSWORD pg_dump -h keycloak_db -p 5432 -U $POSTGRES_USER keycloak' > "${dir}/${time}.sql"
+# to restore: pg_restore -d newdb db.dump

compose.yml

@@ -0,0 +1,38 @@
+version: '3.9'
+
+services:
+  keycloak_db:
+    image: postgres:${POSTGRES_VERSION}
+    restart: always
+    environment:
+      - POSTGRES_DB=keycloak
+      - POSTGRES_USER=${KC_DB_USERNAME}
+      - POSTGRES_PASSWORD=${KC_DB_PASSWORD}
+    volumes:
+      - ./data/postgres:/var/lib/postgresql/data
+
+  keycloak:
+    build:
+      dockerfile: Containerfile.keycloak
+      args:
+        KEYCLOAK_VERSION: ${KEYCLOAK_VERSION}
+    depends_on:
+      - keycloak_db
+    environment:
+      - KC_HEALTH_ENABLED=true
+      - KC_DB=postgres
+      - KC_DB_URL=jdbc:postgresql://keycloak_db:5432/keycloak
+      - KC_DB_URL_DATABASE=keycloak
+      - KC_PROXY_ADDRESS_FORWARDING=true
+      - KC_HOSTNAME_STRICT_HTTPS=false
+      - KC_PROXY=edge
+      - KC_HTTP_ENABLED=true
+      - KC_HOSTNAME_STRICT=false
+      - KC_HOSTNAME=${KC_HOSTNAME}
+      - KC_DB_USERNAME=${KC_DB_USERNAME}
+      - KC_DB_PASSWORD=${KC_DB_PASSWORD}
+      - KEYCLOAK_ADMIN=${KEYCLOAK_ADMIN}
+      - KEYCLOAK_ADMIN_PASSWORD=${KEYCLOAK_ADMIN_PASSWORD}
+    restart: always
+    ports:
+      - 8080:8080

sample.env

@@ -0,0 +1,7 @@
+KEYCLOAK_VERSION=22.0
+KEYCLOAK_ADMIN=idpadmin
+KEYCLOAK_ADMIN_PASSWORD=
+KC_DB_USERNAME=ctbkidpdb
+KC_DB_PASSWORD=
+KC_HOSTNAME=idp.ctbk.de
+POSTGRES_VERSION=16.0