Add startup entrypoint to fix realm import bugs and enable portable hostnames

Keycloak's realm import silently drops the config for the 'username'
protocol mapper in the 'profile' client scope, reverting it to defaults.
The realm JSON also has redirect URIs and web origins hardcoded to a
specific hostname, making the image non-portable across environments.

This adds an entrypoint script that wraps kc.sh, waits for the realm
import to complete, then idempotently patches the mapper config and
(when SERVER_HOST is set) rewrites client URIs to match the deployment
hostname.

See: keycloak/keycloak#36065
See: keycloak/keycloak#16289

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: matthewhorridge

.github/workflows/release.yaml

@@ -30,10 +30,8 @@ jobs:
         run: |
           VERSION=${{ steps.get-version.outputs.version }}
           find . -name 'pom.xml' -exec mvn versions:set -DnewVersion=$VERSION -DgenerateBackupPoms=false -f {} \;
-      - name: Build SPI plugin
-        run: mvn --batch-mode -pl spi clean package
       - name: Build and push Docker image
-        run: mvn --batch-mode package install
+        run: mvn --batch-mode install
       - name: Release
         uses: softprops/action-gh-release@v1
         env:

.github/workflows/test.yaml

@@ -0,0 +1,15 @@
+name: Test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build image
+        run: docker build -t protegeproject/webprotege-keycloak:test .
+      - name: Run entrypoint integration test
+        run: ./test-entrypoint.sh

Dockerfile

@@ -1,5 +1,23 @@
+FROM alpine:3 AS tools
+ARG TARGETARCH
+RUN wget -O /usr/local/bin/jq \
+      "https://github.com/jqlang/jq/releases/download/jq-1.7.1/jq-linux-${TARGETARCH}" \
+    && chmod +x /usr/local/bin/jq
+
+FROM maven:3.9-eclipse-temurin-17 AS spi-builder
+WORKDIR /build
+COPY spi/pom.xml .
+RUN mvn dependency:go-offline -B
+COPY spi/src ./src
+RUN mvn package -B -DskipTests
+
 FROM keycloak/keycloak:26.1
+COPY --from=tools /usr/local/bin/jq /usr/bin/jq
 COPY ./webprotege /opt/keycloak/themes/webprotege
-COPY ./spi/target/webprotege-credential-check-authenticator-*.jar /opt/keycloak/providers/
+COPY --from=spi-builder /build/target/webprotege-credential-check-authenticator-*.jar /opt/keycloak/providers/
 COPY ./webprotege.json /opt/keycloak/import/webprotege.json
+COPY --chmod=755 ./entrypoint.sh /opt/keycloak/bin/entrypoint.sh
+
 RUN /opt/keycloak/bin/kc.sh build
+
+ENTRYPOINT ["/opt/keycloak/bin/entrypoint.sh"]

README.md

@@ -8,39 +8,69 @@ Keycloak configuration for WebProtege. This repository contains:
 
 ## Prerequisites
 
-- Java 17+
-- Maven 3.8+
 - Docker
 
-## Building the Plugin
+## Docker Build
+
+The `Dockerfile` uses a multi-stage build to compile the authenticator plugin,
+download tools, and package the theme, realm configuration, and startup
+entrypoint into a custom Keycloak image.  No local Java or Maven installation
+is required.
 
-The authenticator plugin must be built before deploying Keycloak:
+To build locally:
 
 ```bash
-cd spi
-mvn clean package
+docker build -t protegeproject/webprotege-keycloak:1.2.0 .
 ```
 
-This produces `spi/target/webprotege-credential-check-authenticator-1.0.0.jar`.
+## Startup Entrypoint
 
-## Docker Build
+The image includes a custom entrypoint script (`entrypoint.sh`) that wraps the
+standard Keycloak startup.  It starts Keycloak normally, waits for the realm
+import to complete, then applies two configuration patches that cannot be
+achieved through the realm import alone.
 
-The `Dockerfile` packages the theme, plugin, and realm configuration into a custom Keycloak image:
+### 1. Protocol Mapper Fix
 
-```dockerfile
-FROM keycloak/keycloak:26.1
-COPY ./webprotege /opt/keycloak/themes/webprotege
-COPY ./spi/target/webprotege-credential-check-authenticator-1.0.0.jar /opt/keycloak/providers/
-COPY ./webprotege.json /opt/keycloak/import/webprotege.json
-RUN /opt/keycloak/bin/kc.sh build
-```
+Keycloak's realm import mechanism has a known limitation: it silently drops the
+`config` dictionary for certain protocol mapper types.  The realm JSON defines a
+`username` mapper in the `profile` client scope that maps the custom user
+attribute `webprotege_username` to the `preferred_username` JWT claim.  After
+import, Keycloak reverts this mapper to its built-in default, which maps the
+Keycloak username field instead.
 
-To build locally:
+This matters because WebProtege uses email addresses as Keycloak usernames, but
+internal application lookups rely on the original MongoDB user ID stored in the
+`webprotege_username` attribute.  Without the fix, the backend receives email
+addresses where it expects user IDs, breaking user resolution.
 
-```bash
-cd spi && mvn clean package && cd ..
-docker build -t protegeproject/webprotege-keycloak:1.0.0 .
-```
+The entrypoint detects this condition on each startup and, if the mapper is in
+the wrong state, deletes it and recreates it with the correct configuration.
+On subsequent boots where the mapper is already correct, the fix is skipped.
+
+### 2. Hostname-Based Client URI Patching
+
+The realm JSON ships with a default hostname baked into the `webprotege`
+client's redirect URIs, web origins, and base URL.  Self-hosted deployments use
+different hostnames.  When the `SERVER_HOST` environment variable is set, the
+entrypoint updates these values so that:
+
+- Keycloak accepts OAuth redirects back to the correct host
+- CORS headers include the correct origin
+- The Keycloak login and account pages link back to the correct application URL
+- The realm's OpenID Connect discovery document advertises the correct issuer
+
+This makes the image portable — the same build works for local development,
+staging, and production by setting `SERVER_HOST` in the deployment environment.
+
+### Environment Variables
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `KEYCLOAK_ADMIN` | Yes | `admin` | Admin username for kcadm authentication |
+| `KEYCLOAK_ADMIN_PASSWORD` | Yes | `password` | Admin password for kcadm authentication |
+| `KC_HTTP_RELATIVE_PATH` | Yes | *(none)* | Keycloak's HTTP relative path (e.g. `/keycloak`) |
+| `SERVER_HOST` | No | *(none)* | Public hostname; when set, client URIs and the realm frontend URL are updated to match |
 
 ## Deployment