Skip to content
fzymgc-house Cluster Docs

Enable Keycloak anonymous DCR via Trusted-Hosts policy

Enable Keycloak anonymous DCR via Trusted-Hosts policy

Section titled “Enable Keycloak anonymous DCR via Trusted-Hosts policy”

Date: 2026-06-28 Status: Superseded by hl-amad Decision: hl-xktj Deciders: Sean Brandt

Context

Section titled “Context”

Keycloak disables anonymous Dynamic Client Registration by default — the realm’s Trusted Hosts client-registration policy whitelists no hosts. agentgateway’s Keycloak adapter proxies the anonymous RFC 7591 POST /register (no initial-access-token) to Keycloak’s clients-registrations endpoint and rewrites registration_endpoint in the AS metadata to the gateway’s own /client-registration (a documented CORS workaround). A trusted source must be configured for the proxied registration to succeed.

Decision

Section titled “Decision”

Configure the Keycloak Trusted Hosts client-registration policy to trust the agentgateway Service ClusterIP (not a pod IP), enabling anonymous RFC 7591 DCR proxied through the gateway. Keep host-match enabled (restrict to that source) and relax client-URI matching for DCR loopback redirect URIs.

Rationale

Section titled “Rationale”
  • MCP clients perform anonymous /register per RFC 7591; an initial-access-token requirement is incompatible with the flow agentgateway proxies.
  • The Service ClusterIP is stable across pod reschedules; pod IPs are not — using the ClusterIP minimizes surface churn.
  • agentgateway enforces Strict JWT on every non-registration path and engram re-validates as defense in depth, so the anonymous /register is the only widened surface and it is cluster-internal.

Alternatives Considered

Section titled “Alternatives Considered”
  • Trust the agentgateway Service ClusterIP (chosen): stable, cluster-internal, narrow surface; cost is a documented deviation from Keycloak’s default-secure posture.
  • Require an initial-access-token per DCR request (rejected): Keycloak default-secure but incompatible with RFC 7591 anonymous DCR — breaks the agentgateway proxy flow.

Consequences

Section titled “Consequences”
  • Positive: real DCR works for MCP clients without pre-issued credentials; defense in depth preserved via engram re-validation.
  • Negative: anonymous DCR is explicitly enabled — a documented deviation from Keycloak’s default-secure posture, owned by this ADR.
  • Neutral: /register is reachable externally only through the gateway; the Trusted-Hosts entry tracks the agentgateway Service ClusterIP.

References

Section titled “References”
  • Superseded by: hl-amad