1

https://grafana.example.com/login?disableAutoLogin=true

That takes you to the username and password form even when auto_login = true keeps redirecting you to the OAuth provider. If you also do not remember the local admin password:

1
2
3
4

# container / pod
grafana cli --homepath /usr/share/grafana admin reset-admin-password 'new'
# package
grafana-cli admin reset-admin-password 'new'

And if the form is disabled ([auth] disable_login_form = true), first set GF_AUTH_DISABLE_LOGIN_FORM=false in the environment and restart.

Roles that undo themselves

You give someone Editor in Administration → Users, and the next day they are Viewer again. Not a bug: on every OAuth login Grafana syncs the organization role with whatever the provider says (or with auto_assign_org_role when the provider says nothing) and overwrites what you set by hand.

Two ways to live with it:

1. Let the provider really be in charge. Map groups or claims to roles with JMESPath and make it strict, so a user with no group does not get in as a default Viewer:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[auth.github]
enabled = true
allow_sign_up = true
auto_login = true
client_id = $__file{/etc/secrets/github-client-id}
client_secret = $__file{/etc/secrets/github-client-secret}
scopes = user:email,read:org
allowed_organizations = my-org
role_attribute_strict = true
allow_assign_grafana_admin = true
role_attribute_path = contains(groups[*], '@my-org/grafana-admin') && 'GrafanaAdmin' || contains(groups[*], '@my-org/grafana-editor') && 'Editor' || contains(groups[*], '@my-org/grafana-viewer') && 'Viewer'

2. Keep Grafana away from the roles. If you would rather manage them in the UI:

1
2

[auth.github]
skip_org_role_sync = true

skip_org_role_sync is per provider (auth.github, auth.google, auth.generic_oauth, auth.azuread, auth.okta, auth.gitlab, SAML). The old global switch [auth] oauth_skip_org_role_update_sync is deprecated; if it is still in your .ini, replace it with the per-provider one.

With Google, hosted_domain and allowed_domains restrict who can log in; without role_attribute_path everyone comes in with auto_assign_org_role (Viewer by default).

Provisioned data sources

