feat(gitops): sealed broker-realm secrets + CI guard + canonical insight client scope (Phase 1, boxes 2–3)

[cyberantonz]

What

The remaining two Phase-1 boxes of the broker rollout, delivered together (they are one coherent unit: the realm YAML, the Secret it references, and the guard that polices it):

Box 2 — secrets via SealedSecrets + CI guard

• insight-keycloak-config sealed-secret shape template (environments/local/sealed-secrets/insight/…yaml.template) + inventory secrets.services entry (off by default). One Secret feeds the config-cli hook Job (keycloakConfig.existingSecret, feat(gitops): keycloak-config-cli sync Job — broker realms as code (Phase 1, box 1) #2204): the KEYCLOAK_USER/KEYCLOAK_PASSWORD login plus every $(env:VAR) placeholder the realm YAML references.
• Secret hygiene: realm YAML only ever references secrets — env placeholders resolved at apply time from sealed Secrets. keycloakConfig.extraEnv (added here) lets placeholders resolve from other already-sealed Secrets via explicit secretKeyRef mappings, so a value shared with another consumer (e.g. the authenticator's client secret) has exactly one sealed source of truth and is never sealed twice — also the only way to consume Secret keys that are not valid env-var names, which envFrom drops silently. A bespoke realm-YAML lint was tried and dropped in review: the repository's standard secret scanning covers these files, and the authoring rules (placeholders only; no placeholder syntax in YAML comments — config-cli substitution scans comments and fails the import loudly at deploy time) are documented in the gitops README.

Box 3 — canonical insight client scope

• environments/local/keycloak/realms/insight-broker.yaml — the canonical realm shape environments copy when onboarding: a clientScopes entry named insight emitting exactly email and the single-string tenant_id (DD-AUTH-04), and the insight-authenticator confidential client with fullScopeAllowed: false and exactly [basic, insight] assigned — the allow-list ADR-0003 mandates, so upstream-IdP claims cannot pass through unless a mapper re-emits them. (basic is the Keycloak 24+ built-in carrying the protocol-required sub/session claims; it emits no identity claims.) The tenant_id mapper shape matches the compose realm generator. The file is inert until an environment flips keycloakConfig.enabled (Phase 4).

Verification

• Live claim-set proof on a scratch cluster: the realm applied through the feat(gitops): keycloak-config-cli sync Job — broker realms as code (Phase 1, box 1) #2204 hook Job (env-var substitution from the Secret shape above), then admin-API example-token evaluation for a probe user carrying both allow-listed attributes and a stray attribute: ID and access tokens contain exactly sub, email, tenant_id plus protocol claims — the stray attribute does not leak, and no profile-scope claims appear.
• helm lint unaffected (no chart changes); pre-commit clean.

One finding for Phase 3 (#2196)

Keycloak 24+ declarative user profile drops unmanaged user attributes written via the admin REST API by default (unmanagedAttributePolicy unset) — a probe user created that way silently lost tenant_id until the scratch realm allowed unmanaged attributes. The production path is unaffected (identity-provider mappers stamp the attribute at first broker login, as the Phase-0 PoC proved end-to-end), but Phase 3 should decide whether realms declare tenant_id in the user profile explicitly rather than relying on that difference.

Refs #2195
Part of #2193

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a standard Keycloak broker realm configuration with limited client scopes and environment-based credentials.
  • Added a local sealed-secret template for securely configuring Keycloak credentials and redirect settings.

• Documentation

  • Updated setup guidance for realm credentials, environment substitutions, and sealed-secret workflows.

• Bug Fixes

  • Added validation that detects exposed credentials, invalid placeholders, and malformed realm configuration files before deployment.

[coderabbitai]

Warning

Review limit reached

@cyberantonz, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 19 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: faea141f-1497-4cbe-9fb3-5728a69ffb21

📥 Commits

Reviewing files that changed from the base of the PR and between 50557fa and 1986a15.

📒 Files selected for processing (7)

• charts/insight/templates/keycloak-config-job.yaml
• charts/insight/values.yaml
• deploy/gitops/Makefile
• deploy/gitops/README.md
• deploy/gitops/environments/local/inventory.yaml.template
• deploy/gitops/environments/local/keycloak/realms/insight-broker.yaml
• deploy/gitops/environments/local/sealed-secrets/insight/insight-keycloak-config-sealedsecret.yaml.template

📝 Walkthrough

Walkthrough

The PR adds a canonical Keycloak broker realm, sealed-secret configuration, and environment wiring. It adds a Python guard that rejects literal credentials and invalid placeholders, then runs the guard in CI and pre-commit.

Changes

Keycloak realm guard

Layer / File(s)	Summary
Realm configuration and secret wiring deploy/gitops/environments/local/keycloak/realms/insight-broker.yaml, deploy/gitops/environments/local/sealed-secrets/..., deploy/gitops/environments/local/inventory.yaml.template, deploy/gitops/README.md	Adds the insight-broker realm, its restricted client scope and authenticator client, sealed-secret template, inventory entry, and credential-handling documentation.
Realm secret validation scripts/ci/realm_secret_guard.py	Recursively checks sensitive fields, accepts strict $(env:VAR) placeholders, rejects placeholders in comments, reports YAML errors, and returns a failure status when findings exist.
CI and pre-commit enforcement .github/workflows/ci.yml, .pre-commit-config.yaml	Runs the guard for relevant pull requests and through a local pre-commit hook with PyYAML installed.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant PullRequest
  participant GitHubActions
  participant PyYAML
  participant realm_secret_guard
  participant RealmYAML

  PullRequest->>GitHubActions: Change realm YAML
  GitHubActions->>PyYAML: Install parser
  GitHubActions->>realm_secret_guard: Run validation
  realm_secret_guard->>RealmYAML: Read and inspect
  RealmYAML-->>realm_secret_guard: YAML content
  realm_secret_guard-->>GitHubActions: Findings and exit status

Loading

Possibly related issues

• Broker Phase 1: realm as code in gitops — config-cli Job, sealed secrets, canonical client scope #2195 — Covers the realm-as-code configuration, sealed secrets, and CI secret guarding added here.
• EPIC: Keycloak identity broker rollout (ADR-0003) #2193 — Covers Phase 1 of the Keycloak identity-broker rollout implemented by this realm configuration.
• Broker Phase 4: migrate environments behind the broker; retire fakeidp #2198 — Relates to the broker realm and authenticator configuration used for the identity-broker migration.

Possibly related PRs

• constructorfabric/insight#2170 — Defines the related GitOps Keycloak realm and secret-management approach.
• constructorfabric/insight#2204 — Also manages version-controlled broker realm YAML and substituted secrets.

Suggested reviewers: ktursunov

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately identifies the sealed secrets, CI guard, and canonical client scope added by the pull request.

✨ 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

🤖 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 `@deploy/gitops/environments/local/keycloak/realms/insight-broker.yaml`:
- Around line 37-46: The email mapper currently reads from the user attribute
map instead of Keycloak’s built-in UserModel.email property. Update the mapper
named “email” to use oidc-usermodel-property-mapper while preserving its
existing claim name, token inclusion, and email configuration.

🪄 Autofix

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: 1dbbdc00-1173-4fb8-82b0-10b9bfbb6c36

📥 Commits

Reviewing files that changed from the base of the PR and between a3a2fb4 and 50557fa.

📒 Files selected for processing (7)

• .github/workflows/ci.yml
• .pre-commit-config.yaml
• deploy/gitops/README.md
• deploy/gitops/environments/local/inventory.yaml.template
• deploy/gitops/environments/local/keycloak/realms/insight-broker.yaml
• deploy/gitops/environments/local/sealed-secrets/insight/insight-keycloak-config-sealedsecret.yaml.template
• scripts/ci/realm_secret_guard.py