External OIDC and Keycloak
Use api.auth: oidc_resource_server when an external OpenID Connect provider
issues access tokens for ai-memory-hub. The initial tested profile targets
Keycloak, but validation uses standard discovery and JWKS endpoints rather than
Keycloak administration APIs.
Install the OAuth dependencies before enabling this mode:
uv sync --extra oauth
This mode is separate from oauth_resource_server, which accepts hub-issued
HS256 tokens from the built-in Connect authorization flow. The two token models
cannot be enabled together.
Hub configuration
api:
host: 127.0.0.1
port: 8000
auth: oidc_resource_server
public_base_url: https://memory.example.internal
oidc:
issuer: https://keycloak.example.internal/realms/home
client_id: ai-memory-hub
audience: ai-memory-hub
algorithms: [RS256]
username_claim: preferred_username
email_claim: email
display_name_claim: name
allowed_groups: [memory-users]
allowed_roles: [memory-user]
role_scopes:
memory-reader: [memory:read]
memory-writer: [memory:read, memory:write]
discovery_url defaults to <issuer>/.well-known/openid-configuration.
Set jwks_url only when the provider does not publish a usable discovery
document. HTTPS is required except for loopback development URLs.
The validator requires a signed token with matching iss, aud, sub, and
exp claims. It also checks nbf, iat, and azp when present. Direct scope
or scp values are accepted, and configured Keycloak realm or client roles can
add hub scopes through role_scopes. Protected requests still require
memory:read or memory:write according to the HTTP or MCP operation.
Identity ownership is derived from a SHA-256 digest of the issuer and subject.
This keeps the same user stable across restarts while preventing subject
collisions between providers. On the first valid request, the hub creates the
matching local user and default project. It stores only the subject and the
configured username_claim, email_claim, and display_name_claim values in
the OAuth identity profile; later tokens refresh changed values without
changing ownership. Missing optional claims do not erase stored values, and an
email explicitly marked email_verified: false is not stored. Access tokens,
groups, roles, scopes, and other raw claims are not persisted or logged by this
validation path.
When allowed_domains is configured, the email claim is an authorization
boundary and the token must contain email_verified: true. Missing or
non-boolean verification values are rejected.
The profile claim names default to the standard Keycloak claims shown above and may use dotted paths for nested provider payloads. Claim synchronization is cached in-process for unchanged profiles to avoid a metadata write on every request. Restarting the hub or receiving changed profile values safely repeats the upsert.
Keycloak client setup
Create an OpenID Connect client in the selected realm:
- Set the client ID to the configured
client_id, such asai-memory-hub. - Configure Keycloak to include that client in the access-token audience.
- Add realm or client roles used by
allowed_rolesandrole_scopes. - Add a
groupsmapper ifallowed_groupsis configured. - Give users only the roles and groups needed for their hub access.
The hub is a resource server and does not need a client secret to validate tokens. Redirect URIs, PKCE, refresh tokens, and interactive login remain the responsibility of the MCP client and Keycloak. The protected-resource metadata endpoint advertises the configured Keycloak issuer so capable MCP clients can discover the external authorization server.
Verification
curl -fsS https://memory.example.internal/.well-known/oauth-protected-resource/mcp
curl -fsS https://memory.example.internal/memory/search \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query":"project memory"}'
GET /ready reports the external issuer, discovery URL, configured audience,
whether a direct JWKS URL is configured, and a live provider_ready signal.
The Connect page shows the same provider availability. Successful checks use
the configured JWKS cache lifetime; failed checks are cached for 30 seconds so
an unavailable provider is not contacted on every readiness request. Provider
failure does not make the hub's own readiness endpoint fail, because existing
local operations and diagnostics must remain available. These surfaces never
return tokens, claims, client secrets, or provider error responses.
Use TLS even on a private LAN unless every hop is otherwise protected. Do not copy browser tokens into committed configuration or shell history. If Keycloak is only reachable through an internal CA, install that CA in the hub container or host rather than disabling certificate verification.
Current boundary
External OIDC validates bearer access tokens, publishes MCP-compatible
protected-resource metadata, and maintains a minimal local identity profile.
It does not add a second browser login flow to /connect or manage Keycloak
sessions. Interactive authorization, PKCE, refresh tokens, MFA, logout, and
session policy remain provider- and MCP-client-owned concerns.