Vault & Keycloak Integration

Token Introspection Integration with Vault and Keycloak¶

Token introspection enables dynamic validation of OAuth2 tokens against external identity providers (IdPs), such as Keycloak, to grant access to secrets managed by HashiCorp Vault. This integration allows Vault to enforce fine-grained access control based on token claims (e.g., audience, scope, expiration) while leveraging Keycloak's authentication and authorization capabilities.

Keycloak Configuration for Token Introspection¶

Enable Introspection Endpoint
Keycloak's introspection endpoint is enabled by default, but ensure your realm is configured to issue tokens with the required claims.
Example:

curl -X POST \
  http://KEYCLOAK_HOST/auth/realms/{realm}/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=admin-cli" \
  -d "client_secret={secret}" \
  -d "grant_type=client_credentials"

Configure Client for Introspection
Create a client in Keycloak with the introspection scope enabled:

curl -X POST \
  http://KEYCLOAK_HOST/auth/admin/realms/{realm}/clients \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "vault-introspection",
    "redirectUris": ["http://VAULT_HOST/v1/sys/auth/keycloak/introspect"],
    "scopesEnabled": ["introspection"],
    "enabled": true
  }'

HashiCorp Vault Configuration for Token Introspection¶

Set Up Introspection Backend
Configure Vault to use Keycloak's introspection endpoint:

vault write auth/keycloak/config \
  url="http://KEYCLOAK_HOST/auth/realms/{realm}" \
  client_id="vault-introspection" \
  client_secret="{secret}" \
  introspection_endpoint="/protocol/openid-connect/token/introspection"

Mount Secret Engine and Define Policies
Mount a secret engine and bind access to token claims:

vault secrets enable -path=secrets kv-v2

vault write secrets/config/roles/my-role \
  allowed_policies="my-policy" \
  token_introspection=true

Example Secret Access with Token
Use a valid Keycloak token to access a secret:
```
vault read secrets/data/my-secret \
  -token="{keycloak_token}"
```

Workflow Diagram¶

[Application] -> [Keycloak] -> [Vault]
         |                |
         v                v
    [OAuth2 Token]   [Introspection]
         |                |
         v                v
    [Valid/Revoked]   [Secret Access]

Key takeaways¶

Token introspection allows Vault to dynamically validate tokens against Keycloak, enabling fine-grained access control.
Keycloak configuration requires enabling introspection scopes and setting up a dedicated client with secure credentials.
Vault integration relies on the auth/keycloak backend, which uses token claims to enforce secret access policies.
Always secure client credentials and ensure introspection endpoints are protected against unauthorized access.