austinderbique/keycloak-trusted-device

🛡️ Keycloak with Trusted Device Support

This image is based on the official https://github.com/keycloak/keycloak distribution and includes the https://github.com/wouterh-dev/keycloak-spi-trusted-device extension preinstalled.

The Trusted Device extension allows Keycloak to remember previously authenticated devices, so users can skip MFA on trusted devices while still enforcing it on new or unrecognized ones. This improves user experience without compromising security.

✨ Features

• Built from the official keycloak/keycloak base image.
• Includes the Trusted Device SPI for conditional MFA based on device recognition.
• Supports the full Browser with Trusted MFA authentication flow out of the box.
• Multi-arch builds: linux/amd64 and linux/arm64.
• Published automatically to Docker Hub when new Keycloak releases are available.

🏗 GitHub Repository & Build Process

This image is built and maintained in the public GitHub repository: 🔗 https://github.com/aderbique/keycloak-trusted-device

🗓 Release Schedule

The image is updated and pushed to https://hub.docker.com/repository/docker/austinderbique/keycloak-trusted-device under these triggers:

1. Weekly build – fetches the latest Keycloak release and rebuilds the image if a new version is available.
2. Manual build – trigger via GitHub Actions to build a specific Keycloak version.
3. Tag push – pushing a Git tag like v26.3 builds that specific Keycloak version.

Tags:

• <KEYCLOAK_VERSION> → e.g., 26.3
• latest → points to the most recently built version

⚙️ Usage Example

Docker Run

bash
docker run -d \
  --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  austinderbique/keycloak-trusted-device:latest


### Docker Compose
```bash
version: "3.8"
services:
  keycloak:
    image: austinderbique/keycloak-trusted-device:latest
    ports:
      - "8080:8080"
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin

🔧 Setting the Trusted Device Flow

Warning: Back up your Keycloak database before switching authentication flows.

1. Log in to the Keycloak Admin Console.
2. Navigate to Authentication → Flows.
3. Duplicate the built-in Browser flow and rename it, e.g., Browser with Trusted MFA.
4. Edit the new flow to match the Authentication Flow Structure from the plugin’s documentation.
5. Set your new flow as the Browser Flow under Authentication → Bindings.
6. Test with a non-admin user account.

For full configuration details, setup examples, and advanced options, visit the https://github.com/wouterh-dev/keycloak-spi-trusted-device.