docs(monitoring): add OIDC authentication guide for Grafana#597
docs(monitoring): add OIDC authentication guide for Grafana#597IvanHunters wants to merge 1 commit into
Conversation
Guide covers spec.oidc modes (None/System/CustomConfig) on the Monitoring CR, how System mode provisions a per-instance Keycloak client + audience scope + three role-mapping groups in the cozy realm, and how a user logs in through the Grafana browser flow. Placed under docs/next/operations/services/monitoring/ (weight 5, between setup and dashboards); ships alongside the code PR that adds the spec.oidc selector to the Monitoring chart. Signed-off-by: IvanHunters <xorokhotnikov@gmail.com>
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThis PR adds a new documentation page describing OIDC authentication for Grafana instances in Cozystack Monitoring deployments, covering the ChangesOIDC Authentication Documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Related PRs: None specified. Suggested labels: documentation Suggested reviewers: None specified. 🐰 A rabbit hops through Keycloak's gate, 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces documentation for configuring OIDC authentication for Grafana in Cozystack, detailing the available modes (System and CustomConfig), role assignment, and prerequisites. The review feedback suggests minor formatting improvements, such as replacing Unicode ellipsis characters with standard ASCII characters. Additionally, it corrects a technical inaccuracy by clarifying that Grafana does not support Kubernetes-style CEL claimValidationRules and that any such validation must be handled via JMESPath in role_attribute_path.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| role_attribute_path: "contains(groups[*], 'grafana-admins') && 'Admin' || 'Viewer'" | ||
| ``` | ||
|
|
||
| …or via a pre-existing Secret in the tenant namespace holding a ready-made `[auth.generic_oauth]` ini fragment in the `auth.ini` key: |
There was a problem hiding this comment.
Using standard ASCII characters (like starting the sentence directly with Or) is preferred over the Unicode ellipsis character … to ensure consistent rendering and avoid copy-paste issues.
| …or via a pre-existing Secret in the tenant namespace holding a ready-made `[auth.generic_oauth]` ini fragment in the `auth.ini` key: | |
| Or via a pre-existing Secret in the tenant namespace holding a ready-made `[auth.generic_oauth]` ini fragment in the `auth.ini` key: |
| username: alice@acme.example | ||
| email: alice@acme.example | ||
| emailVerified: true | ||
| password: "…" |
There was a problem hiding this comment.
Use standard three dots ... instead of the Unicode ellipsis … inside the code block.
| password: "…" | |
| password: "..." |
|
|
||
| ## Prerequisites and gotchas | ||
|
|
||
| - **`emailVerified: true` on Keycloak users.** Phase 1 does not add a `claimValidationRules` entry — so `email_verified` is not chart-enforced. Set `emailVerified: true` on the `KeycloakRealmUser` (or complete the email-verify flow through the Keycloak UI) so the identity holding a given email is guaranteed authentic. The `cozy` realm's default `duplicateEmails: false` prevents a second account from claiming an already-registered address. CEL `claimValidationRules` to make this a hard gate is a follow-up hardening path. |
There was a problem hiding this comment.
The mention of CEL claimValidationRules seems to be a copy-paste leftover from the Kubernetes OIDC guide. Grafana's generic OAuth does not support Kubernetes-style CEL (Common Expression Language) or claimValidationRules. Instead, claim validation or enforcement of email_verified in Grafana is typically achieved using JMESPath expressions within role_attribute_path (potentially combined with role_attribute_strict: true). Let's update this to refer to JMESPath-based enforcement instead of CEL claimValidationRules.
| - **`emailVerified: true` on Keycloak users.** Phase 1 does not add a `claimValidationRules` entry — so `email_verified` is not chart-enforced. Set `emailVerified: true` on the `KeycloakRealmUser` (or complete the email-verify flow through the Keycloak UI) so the identity holding a given email is guaranteed authentic. The `cozy` realm's default `duplicateEmails: false` prevents a second account from claiming an already-registered address. CEL `claimValidationRules` to make this a hard gate is a follow-up hardening path. | |
| - **`emailVerified: true` on Keycloak users.** The default configuration does not enforce `email_verified` in the role mapping. Set `emailVerified: true` on the `KeycloakRealmUser` (or complete the email-verify flow through the Keycloak UI) so the identity holding a given email is guaranteed authentic. The `cozy` realm's default `duplicateEmails: false` prevents a second account from claiming an already-registered address. Enforcing this in Grafana's `role_attribute_path` via JMESPath is a follow-up hardening path. |
| - **Per-tenant Keycloak realms.** Managed multi-tenant identity is a separate proposal, evaluated against Keycloak Organizations. Track it in the [community proposal](https://github.com/cozystack/community/pull/24). | ||
| - **Federating an external IdP into the platform `cozy` realm.** BYO-for-Cozystack-itself is a distinct problem — this feature is BYO-for-a-managed-service. | ||
| - **Full-logout through Keycloak's end-session endpoint.** Native `auth.generic_oauth` covers the OAuth part; `backend-logout-url` wiring is a follow-up. | ||
| - **CEL `claimValidationRules` for `email_verified`.** Explicit-gate hardening; not required for Phase 1 given the layered guarantees above. |
There was a problem hiding this comment.
Since Grafana does not support CEL or claimValidationRules, we should clarify that this is a limitation of Grafana's OAuth capabilities rather than an out-of-scope feature that could be added later using CEL.
| - **CEL `claimValidationRules` for `email_verified`.** Explicit-gate hardening; not required for Phase 1 given the layered guarantees above. | |
| - **CEL `claimValidationRules` for `email_verified`.** Grafana does not support Kubernetes-style CEL validation rules; any such validation must be done via JMESPath in `role_attribute_path`. |
IvanHunters
requested review from
Andrei Kvapil (kvaps) and
Timofei Larkin (lllamnyp)
as code owners
1 participant
Summary
Adds a new guide under
content/en/docs/next/operations/services/monitoring/: OIDC authentication for Grafana.Documents how to enable per-user OIDC authentication on the Grafana instance shipped by every
Monitoringrelease, using the newspec.oidcselector. Ships alongside cozystack/cozystack#3176, the code PR that adds the selector to the chart. The identity model is per-instance audience isolation on the flatcozyrealm — same shape as the tenant kube-apiserver's Phase 1 (cozystack/cozystack#3044); architectural rationale in cozystack/community#24.What
content/en/docs/next/operations/services/monitoring/oidc-authentication.md(weight: 5, positioned betweensetup.md(2) anddashboards.md(10)).None,System,CustomConfig), the three role-mappingKeycloakRealmGroups the chart owns, how a user is added viaKeycloakRealmUser, browser login flow, and gotchas:emailVerifiedprescriptive requirement, self-signed CA underCustomConfig.secretRef,admin_userbreak-glass posture.claimValidationRules) so readers know where the boundary sits.docs/next/; version-specific pages (v1.5, ...) get the guide when the code PR lands in a release.Why
spec.oidcselector on theMonitoringCR is a new user-facing surface — needs a user-facing guide before v1.6.content/en/docs/next/kubernetes/oidc-authentication.md, docs(kubernetes): add OIDC authentication guide #596), so operators land on a familiar layout./docs/next/operations/services/monitoring/oidc-authentication/.Summary by CodeRabbit