Docker环境下如何打包并覆盖Keycloak默认SPI（自定义暴力破解检测SPI场景）

Got it, I’ve been in your shoes—getting a custom SPI working locally is straightforward, but Docker requires a different approach since we can’t edit XML config files directly at runtime. Here’s a clear, step-by-step guide using CLI scripts to make your custom SPI the default in a Keycloak Docker container:

1. Prepare Your Custom SPI JAR #

First, make sure your bw-brute-force-detector SPI is packaged as a JAR file. Place it in a local directory (e.g., ./providers) so we can copy it into the Docker image later.

2. Create a Keycloak CLI Script #

Create a CLI script (let’s name it configure-bw-spi.cli) to set up your SPI as the default. This script will tell Keycloak to enable your provider and set it as the default brute force protector.

For WildFly-based Keycloak (pre-17): #

# Configure custom brute force protector SPI
/subsystem=keycloak-server/spi=bruteForceProtector:add()
/subsystem=keycloak-server/spi=bruteForceProtector/provider=bw-brute-force-detector:add(enabled=true)
/subsystem=keycloak-server/spi=bruteForceProtector:write-attribute(name=default-provider, value=bw-brute-force-detector)

For Quarkus-based Keycloak (17+): #

Newer Keycloak versions use a simplified CLI syntax with kc.sh. You can create a bash script (e.g., configure-bw-spi.sh) instead:

#!/bin/bash
# For Keycloak 17+ (Quarkus)
/opt/keycloak/bin/kc.sh config set spi.brute-force-protector.default-provider=bw-brute-force-detector
/opt/keycloak/bin/kc.sh config set spi.brute-force-protector.bw-brute-force-detector.enabled=true

3. Build a Custom Keycloak Docker Image #

Create a Dockerfile in the same directory as your providers folder and CLI script. This will extend the official Keycloak image, add your SPI JAR, and run the configuration script during setup.

For WildFly-based Keycloak (pre-17): #

FROM quay.io/keycloak/keycloak:legacy

# Copy custom SPI JAR to Keycloak's deployments directory
COPY ./providers/bw-brute-force-detector.jar /opt/jboss/keycloak/standalone/deployments/

# Copy CLI script to Keycloak's scripts directory
COPY ./configure-bw-spi.cli /opt/jboss/keycloak/scripts/cli/

# Run the CLI script to configure the SPI, then shut down the server
RUN /opt/jboss/keycloak/bin/jboss-cli.sh --file=/opt/jboss/keycloak/scripts/cli/configure-bw-spi.cli && \
    /opt/jboss/keycloak/bin/jboss-cli.sh --command=":shutdown"

For Quarkus-based Keycloak (17+): #

FROM quay.io/keycloak/keycloak:latest

# Copy custom SPI JAR to Keycloak's providers directory
COPY ./providers/bw-brute-force-detector.jar /opt/keycloak/providers/

# Copy and execute the configuration script
COPY ./configure-bw-spi.sh /opt/keycloak/scripts/
RUN chmod +x /opt/keycloak/scripts/configure-bw-spi.sh && \
    /opt/keycloak/scripts/configure-bw-spi.sh

4. Build and Run the Docker Container #

Build the custom image: #

docker build -t custom-keycloak .

Run the container: #

For legacy WildFly version:

docker run -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin custom-keycloak

For Quarkus version (development mode):

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin custom-keycloak start-dev

5. Verify the SPI is Active #

To confirm your SPI is working:

• For WildFly: Exec into the container and check standalone-ha.xml (or standalone.xml) to see if your SPI configuration is present.
• For Quarkus: Run docker exec <container-id> /opt/keycloak/bin/kc.sh config show and look for the spi.brute-force-protector entries.

You can also test the brute force protection flow to ensure your custom logic is being triggered.

内容的提问来源于stack exchange，提问作者Djordje