Skip to main content
The playground includes a pre-configured Keycloak instance that acts as an Identity Provider (IdP). It demonstrates KrakenD’s ability to validate JWT tokens issued by an external authentication service.

​
Overview

Keycloak provides:
  • JWT token generation - Issue tokens for authenticated users
  • User management - Pre-configured users with different roles
  • Realm administration - Full IdP configuration capabilities
  • Standards compliance - OIDC and OAuth 2.0 support

​
Access

​
Pre-Configured Users

The playground includes two users with different roles:
UsernamePasswordRole
moderatormoderatorModerator role with elevated permissions
readerreaderReader role with limited permissions
These users are pre-configured in the krakend realm and ready to use for testing JWT authentication.

​
Admin Console

To manage users, roles, and realm configuration:
  1. Visit http://localhost:8085/admin/master/console/#/krakend/users
  2. Login with admin credentials: admin / admin
  3. Select the krakend realm from the dropdown
  4. Manage users, roles, clients, and other settings

​
JWT Token Validation

KrakenD validates JWT tokens issued by Keycloak on protected endpoints. For example: 
{
  "endpoint": "/private/moderate",
  "extra_config": {
    "auth/validator": {
      "alg": "RS256",
      "jwk_url": "http://keycloak:8080/realms/krakend/protocol/openid-connect/certs",
      "roles_key": "realm_access.roles",
      "roles": ["moderator"]
    }
  }
}

​
How It Works

  1. User authenticates with Keycloak
  2. Keycloak issues a JWT token
  3. Client sends the token to KrakenD in the Authorization header
  4. KrakenD validates the token signature using Keycloak’s public keys
  5. KrakenD checks required roles/claims
  6. Request proceeds if valid, or returns 401/403 if invalid

​
Configuration Persistence

All realm configuration changes made through the administration dashboard will NOT be persisted on container restart.

​
Exporting Configuration

If you create new users, roles, or configurations that you want to keep: 
make save-keycloak-config
This exports the current realm configuration to config/keycloak/realms/, which is mounted as a volume and will be imported on the next container start.
Make sure the Keycloak container is running before executing the save command.

​
Realm Configuration

The Keycloak instance uses:
  • Import on startup - Automatically imports realm config from config/keycloak/realms/
  • Development mode - Runs with start-dev for easier testing
  • Volume mount - Configuration files at ./config/keycloak/realms:/opt/keycloak/data/import

​
Using with the Demo App

The playground includes a Single Page Application at http://localhost:3000 that:
  1. Integrates with Keycloak for authentication
  2. Obtains JWT tokens
  3. Makes authenticated requests to KrakenD
  4. Demonstrates the complete authentication flow

​
JWT Revocation

The playground also includes a JWT revoker service on port 9000 that works with KrakenD’s bloomfilter to revoke tokens. See the JWT revoker documentation for more details.

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us