design: Define Keycloak client contract for operator-managed registrations

[pdettori]

Context

Issues raised in #268 and related discussions highlight that the operator's automatic Keycloak client creation lacks a clear, documented contract. The current implementation makes implicit assumptions about:

• Client ID format — hardcoded SPIFFE ID pattern (spiffe://<td>/ns/<ns>/sa/<sa>)
• Audience claims — no explicit audience configuration (partly addressed by kagenti-extensions#356)
• Token-exchange scope — no restrictions on what tokens a client can exchange for
• Per-pod vs per-workload identity — no clear boundary on what granularity is supported

Goals

Define an explicit contract for operator-managed Keycloak clients covering:

1. Client Identity

• What determines the client ID (SPIFFE ID, annotation, convention)?
• What happens when the SPIFFE ID format is non-default or per-pod?
• Relationship between ClusterSPIFFEID CRDs and Keycloak client creation

2. Client Configuration

• Default grant types (client_credentials, token-exchange)
• Client scopes — what's included by default, what's configurable?
• Service account roles and role mappings
• Audience restrictions (inbound and outbound)

3. Token Exchange Permissions

• Which clients can exchange tokens with which targets?
• How are token-exchange policies scoped (namespace, labels, explicit list)?
• How does this interact with AuthBridge's ext_proc validation?

4. Lifecycle

• What happens on workload deletion — client cleanup?
• What happens on SPIFFE ID rotation or trust domain change?
• Idempotency guarantees on re-reconciliation

Current Behavior (for reference)

The operator creates:

• A confidential client with client_credentials grant
• Token-exchange permission enabled
• A service-account user mapped to the kagenti-agent realm role
• Client ID set to the SPIFFE ID (hardcoded format)
• No custom client scopes added

Related

• 🐛 Client registration controller assumes default format for SPIFFE IDs #268 — SPIFFE ID format assumption (immediate fix)
• kagenti-extensions#356 — AllowedAudiences for inbound JWT validation (merged)
• kagenti-extensions PR Add configurable SPIFFE ID template support #269 — Configurable SPIFFE ID template (to be reopened)

Outcome

A design doc or ADR that the operator, AuthBridge, and client-registration components can implement against, ensuring consistency across the auth flow.

cc @grs @akram @webchang