jeffersonlab/keycloak repository overview

⁠keycloak

Configurable Keycloak⁠ Docker image and bash setup scripts.

• Overview⁠
• Quick Start with Compose⁠
• Configure⁠
• Release⁠

⁠Overview

This project provides a docker image which extends the production-oriented keycloak⁠ and adds features for development and testing. The Jefferson Lab image sets up a Docker healthcheck and Docker entrypoint, installs client tools (see kc-lib.sh⁠), and adds some default configuration for the Jefferson Lab environment. The entrypoint integrates with the healthcheck such that the container is "healthy" only when keycloak is both running and configured. Configuration is supported via environment variables and a conventional directory named /container-entrypoint-initdb.d of bash scripts that can be overwritten by mounting a volume.

• 1.x version based on Keycloak 20.x
• 2.x version based on Keycloak 26.x

⁠Quick Start with Compose

1. Grab project

git clone https://github.com/JeffersonLab/keycloak
cd keycloak

1. Launch Compose⁠

docker compose up

1. Navigate to admin console

http://localhost:8081/auth

Note: Login with username admin and password admin

⁠Configure

Mount a volume at /container-entrypoint-initdb.d containing bash scripts to run, ordered by name ascending. See example⁠. Mount a subdirectory (e.g. 99-conf.d) or individual files in this location to keep default config as overriding the /container-entrypoint-initdb.d/ will overwrite the default configuration.

Environment variables:

Notes on Default Configuration:

• Additional environment variables are set in 00_config.env⁠. These can only be overridden by replacing this file or providing an additional env file to be sourced after.
• Each client will use the same client_secret: yHi6W2raPmLvPXoxqMA7VWbLAA2WN0eB
• Four users are created all with the password password: jadams, jdoe, jsmith, and tbrown
• All users have ${KC_RESOURCE}-user role. jdoe and tbrown have ${KC_RESOURCE}-admin role
• Client has KC_UPDATE_CLIENT_ROLES_MAPPER unset by default

Notes on Setup and Persistence:

• The setup scripts run once, after Keycloak first starts, and then the entrypoint writes a setup-complete marker file. The container is healthy only once the marker exists and Keycloak responds at KC_BACKEND_URL.
• With the default embedded (dev-file) database the marker is written to /opt/keycloak/data/setup-complete, next to the database. If you mount a volume at /opt/keycloak/data, a recreated container keeps its realm and skips setup. Without a volume, a new container starts fresh and runs setup again.
• With an external database (e.g. KC_DB=oracle) the marker is written to /opt/keycloak/setup-complete, in the container itself, so a recreated container runs the setup scripts again against the existing database. Set KC_SKIP_DEFAULT_SETUP=true (or make your own scripts idempotent) if the database outlives the container.
• The entrypoint runs until Keycloak exits and then exits with Keycloak's status, so Docker restart policies (e.g. restart: unless-stopped) apply if Keycloak stops. docker stop is passed on to Keycloak for a clean shutdown.

Notes on LDAP:

• create_ldap_storage_provider names the provider ${KC_REALM}-ldap-provider, and gives it a component ID from KC_PROVIDER_ID or else derived from KC_REALM. With KC_IMPORT off, each user's ID (the sub claim) is f:<component ID>:<username>, which stays the same when Keycloak is reinstalled from scripts. Changing the component ID changes every user's ID, which breaks clients that store it.
• Keycloak logs The given key is not a valid key per specification at each login when the component ID is not a UUID or exactly 22 characters of letters, digits, _ and -.
• With KC_IMPORT off, users and their memberships are read from LDAP, but you must sync new LDAP groups by hand. Keycloak's scheduled sync, which also creates roles, only runs with import on, and the admin console disables the provider's sync actions. A new group has no Keycloak role until a sync runs or one of its members logs in. After adding a group, or on your own schedule, call run_user_storage_sync, or sync only the role mapper, with your realm in place of ace:

  kcadm.sh create "user-storage/$(kcadm.sh get components -r ace -q name=ace-ldap-provider --fields id | jq -r .[0].id)/mappers/ace-ldap-role-mapper/sync?direction=fedToKeycloak" -r ace
  

  Copy
  Syncing only adds roles: a role whose group was removed from LDAP stays in Keycloak until you delete it.

⁠Release

1. Bump the version number in the VERSION file and commit and push to GitHub (using Semantic Versioning⁠).
2. The CD⁠ GitHub Action should run automatically invoking:
   • The Create release⁠ GitHub Action to tag the source and create release notes summarizing any pull requests. Edit the release notes to add any missing details.
   • The Publish docker image⁠ GitHub Action to create a new demo Docker image.