Keycloak (OIDC Provider) Configuration
This guide details the recommended and troubleshooting configurations for setting up OpenBao with Keycloak as an OpenID Connect (OIDC) provider.
1. Keycloak Client Setup
The Keycloak client must be configured to support the Authorization Code Flow as shown below.
| Setting | Value | Notes |
|---|---|---|
| Client ID | 'bao-client' (Example) | This is the client identifier used to request tokens from Keycloak. You'll use it as the client ID in the OpenBao oidc configuration. |
| Client Authentication | Enabled | Must be 'client-secret' to allow the Authorization Code Flow. |
| Access Type | 'confidential' | Required for the Authorization Code Flow. |
| Valid Redirect URIs | See Redirect URIs below | These must match the exact URLs generated by the OpenBao UI/CLI. |
Required Redirect URIs (Important!)
The Keycloak client must be configured to accept the following specific redirect URI patterns:
| Endpoint | Purpose | URI Pattern to Add |
|---|---|---|
| API/Code Exchange | Primary OIDC API endpoint. | https://<YOUR_VAULT_ADDR>/v1/auth/oidc/* |
| UI Login | The actual URI generated by the OpenBao UI. | https://<YOUR_VAULT_ADDR>/ui/vault/auth/oidc/oidc/callback |
| CLI Login | Used for 'bao login -method=oidc'. | http://localhost:8250/oidc/callback |
The exact URIs will be needed in the OpenBao role setting too (see below).
2. OpenBao Configuration
The most important configuration lies in the required 'oidc_discovery_url'.
2.1 OIDC Discovery
The correct 'oidc_discovery_url' is the base realm URL. OpenBao will append the necessary '/.well-known/openid-configuration' path to the end of the URL.
| Field | Description | Example (Correct) |
|---|---|---|
| 'oidc_discovery_url' | The base URL of the Keycloak realm. | https://<KEYCLOAK_URL>/realms/<REALM-NAME> |
| 'jwks_url' | Optional - Provides the public key source manually. | https://<KEYCLOAK_URL>/realms/<REALM-NAME>/protocol/openid-connect/certs |
Note on URLs: If 'jwks_url' is provided, 'oidc_discovery_url' must be omitted. Also omit using the 'oidc_client_id' and the 'oidc_client_secret'. When doing this, the auth mount cannot be used for OIDC and can only be used for explicit JWT verification.
Working Example Command
This command provides the base configuration that should be used once OpenBao's API bug is stabilized.
# This assumes the minimal configuration required to start the flow.
# Use this when auto-discovery is reliable.
bao write auth/oidc/config \
oidc_client_id="bao-client" \ # taken from your Keycloak client setting
oidc_client_secret="<CLIENT_SECRET>" \ # found under "Credentials" in Keycloak
default_role="admin-sso" \ # this is used, if during OIDC login a role isn't entered
oidc_discovery_url="https://<KEYCLOAK_URL>/realms/<REALM-NAME>"
3. The Role Configuration
The role maps authenticated Keycloak users to OpenBao policies.
3.1 Resolving Role Type Errors
Common errors you might come across in this setup stem from the allowed_redirect_uris field not having all possible URIs entered.
| OpenBao Parameter | Value | Notes |
|---|---|---|
| 'role_type' | 'oidc' | Required for browser-based UI logins. |
| 'allowed_redirect_uris' | See Section 1 | This must be a list of comma separated uris. The example below shows the typical uris. |
Example Role Creation
# This example shows a fairly standard role setup. Note the path name /admin-sso. This is the name you wish to give the role and was used above as the default.
# Also note this role gives the logged in user admin permissions across your OpenBao instance. Use with caution!
bao write auth/oidc/role/admin-sso \
role_type="oidc" \
user_claim="sub" \
policies="admin,default" \
oidc_scopes="profile,email" \
allowed_redirect_uris="https://<YOUR_VAULT_ADDR>/v1/auth/oidc/callback,https://<YOUR_VAULT_ADDR>/ui/vault/auth/oidc/oidc/callback,http://localhost:8250/oidc/callback"