docs(monitoring): add OIDC authentication guide for Grafana#597
docs(monitoring): add OIDC authentication guide for Grafana#597IvanHunters wants to merge 3 commits 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. |
📝 WalkthroughWalkthroughThis PR adds a documentation page covering OIDC authentication for Cozystack Monitoring Grafana instances, including authentication modes, per-instance audience isolation, role and group handling, prerequisites, reconciliation, break-glass access, and operational limitations. ChangesOIDC Authentication Documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Suggested reviewers: 🚥 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
… loss note
Two doc updates paired with the cozystack chart fix:
- Server-level GrafanaAdmin promotion is now driven by an explicit
spec.oidc.grafanaAdmin: true field (was: chart-side .Release.Name
detection). Document the new field and where the platform bundle
flips it on.
- Mode toggle (System → CustomConfig/None) deletes the three
chart-owned <clientId>-{admin,editor,viewer} KeycloakRealmGroups
and every user's membership goes with them. Not a bug, but a one-
way UX cost on the toggle — document it under Prerequisites and
gotchas so operators know before flipping.
Signed-off-by: IvanHunters <xorokhotnikov@gmail.com>
…ob architecture
The website doc was written against the initial PR#3176 shape
(three chart-owned KeycloakRealmGroups + role_attribute_path mapping
groups to Admin/Editor/Viewer). Later commits on the code PR dropped
that architecture entirely — chart-owned groups gone (commit
3b36966e2), role_attribute_path replaced with skip_org_role_sync +
app-side users-map reconciled by a Job (commit sequence 2b3751edc /
7e2ac3cb8 / 4e8c5f4ed / e47308961 / b370998fc / efc27b33c). The
website guide had drifted six revisions behind the code.
Rewrite covers the actual current surface:
- spec.oidc.users[] with Grafana org-role (Admin/Editor/Viewer) is
the assignment mechanism; users-Job reconciles it on every helm
action.
- Login authorization is separate: allowed_groups gate on the
tenant-scoped <ns>-{view,use,admin,super-admin} groups from the
platform-managed cozy realm.
- groups_attribute_path=groups is REQUIRED on Grafana v11.x+
alongside allowed_groups (matches the code fix committed on the
cozystack side).
- CustomConfig inline vs secretRef with the users[] compatibility
contract (secretRef requires users: []).
- Mode-toggle gotcha now describes the users-Job's ephemeral-account
cleanup, not the deleted KeycloakRealmGroups.
Also drops the stale role_attribute_path example that used a
grafana-admins group name that this chart never provisioned.
Signed-off-by: IvanHunters <xorokhotnikov@gmail.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
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 `@content/en/docs/next/operations/services/monitoring/oidc-authentication.md`:
- Line 53: Update both fenced configuration blocks in the OIDC authentication
documentation to include an appropriate language identifier, such as ini, on
each opening fence while leaving their configuration content unchanged.
🪄 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
Run ID: 45d325e9-d03d-4247-9dbd-612f36f426c1
📒 Files selected for processing (1)
content/en/docs/next/operations/services/monitoring/oidc-authentication.md
| - A chart-owned **users-reconcile Job** (`<release>-oidc-users`) that syncs `spec.oidc.users[]` into the Grafana instance on every reconcile: creates missing Grafana accounts, patches roles, and prunes stale org members. Runs as a post-install / post-upgrade hook when `users[]` is non-empty; omitted otherwise (BYO-IdP-friendly). | ||
| - The Grafana CR's **`spec.config.auth.generic_oauth`** section wired to the cozy realm issuer, per-instance audience scope, and the tenant-membership gate: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Specify languages for the fenced configuration blocks.
Add a language identifier, such as ini, to both fences so markdownlint passes and syntax highlighting is available.
Proposed fix
- ```
+ ```ini
...
- ```
+ ```iniAlso applies to: 62-62
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 53-53: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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 `@content/en/docs/next/operations/services/monitoring/oidc-authentication.md`
at line 53, Update both fenced configuration blocks in the OIDC authentication
documentation to include an appropriate language identifier, such as ini, on
each opening fence while leaving their configuration content unchanged.
Source: Linters/SAST tools
Aleksei Sviridkin (lexfrei)
left a comment
Aleksei Sviridkin (lexfrei)
left a comment
There was a problem hiding this comment.
NOT LGTM — the page is well-structured and the tone matches the tenant Kubernetes OIDC guide, but three of its claims contradict the code PR it ships alongside (cozystack/cozystack#3176). I checked each against that PR's templates, values and unit tests rather than against its prose.
Business context: a user-facing guide for the new spec.oidc selector on the Monitoring CR, landing in docs/next/ ahead of v1.6.
Blockers
B1: spec.oidc.grafanaAdmin does not exist, and the behaviour it describes is explicitly out of scope
Line 70: "Server-level GrafanaAdmin promotion is opt-in via spec.oidc.grafanaAdmin: true — the chart then sets allow_assign_grafana_admin: true … The platform bundle flips this on for the platform Grafana release."
The oidc struct in packages/extra/monitoring/values.yaml (as added by #3176) has exactly three fields: mode, customConfig, users. There is no grafanaAdmin. The string grafanaAdmin does not appear anywhere in #3176's diff. That PR's own operator guide states the opposite outright: "Server-level GrafanaAdmin promotion (allow_assign_grafana_admin) is out of scope for Phase 1. All Grafana instances — platform and tenant — cap at org-level Admin." And packages/system/monitoring/tests/oidc_test.yaml pins the absence with notExists: spec.config["auth.generic_oauth"].allow_assign_grafana_admin.
An operator following this paragraph would add a field the CR schema rejects. Remove the paragraph, and instead list server-level GrafanaAdmin under "What's out of scope".
B2: the example clientId is wrong
Line 47: "clientId set to <namespace>-<release> (for the CR above: tenant-acme-monitoring-system)."
The rule is right, the worked example is not. monitoring.oidc.clientId is printf "%s-%s" .Release.Namespace .Release.Name, and the Monitoring ApplicationDefinition sets release.prefix: "", so the CR shown just above (name: monitoring, namespace: tenant-acme) produces the release monitoring and therefore the clientId tenant-acme-monitoring. monitoring-system is the platform release name — the one living in cozy-monitoring, which the page itself names correctly two paragraphs earlier. As written, a reader hunting for their KeycloakClient looks for an object that does not exist.
B3: the "mode toggle prunes accounts" gotcha inverts the code
Line 150: "Flipping spec.oidc.mode from System to None prunes every user the users-Job provisioned … Flipping back re-provisions them empty."
oidc-users-job.yaml renders only when spec.oidc.users is non-empty, and its header comment says this is deliberate, naming mode=None as one of three empty-users states it guards: "a prune pass with an empty desired list would silently delete every non-admin Main-Org member on every helm upgrade … Removing the last users: entry therefore no longer prunes it."
So flipping System → None runs no Job and prunes nothing; the local Grafana accounts survive. The page tells operators to treat the toggle "like an admin-Secret rotation" — the opposite of the actual, deliberately-safe behaviour. Worth also re-checking the neighbouring claim under "Assigning roles" that removing a user from the list "deletes the account": the Job's documented action is pruning non-admin Main-Org members, which is an org-membership change, not necessarily account deletion.
Non-blocking follow-ups
- Two operator guides for one feature. #3176 also ships
docs/oidc-grafana.md(410 lines) inside the monorepo, covering the same ground. Two authoritative guides will drift — this PR is already the proof, since all three blockers above are places where this page and that one disagree. Worth deciding which is canonical and having the other link to it. - Docs are ahead of the code. #3176 is still open and unmerged, so nothing yet pins these claims. Sequencing the guide before the code it documents is precisely how the three errors above got in. Re-verify every claim against the merged code once #3176 lands.
- The branch is
BEHINDits base; rebase before merge.
|
|
||
| `skip_org_role_sync=true` keeps a login from overwriting the users-Job's role assignments; `oauth_allow_insecure_email_lookup=true` lets Grafana attach the OIDC identity to the pre-provisioned local account by email; `allow_sign_up=false` is the isolation lever — without it, Grafana's default `allow_sign_up=true` combined with `skip_org_role_sync=true` would mint a Viewer account for every `cozy`-realm identity that hits the login flow. | ||
|
|
||
| Server-level `GrafanaAdmin` promotion is opt-in via `spec.oidc.grafanaAdmin: true` — the chart then sets `allow_assign_grafana_admin: true` on the rendered `[auth.generic_oauth]` block. The platform bundle flips this on for the platform Grafana release (`monitoring-system` in `cozy-monitoring`); tenant Grafana releases inherit the chart default `false` and stay at org-level Admin. |
There was a problem hiding this comment.
spec.oidc.grafanaAdmin does not exist in the code PR this page ships alongside. The oidc struct in packages/extra/monitoring/values.yaml has exactly three fields — mode, customConfig, users — and the string grafanaAdmin appears nowhere in cozystack/cozystack#3176.
That PR states the opposite explicitly in its own guide: "Server-level GrafanaAdmin promotion (allow_assign_grafana_admin) is out of scope for Phase 1. All Grafana instances — platform and tenant — cap at org-level Admin." Its unit suite pins the absence: notExists: spec.config["auth.generic_oauth"].allow_assign_grafana_admin.
An operator following this paragraph would set a field the CR schema rejects. Please drop it and move server-level GrafanaAdmin into the "What's out of scope" section instead.
|
|
||
| Cozystack provisions: | ||
|
|
||
| - A per-instance **`KeycloakClient`** in the `cozy` realm with `clientId` set to `<namespace>-<release>` (for the CR above: `tenant-acme-monitoring-system`). Confidential (`clientAuthenticatorType: client-secret`), `secret` sourced from a chart-owned Kubernetes Secret. `redirectUris` locked to `https://grafana.<host>/login/generic_oauth`. |
There was a problem hiding this comment.
The rule (<namespace>-<release>) is right but the worked example is not. monitoring.oidc.clientId is printf "%s-%s" .Release.Namespace .Release.Name, and the Monitoring ApplicationDefinition sets release.prefix: "" — so the CR shown directly above (name: monitoring in tenant-acme) yields the release monitoring and the clientId tenant-acme-monitoring.
monitoring-system is the platform release name, in cozy-monitoring — which this page names correctly two paragraphs earlier. As written, a reader goes looking for a KeycloakClient that does not exist.
| - **`groups_attribute_path` is not optional on Grafana v11.x+.** The chart wires it automatically for `System` mode; in `CustomConfig` inline the operator must add it explicitly (`groups_attribute_path: groups`) if their IdP emits a top-level `groups` array. Otherwise `allowed_groups` becomes a silent no-op and every login fails. | ||
| - **BYO issuer with a self-signed CA.** In `CustomConfig` mode the `secretRef` path is the way to ship a CA bundle alongside the `[auth.generic_oauth]` block — you package `auth.ini` and any `ca-cert` files into the Secret and mount both under `/etc/grafana/oidc`. | ||
| - **`admin_user` stays a break-glass path.** Even under `mode: System` the login form and the `grafana-admin-password` Secret remain wired. Locking the form off is a follow-up hardening. | ||
| - **Mode toggle drops the users-Job's local accounts.** Flipping `spec.oidc.mode` from `System` to `None` prunes every user the users-Job provisioned (the accounts are ephemeral shadows of `spec.oidc.users[]`). Any dashboards those users starred / owned move to their original creators; the local passwords / API keys go away. Flipping back re-provisions them empty. Treat mode toggle like an admin-Secret rotation. |
There was a problem hiding this comment.
This inverts the code. oidc-users-job.yaml renders only when spec.oidc.users is non-empty, and its header comment says so deliberately, naming mode=None as one of three empty-users states it guards against: "a prune pass with an empty desired list would silently delete every non-admin Main-Org member on every helm upgrade … Removing the last users: entry therefore no longer prunes it."
So System → None runs no Job and prunes nothing — the local Grafana accounts survive. Telling operators to treat the toggle "like an admin-Secret rotation" is the opposite of the actual, deliberately-safe behaviour.
While you are here, please re-check the related claim under "Assigning roles" that removing a user from the list "deletes the account" — the Job's documented action is pruning non-admin Main-Org members, which is an org-membership change, not necessarily account deletion.
2 participants
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
None,System,CustomConfig), required setup prerequisites, and the expected sign-in flow.