---
title: "Configuration"
description: "Learn how to authenticate users with Keycloak via the walt.id wallet API."
stack: "Community Stack (open source) — version 0.21.0"
stack_version: "0.21.0"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/community-stack/wallet/authentication/jwt-oidc/keycloak/configuration
generated: 2026-07-08
---
# Configuration
## Installation
docker :
```bash
docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:24.0.1 start-dev --features=preview
```
or
Download the Keycloak server from the [official website](https://www.keycloak.org/downloads.html) and start it with the following command:
```bash
bin/kc.sh start-dev --features=preview
```
In either case it is important that the flag: __--features=preview__ is passed along in order to enable the "token-exchange" option (see below).
## Keycloak Realm Configuration
- Create a new realm named "waltid-keycloak-ktor" in the Keycloak admin console.
## Client Setup
- Setup a client with the following configurations:
- Client Capability Configuration
Configure client capabilities:
- Login Settings in Client Config :
1.Root URL : Public root URL of the wallet.
2\. Home URL : Default URL for redirects or links.
3\. Valid URI pattern for successful login redirects (wildcard: \*).
4\. Web origins : Allowed CORS origins.
## Service Account Configuration
To use the Keycloak user API, you need to add a service account role in Keycloak. This role is used to authenticate a user using the username and password.
1. Go to the Keycloak admin console and select the realm you want to use.
2. Go to the client **waltid_backend** and select the `Service Account Roles` tab.
3. Add the `manage-users` role to the service account.
## Token exchange for user impersonation Configuration
User impersonation in Keycloak allows one user to obtain a token that represents another user, enabling them to perform actions on behalf of that user. This process involves exchanging a token granted to the acting user with another token representing the target user.
To granting permission for the exchange of tokens , you need to define a token-exchange fine grain permission in the target client you want permission to exchange to.
1. Go to the Keycloak admin console and select the realm **waltid-keycloak-ktor**.
2. Go to the client **waltid_backend** and select the `Permissions` tab.
3. Toggle Permissions Enabled to On.
That page displays a **token-exchange** link.
4. Click on the **token-exchange** link and add the `token-exchange` permission to the client.
5. Click Client details in the breadcrumbs at the top of the screen.
Define a policy for this permission
7. Click Authorization in the breadcrumbs at the top of the screen.
8. Click Policies in the breadcrumbs at the top of the screen.
9. Click Create Policy.
10. After you create this policy, go back to the target client’s token-exchange permission and add the client policy you just defined.
Apply Client Policy
## Impersonation Configuration
1. Go to the Keycloak admin console and select the realm you want to use.
2. Go to the Users tab in the left-hand menu.
3. Go to permissions .
The page displays an impersonate link.
4. Click on the impersonate link and click the `impersonate` link.
5. Click Client details in the breadcrumbs at the top of the screen.
Define a policy for this permission
6. After you create this policy, go back to users' impersonation permission and add the client policy you just defined.
Apply Client Policy
## Keycloak integration in wallet-api
Read here how to configure wallet-api to support Keycloak login.
### Keycloak provider configuration
Update OIDC config file in `config/oidc.conf`:
```ini
enableOidcLogin = true
providerName = keycloak
oidcRealm = "https://keycloak.walt-test.cloud/realms/waltid-keycloak-ktor"
oidcJwks = "${oidcRealm}/protocol/openid-connect/certs"
authorizeUrl = "${oidcRealm}/protocol/openid-connect/auth"
accessTokenUrl = "${oidcRealm}/protocol/openid-connect/token"
logoutUrl = "${oidcRealm}/protocol/openid-connect/logout"
clientId = "waltid_backend"
keycloakUserApi = "https://keycloak.walt-test.cloud/admin/realms/waltid-keycloak-ktor/users"
clientSecret = "..."
jwksCache = {
cacheSize = 10
cacheExpirationHours = 24
rateLimit: {
bucketSize: 10
refillRateMinutes: 1
}
}
```
1. `oidcRealm`: The realm base URL: `/realms/`
2. `clientId`: Specify the client ID created in Keycloak.
3. `clientSecret`: The client secret is generated by Keycloak (found in `clients -> -> credentials`):
