docs(authenticator): ADR-0003 — adopt Keycloak as identity broker, configured as code

[cyberantonz]

What

Records the outcome of the identity-broker investigation (#1782) as ADR-0003 under the authenticator specs, per the issue's deliverable. Closes #1782.

• ADR-0003 (new, accepted): Keycloak brokers heterogeneous customer IdPs (Entra/Okta/OIDC/SAML) and social logins (GitHub Login with GitHub #2163; Google/Facebook/Apple later) behind one uniform OIDC issuer; the authenticator keeps a single issuerUrl and is unchanged. Realm content is configuration-as-code only — keycloak-config-cli YAML applied from gitops, secrets via sealed secrets — never the admin UI. Per-provider identity-provider mappers inject the single tenant_id claim; protocol mappers allow-list what enters the token. Topology: realm per customer. fakeidp is retired (Keycloak becomes the issuer in compose and the in-process rig too, via the existing gen-realm.py realm).
• ADR-0002 (amended): status-history note — fakeidp survival clause retired, deferred broker question decided; shared pre-provisioned Keycloak and realm-generation decisions stand unchanged.
• DESIGN.md: ADR index refreshed (0001 was described as current; 0002 was missing; 0003 added) and the stale ./ADR/ traceability link fixed to ./specs/ADR/.
• PRD.md: unchanged on purpose — it is IdP-agnostic and brokering does not alter the RP contract.

Investigation report with the full comparison: #1782 (comment)

Validation

• cfs toc regenerated for touched files; cfs validate --local-only reports no findings for the authenticator artifacts (remaining repo-wide findings are pre-existing in other components); cfs check-language clean.

Confirmation gate (recorded in the ADR)

The PoC — a config-cli-only realm brokering one upstream, unchanged authenticator, gateway JWT minted — validates refresh-token passthrough and logout propagation before rollout.

Refs #2163, #1583.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated authentication architecture decisions and traceability.
  • Documented Keycloak as the shared identity broker for customer identity providers and social logins.
  • Added guidance for declarative realm configuration, tenant mapping, secret management, migration, and operational considerations.
  • Recorded the retirement of the fake identity provider in deployment and test environments.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds an ADR for Keycloak as the identity broker, records its amendment to the real-IdP decision, and updates authenticator architecture references and traceability to ADRs 0001–0003.

Changes

Keycloak broker documentation

Layer / File(s)	Summary
Keycloak broker decision and ADR amendment docs/components/backend/authenticator/specs/ADR/0003-keycloak-identity-broker.md, docs/components/backend/authenticator/specs/ADR/0002-real-idp-on-deployed-stands.md	ADR-0003 documents Keycloak brokering, realm and tenant mapping, configuration management, migration, validation, and fakeidp retirement. ADR-0002 records the related status amendment.
Architecture references and traceability docs/components/backend/authenticator/DESIGN.md	The design references ADRs 0001–0003 and updates the traceability link to specs/ADR/.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• constructorfabric/insight#1662: Introduced the Authenticator design that this ADR extends.
• constructorfabric/insight#1821: Implements the related compose Keycloak mode, realm generation, and issuer configuration.

Suggested reviewers: aleksdotbar, ktursunov

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The ADR covers the investigation and recommendation, but the provided changes do not show the required throwaway compose PoC with the unchanged authenticator [#1782].	Add or link the compose PoC that demonstrates brokered login through Keycloak and gateway JWT issuance with the unchanged authenticator.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: adopting Keycloak as the authenticator identity broker with configuration-as-code.
Out of Scope Changes check	✅ Passed	The documented changes address the linked issue through ADR updates, traceability corrections, and the related ADR amendment.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/components/backend/authenticator/specs/ADR/0002-real-idp-on-deployed-stands.md (1)

103-105: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider an inline pointer to the amendment at the retired bullet.

The status history (Lines 10-16) states the fakeidp survival clause is retired. The Decision Outcome bullet at Lines 103-105 still asserts "fakeidp survives in exactly three places" with no inline note. A reader who jumps directly to the Decision Outcome section can miss the amendment recorded only at the top of the file.

Add a short inline annotation, for example "(retired by ADR-0003, see status history)", next to this bullet.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@docs/components/backend/authenticator/specs/ADR/0002-real-idp-on-deployed-stands.md`
around lines 103 - 105, Add a brief inline annotation to the Decision Outcome
bullet containing “fakeidp survives in exactly three places,” pointing readers
to ADR-0003 and the status history as the source of its retirement.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@docs/components/backend/authenticator/specs/ADR/0003-keycloak-identity-broker.md`:
- Around line 86-88: Remove the incorrect claim that Apple is a built-in
identity provider shipped with Keycloak from the provider coverage section.
Delete "and Apple since Keycloak 24" from the list of GitHub, Google, Facebook,
Microsoft, LinkedIn, and GitLab providers in the quoted section. Update the
corresponding claim at lines 186-187, and add a note that deployments requiring
Sign in with Apple must use an app-specific extension dependency instead of
relying on built-in support.

---

Nitpick comments:
In
`@docs/components/backend/authenticator/specs/ADR/0002-real-idp-on-deployed-stands.md`:
- Around line 103-105: Add a brief inline annotation to the Decision Outcome
bullet containing “fakeidp survives in exactly three places,” pointing readers
to ADR-0003 and the status history as the source of its retirement.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 937e8486-4323-4ff5-912a-b81342f0aaf4

📥 Commits

Reviewing files that changed from the base of the PR and between 59f0634 and e9d72f6.

📒 Files selected for processing (3)

• docs/components/backend/authenticator/DESIGN.md
• docs/components/backend/authenticator/specs/ADR/0002-real-idp-on-deployed-stands.md
• docs/components/backend/authenticator/specs/ADR/0003-keycloak-identity-broker.md