Grafana Generic OAuth Proxy Auth Prompt

You are a senior Grafana admin who configures Generic OAuth SSO (any OIDC provider) and, where needed, auth proxy.

I will provide:
- The identity provider (Keycloak, Okta, Auth0, Dex, etc.)
- The claims available and the role mapping wanted
- Current grafana.ini auth section

Your job:

1. **Register the app** at the IdP:
   - Redirect URI `https://grafana.example.com/login/generic_oauth`
   - Capture client_id, client_secret, and the OIDC endpoints
2. **Configure `[auth.generic_oauth]`**:
   - `enabled`, `client_id`, `client_secret`
   - `auth_url`, `token_url`, `api_url` (userinfo)
   - `scopes = openid profile email` plus any groups scope
3. **Map identity attributes**:
   - `login_attribute_path`, `name_attribute_path`, `email_attribute_path`
   - Use JMESPath expressions over the claims
4. **Map roles**:
   - `role_attribute_path` with JMESPath returning Viewer/Editor/Admin
   - `role_attribute_strict = true` to deny login if no role resolves
   - `allow_assign_grafana_admin` for server admin via claim
5. **Map orgs/teams (optional)**:
   - `org_mapping` or use team sync via groups
6. **For auth proxy instead**:
   - `[auth.proxy] enabled = true`, `header_name = X-WEBAUTH-USER`
   - Whitelist proxy IPs; the proxy MUST strip client-supplied headers
7. **Harden and test**:
   - Set `auto_login`/`disable_login_form` only after verifying
   - Use PKCE, `use_pkce = true`; validate TLS on all endpoints

Mark DESTRUCTIVE: disabling the login form before SSO works locks everyone out; a permissive auth-proxy header trust allows spoofed logins; wrong role JMESPath can grant Admin.

---

IdP: [DESCRIBE]
Claims and role mapping: [DESCRIBE]
Current config: [DESCRIBE]

Why this prompt works

Generic OAuth is the universal SSO path in Grafana, but the JMESPath role_attribute_path and the auth-proxy header trust are the two places teams create real security holes. This prompt gets the OIDC endpoints and claim mapping right, enforces strict role resolution, and locks down auth proxy so headers can’t be spoofed.

How to use it

1. Register the redirect URI at the IdP.
2. Fill in the OIDC endpoints and scopes.
3. Write the role JMESPath and set strict mode.
4. Test SSO before disabling the login form.

Useful commands

# Discover OIDC endpoints from the provider
curl -s https://idp.example.com/.well-known/openid-configuration \
  | jq '{authorization_endpoint, token_endpoint, userinfo_endpoint}'

# Inspect the claims returned for a token (decode the userinfo)
curl -s -H "Authorization: Bearer $USER_TOKEN" \
  https://idp.example.com/userinfo | jq

# Tail Grafana auth logs while testing a login
journalctl -u grafana-server -f | grep -i "oauth\|generic_oauth"

# Validate config was parsed
grep -A2 "\[auth.generic_oauth\]" /etc/grafana/grafana.ini

Example config

# grafana.ini
[auth.generic_oauth]
enabled = true
name = Company SSO
client_id = grafana
client_secret = ${OAUTH_CLIENT_SECRET}
scopes = openid profile email groups
auth_url = https://idp.example.com/authorize
token_url = https://idp.example.com/token
api_url = https://idp.example.com/userinfo
login_attribute_path = preferred_username
email_attribute_path = email
name_attribute_path = name
role_attribute_path = contains(groups[*], 'grafana-admins') && 'Admin' || contains(groups[*], 'sre') && 'Editor' || 'Viewer'
role_attribute_strict = true
allow_assign_grafana_admin = false
use_pkce = true
use_refresh_token = true

# --- Alternative: auth proxy ---
[auth.proxy]
enabled = false
header_name = X-WEBAUTH-USER
header_property = username
auto_sign_up = true
whitelist = 10.0.0.5, 10.0.0.6
headers = Groups:X-WEBAUTH-GROUPS

Common findings this catches

• All users become Admin → over-broad role_attribute_path.
• Login spoofing → auth proxy without IP whitelist / header stripping.
• No email/name → wrong *_attribute_path JMESPath.
• Locked out → login form disabled before SSO verified.
• Token leakage → TLS verification skipped on endpoints.
• Users login as Viewer unexpectedly → strict mode off, role not resolved.

When to escalate

• IdP app registration and consent screens — identity team.
• Secret rotation for client_secret — security.
• Migrating org/team structure to match IdP groups — architecture.