Data sources defined in provisioning/datasources/*.yaml (in the Helm chart, datasources.datasources.yaml) have three surprising properties:

• They cannot be edited in the UI when they carry editable: false: the form shows up locked. That is the right thing in production; the change goes in the YAML.
• Secrets go in secureJsonData, not in jsonData: Grafana encrypts them with secret_key before storing them in its database (/var/lib/grafana/grafana.db, SQLite by default) and never returns them through the API. Tokens, passwords and client certificates go there; in jsonData they sit in plain text.
• They do not disappear when removed from the YAML. Grafana only inserts and updates; deleting has to be explicit:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

apiVersion: 1
prune: true                  # recent versions: removes provisioned sources no longer in this file
deleteDatasources:
  - name: Sentry-old
    orgId: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    orgId: 1
    url: http://prometheus-server.monitoring.svc.cluster.local
    isDefault: true
    editable: false
    version: 1
  - name: Sentry
    type: grafana-sentry-datasource
    access: proxy
    orgId: 1
    editable: false
    jsonData:
      url: https://sentry.io
      orgSlug: my-org
    secureJsonData:
      authToken: ${SENTRY_TOKEN}      # environment variable of the Grafana process

Environment variables expand with $VAR or ${VAR}; a literal $ in a secret is written $$.

Traps

• auto_login with several providers is ignored: it only works with a single provider configured for auto-login.
• allow_sign_up = false keeps out any new user from the provider, including the one you just added to the group; the log says “user signup disabled”.
• role_attribute_strict = true with no mapped group rejects the login with “Role attribute not found”; that is what you want, but warn people.
• The local admin still exists with SSO: change its password and keep it in the secret manager, it is your emergency door together with disableAutoLogin.
• The default secret_key (SW2YcwTIb9zpOOhoPsMm) encrypts secureJsonData identically on every Grafana; set your own ([security] secret_key) before provisioning anything, because changing it later invalidates what was encrypted.

References: Configure authentication and Provisioning in the Grafana documentation.

See also

• Proxmox with Keycloak (OpenID) — the same SSO pattern, with Keycloak as the provider.

In Keycloak: Clients → Create client → OpenID Connect, Client ID proxmox, Client authentication On, Standard flow On, Valid redirect URIs https://pve.example.local:8006 and https://pve.example.local:8006/*. Copy the secret from the Credentials tab.

On a Proxmox node:

1
2
3
4
5
6
7

pveum realm add keycloak --type openid \
  --issuer-url https://id.example.local/realms/lab \
  --client-id proxmox \
  --client-key '<client-secret>' \
  --username-claim preferred_username \
  --autocreate 1 \
  --comment 'Keycloak'

Users log in as alice@keycloak. They are created on first login, with no permissions; permissions are still Proxmox ACLs:

1
2
3

pveum group add sso-admins
pveum acl modify / --groups sso-admins --roles Administrator
pveum user modify alice@keycloak --groups sso-admins     # after their first login

How it works

Proxmox has supported openid realms since PVE 7. From issuer-url it downloads /.well-known/openid-configuration and takes the endpoints from there; the login screen shows the realm in the dropdown and the Login button redirects to Keycloak. On the way back, the value of the claim you picked in username-claim becomes the user <claim>@<realm>.

username-claim accepts any claim name. Keycloak sends preferred_username by default (it comes from the username mapper in the profile client scope), so the extra mapper old guides added to expose a claim called username is not needed. If you prefer the email, --username-claim email.

Keycloak, step by step (26)

1. Realm. Use the one you have (lab in the example). The issuer is https://id.example.local/realms/lab. Since Keycloak 17 there is no /auth/ in the path; if you copy /auth/realms/... from an old guide, discovery fails.
2. Clients → Create client.
   • Client type: OpenID Connect. Client ID: proxmox. Name: whatever you like.
   • Capability config: Client authentication On (confidential client, with secret). Standard flow On. Everything else Off: Direct access grants, Implicit flow, Service accounts, Authorization.
   • Login settings: Root URL https://pve.example.local:8006; Valid redirect URIs https://pve.example.local:8006 and https://pve.example.local:8006/*. Web origins empty: it is a redirect flow, there is no CORS.
3. Credentials → Client secret. That is the --client-key.
4. Groups (optional). Clients → proxmox → Client scopes → proxmox-dedicated → Add mapper → By configuration → Group Membership: Name groups, Token Claim Name groups, Full group path Off, Add to ID token and Add to userinfo On.

Proxmox, step by step

Through the GUI: Datacenter → Permissions → Realms → Add → OpenID Connect Server: Issuer URL, Realm (the short name, keycloak), Client ID, Client Key, Username Claim preferred_username, Autocreate Users. Or the pveum realm add from the TL;DR; the configuration lands in /etc/pve/domains.cfg and replicates across the cluster.

With groups coming from Keycloak, on recent PVE 8 releases and on PVE 9 (pveum realm add --help tells you whether your version has --groups-claim):

1

pveum realm modify keycloak --groups-claim groups --groups-autocreate 1

Each group in the claim is created as <group>-keycloak and the user joins them on every login; you assign the ACLs to those groups.

Test before touching anything else: login screen → Realm Keycloak → Login → you come back authenticated and pveum user list shows alice@keycloak.

Traps

• Invalid parameter: redirect_uri in Keycloak: the URL you typed in the browser (name, port 8006, https) is not in Valid redirect URIs. If you use both the IP and the FQDN, add both.
• The node must trust Keycloak’s certificate, not just your browser. With an internal CA: copy the .crt to /usr/local/share/ca-certificates/ and run update-ca-certificates.
• issuer-url has to match exactly the iss in the tokens: https, no trailing slash, /realms/<realm>.
• Time. A skewed clock invalidates tokens; chrony on the nodes.
• Do not let users edit their own username in Keycloak (a warning from Proxmox’s own docs): renaming yourself to root is switching accounts in Proxmox.
• Do not set --default 1 until it works, and keep root@pam as the emergency door: if Keycloak is down, the openid realm cannot authenticate anyone.
• API and CLI. OIDC users have no password in Proxmox; for Terraform, Ansible, or pvesh from outside create a token: pveum user token add alice@keycloak automation --privsep 0.

Reference: User Management — OpenID Connect in the Proxmox guide and client creation in the Keycloak documentation.