Skip to content

Commit 3aa9c29

Browse files
committed
docs(monitoring): explicit oidc.grafanaAdmin flag + mode-toggle group 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 <[email protected]>
1 parent 5fd4658 commit 3aa9c29

1 file changed

Lines changed: 2 additions & 1 deletion

File tree

‎content/en/docs/next/operations/services/monitoring/oidc-authentication.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ Cozystack provisions:
4343
- A persistent Kubernetes Secret carrying the confidential `client-secret` (random on first install, preserved on upgrades).
4444
- The Grafana CR's `spec.config.auth.generic_oauth` section wired to the cozy realm issuer, per-instance audience scope, and a `role_attribute_path` that maps the three groups above to Grafana's `Admin` / `Editor` / `Viewer` roles.
4545

46-
The platform Grafana release (`monitoring-system` in the `cozy-monitoring` namespace) additionally gets `allow_assign_grafana_admin: true` so an `Admin`-group member is auto-promoted to server-level `GrafanaAdmin`. Tenant Grafana instances stay at org-level Admin.
46+
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, so an `<clientId>-admin` group member becomes a `GrafanaAdmin` on first login. 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.
4747

4848
### Prerequisite
4949

@@ -123,6 +123,7 @@ The `admin_user` / `admin_password` field on the form stays wired to `grafana-ad
123123
- **`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.
124124
- **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`.
125125
- **`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.
126+
- **Mode toggle wipes `KeycloakRealmGroup` membership.** The three `<clientId>-{admin,editor,viewer}` groups are chart-owned. Flipping `spec.oidc.mode` from `System` to `CustomConfig` or `None` deletes them on the next `helm upgrade` — and every user's membership goes with them. Flipping back recreates the groups empty; the platform operator has to re-populate them by hand. Treat mode toggle like an admin-Secret rotation.
126127

127128
## What's out of scope for this feature
128129

0 commit comments

Comments
 (0)