Skip to main content

Configure Keycloak

Set up Keycloak as your identity provider.

Before you start, find your callback URL on the Configure SSO page: {gatewayUrl}/api/auth/callback/keycloak.

Create a client in Keycloak​

  1. In your realm, create a client (OpenID Connect, confidential)
  2. Set Valid redirect URIs to {gatewayUrl}/api/auth/callback/keycloak
  3. Copy the Issuer (realm URL, e.g. https://keycloak.example.com/realms/your-realm), Client ID, and Client Secret

For more details, see the Keycloak guide to creating an OIDC client.

Finish in Willow​

  1. Go to Admin → Settings → Authentication Settings
  2. Select Provider: Keycloak
  3. Enter the Issuer, Client ID, and Client Secret
  4. Select Save Changes
Keycloak SSO provider configured in Willow Authentication Settings

Internal issuer (self-hosted Keycloak)​

If Keycloak runs inside the same network as Willow and its public URL is not reachable from Willow's servers, sign-in fails during OIDC discovery, before the user is ever redirected. Set Internal Issuer to the realm URL Willow can reach directly, for example http://keycloak-service.keycloak.svc.cluster.local:8080/realms/your-realm.

Willow then performs discovery and token exchange over the internal URL, while users are still redirected to the public Issuer to sign in. Leave the field empty to use the public issuer for both.

This requires Keycloak to serve a dynamic back-channel, so the discovery document returned on the internal URL still advertises the public issuer and authorization endpoint. On Keycloak 24+ set hostname-backchannel-dynamic: true (backChannelDynamic: true on the RHBK custom resource) alongside your configured public hostname.

Advanced options​

After saving, three optional settings are available beneath the credential fields:

Enable Client Credentials for Machine Users: lets machine users reach internal MCP servers that use proxy passthrough, by minting an OAuth token from this provider on their behalf (see Machine Users). When enabled, a Token Endpoint field appears, auto-discovered from your issuer's .well-known/openid-configuration.

Enable Client Credentials for Machine Users toggle with auto-discovered Token Endpoint field

Enable passthrough refresh token: forwards the user's SSO JWT to internal MCP servers automatically. When enabled, an OIDC Token Endpoint field appears, auto-discovered. See JWT Passthrough for the full setup.

Enable passthrough refresh token toggle with auto-discovered OIDC Token Endpoint field

Enable Auth Exchange (JWT to Connect credentials): enables JWT token verification using your IdP's JWKS endpoint. When enabled, a JWKS URI field appears, auto-discovered. Used to verify JWT tokens in the auth exchange API.

Enable Auth Exchange toggle with auto-discovered JWKS URI field
On this page