boost-backend — Keycloak service-account auth via OAuth2 Client Credentials (issue 13 of 15)

[gabemontero]

Labels: ready-to-code
Depends on: Issue 11

Implement KeycloakAuthClient for service-account Kagenti authentication via OAuth2 Client Credentials Grant.

Approach Change (2026-06-26)

Previous approach: Per-user identity delegation via RFC 8693 token exchange (TokenExchangeManager). Each user's OIDC token was exchanged for a Kagenti-scoped token with per-user caching and graceful fallback.

Current approach: Service-account authentication via OAuth2 Client Credentials Grant (KeycloakAuthClient). A single service-account token is obtained from Keycloak, cached with expiry buffer, and used for all Kagenti requests. User identity is propagated via X-Backstage-User header for audit purposes (informational only, not for authentication).

Rationale: The service-account approach is simpler, proven in production, and sufficient for current requirements. Per-user token exchange adds complexity (auth proxy dependency, RFC 8693 exchange flow, per-user cache management) without proportional benefit at this stage. Service-account auth with user context headers provides adequate audit trails.

Tasks

From openspec/changes/security-safety-governance/tasks.md section 7:

• 7.1 Create KeycloakAuthClient implementing OAuth2 Client Credentials Grant ✅ PR feat(#3647): auth pivot, dev scaffold, entity provider fixes #3648
• 7.2 Add token caching with configurable expiry buffer (tokenExpiryBufferSeconds, default: 60) ✅ PR feat(#3647): auth pivot, dev scaffold, entity provider fixes #3648
• 7.3 Add max-1-retry on 401 (refresh token and retry once) ✅ PR feat(#3309): add Kagenti auth, 401 retry, and user header #3661
• 7.4 Add config schema: boost.kagenti.auth.{tokenEndpoint, clientId, clientSecret, tokenExpiryBufferSeconds} ✅ PR feat(#3647): auth pivot, dev scaffold, entity provider fixes #3648
• 7.5a Integrate into entity providers — inject bearer token ✅ PR feat(#3647): auth pivot, dev scaffold, entity provider fixes #3648
• 7.5b Integrate into KagentiApiClient — inject bearer token ✅ PR feat(#3309): add Kagenti auth, 401 retry, and user header #3661
• 7.6 Propagate user identity via X-Backstage-User header for audit ✅ PR feat(#3309): add Kagenti auth, 401 retry, and user header #3661

All tasks complete. KeycloakAuthClient was deduplicated into boost-node/src/KeycloakAuthClient.ts and is shared by both entity providers (kagenti-entity-provider) and the user-facing provider module (boost-backend-module-kagenti).

Config Fields

The config fields are defined in plugins/boost-backend/src/config/schemas.ts. The KeycloakAuthClient consumer reads them at startup:

Key	Default	Description
boost.kagenti.auth.tokenEndpoint	—	Keycloak token endpoint URL
boost.kagenti.auth.clientId	—	OAuth2 client ID for service-account
boost.kagenti.auth.clientSecret	—	OAuth2 client secret (visibility: secret)
boost.kagenti.auth.tokenExpiryBufferSeconds	60	Seconds before expiry to refresh token

Implementation Constraints

These constraints are codified in the specs and must be followed:

1. Retry limit: On HTTP 401 from Kagenti, invalidate the cached token, fetch a fresh one, and retry the request at most once. If the retried request also returns 401, propagate the error to the caller. Do not loop. (See access-control/spec.md and design.md Decision 4.)

2. Consumer-applied default for tokenExpiryBufferSeconds: The Zod schema does NOT include .default(60) — raw config resolution bypasses Zod defaults. KeycloakAuthClient applies its own fallback: const buffer = configValue ?? 60.

3. Partial config detection: The three core auth fields (tokenEndpoint, clientId, clientSecret) are individually optional in the schema (because Keycloak auth itself is optional). When only a subset of the three fields is present, a warning is logged and auth is disabled. When all three are present, KeycloakAuthClient is constructed. (Implemented in readKagentiAuthConfig in module.ts.)

4. No references to Augment or Citi in code, config keys, comments, or error messages. Boost is a clean-room reimplementation. The only Augment references allowed are in high-level specification context (e.g., "Augment lesson" in boost-context.md).

5. Credential delivery method: Credentials must be sent as client_id and client_secret in the POST form body (application/x-www-form-urlencoded), not via HTTP Basic auth. This matches the Keycloak client configuration (client_secret_post). See access-control/spec.md.

Reference Implementation

The augment workspace has a working KeycloakTokenManager that can be used as a reference for the remaining patterns (401 retry, concurrent deduplication, getTokenForStreaming):

• workspaces/augment/plugins/augment-backend/src/providers/kagenti/client/KeycloakTokenManager.ts
• workspaces/augment/plugins/augment-backend/src/providers/kagenti/client/KagentiApiClient.ts
• workspaces/augment/plugins/augment-backend/src/providers/kagenti/client/requestCore.ts

Important: Do not copy code from augment. Use it to understand the patterns, then implement cleanly in boost's architecture.

Where the Code Lives

Completed (PR #3648, PR #3661):

• plugins/boost-node/src/KeycloakAuthClient.ts — KeycloakAuthClient class (deduplicated from kagenti-entity-provider into boost-node for shared use)
• plugins/boost-node/src/KeycloakAuthClient.test.ts — unit tests
• plugins/boost-backend-module-kagenti/src/provider/KagentiApiClient.ts — 401 retry, bearer token injection, X-Backstage-User header
• plugins/boost-backend-module-kagenti/src/provider/KagentiProvider.ts — ChatOptions threading for user identity propagation
• plugins/boost-backend-module-kagenti/src/module.ts — config reading, partial config detection, auth client construction

Specifications

• openspec/changes/security-safety-governance/specs/access-control/spec.md — Service-account auth scenarios (6 scenarios covering token acquisition, streaming, 401 retry, user identity propagation, config, LlamaStack unaffected)
• openspec/changes/security-safety-governance/design.md — Decision 4 (service-account auth with token caching and streaming support)
• openspec/changes/security-safety-governance/tasks.md — Section 7 (all tasks)
• openspec/changes/platform-operations-deployment/specs/runtime-config/spec.md — Config field scenarios
• specifications/boost-context.md — Design principles (read Principle 10 for auth context)

[fullsend-ai-triage]

Triage Summary

Status: Ready for implementation — the prerequisite #3307 (Kagenti provider module) is now resolved.

Overview

This issue implements KeycloakTokenManager for service-account authentication to Kagenti via OAuth2 Client Credentials Grant. The approach was updated from per-user token exchange (RFC 8693) to a simpler service-account model with user identity propagated via X-Backstage-User header for audit purposes.

Key Implementation Tasks

1. KeycloakTokenManager — OAuth2 Client Credentials Grant flow
2. Token caching with configurable expiry buffer (default 60s)
3. Concurrent request deduplication (single in-flight Keycloak call)
4. getTokenForStreaming(minLifetimeMs) for SSE connection support
5. 401 retry with cache invalidation and fresh token fetch
6. Config schema under boost.kagenti.auth.*
7. Integration into KagentiApiClient.requestCore() with Bearer token and user context headers

Proposed Test Cases

- Token is cached and reused within expiry window
- Token refreshes when within expiry buffer (60s before expiry)
- Concurrent token requests are deduplicated (single Keycloak call)
- getTokenForStreaming returns fresh token if remaining lifetime < minLifetimeMs
- 401 response triggers cache invalidation and retry with fresh token
- Config validation rejects missing tokenEndpoint, clientId, or clientSecret
- X-Backstage-User header is set for audit purposes

This is issue 13 of 15 in the boost-backend series.

Previous run

Triage Summary

This issue is blocked by #3307 (boost-backend-module-kagenti — Kagenti provider module).

Why it's blocked

This issue implements TokenExchangeManager for per-user identity delegation via RFC 8693, which must integrate into KagentiApiClient.requestCore() (task 7.6). The Kagenti provider module (#3307) defines the KagentiApiClient and its core request infrastructure — that module must land first before token exchange can be wired in.

When to unblock

Once #3307 is resolved, the remaining tasks (creating the TokenExchangeManager, adding per-user token caching, concurrent exchange deduplication, graceful fallback, config schema, and OIDC token extraction) can proceed.

This is issue 13 of 15 in the boost-backend series.

---

Labels: This is part of the ai-integrations workspace (boost-backend plugin for Kagenti/AI agent integration) and involves security-related token exchange.

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 1:50 PM UTC · Completed 1:52 PM UTC
Commit: 71cfae4 · View workflow run →