Grafana auth proxy

Grafana supports authentication through a trusted reverse-proxy header. PassBeyond supplies the authenticated subject and optional profile attributes.

Verify your Grafana version

Grafana configuration keys and provisioning behavior can change. Compare this recipe with the auth-proxy documentation for the exact Grafana version you deploy.

Topology

Browser → TLS edge → PassBeyond → private Grafana listener

Grafana must not be publicly reachable. Its auth-proxy allowlist must identify PassBeyond, not the browser or the TLS edge.

PassBeyond configuration

domain: "grafana.example.com"
idpMetadataURL: "https://sso.example.com/metadata.xml"
configPath: "/var/lib/passbeyond/grafana.json"

proxy:
  listenAddress: "127.0.0.1:8123"
  targetURL: "http://127.0.0.1:3000"
  targetDisableSSLVerify: false
  stripVersionHeaders: true
  useBasicAuth: false
  trustedProxies:
    - "127.0.0.1"
    - "::1"

sessionTimeout: 480

Configure the IdP to send a stable email or account name. Email is selected before sAMAccountName as the PassBeyond subject.

Grafana configuration

In grafana.ini:

[auth.proxy]
enabled = true
header_name = X-Passbeyond-User
header_property = username
auto_sign_up = true
sync_ttl = 60
whitelist = 127.0.0.1 ::1
headers = Email:X-Passbeyond-Data-Email Name:X-Passbeyond-Data-Commonname
enable_login_token = false

Adjust whitelist to the actual PassBeyond source IP or narrow container subnet. Do not add the public client range.

If X-Passbeyond-User contains an email address and Grafana should identify it as email rather than username, set header_property according to the supported values for your Grafana version and test account matching carefully.

Restart Grafana after changing its configuration.

User creation and roles

auto_sign_up = true permits Grafana to create a user on the first trusted request. Disable it when accounts must be pre-provisioned.

Do not grant Grafana administrator rights merely because an arbitrary IdP group appears in X-Passbeyond-Data-Groups. Use Grafana's supported role/group synchronization mechanism for the deployed version and allowlist only application-specific groups.

PassBeyond group values are fixed for the lifetime of its JWT. Choose a suitably short sessionTimeout when role changes must take effect quickly.

Logout behavior

Grafana and PassBeyond can each maintain session state. Test both logout paths:

• Grafana logout may leave the PassBeyond JWT valid, causing immediate auth-proxy login on the next request.
• /saml/slo clears PassBeyond and may log out at the IdP, but an existing Grafana session can have its own lifetime.

Provide users with the logout path that matches the intended organization-wide behavior.

Validate

1. Block direct public access to port 3000.
2. Open Grafana through PassBeyond in a private browser window.
3. Confirm the expected Grafana user is selected or created.
4. Verify email and display name without exposing extra attributes.
5. Send a forged public X-Passbeyond-User; it must not select that user.
6. Test a user without the required application group.
7. Test both Grafana logout and /saml/slo.

If Grafana shows its normal login page, confirm auth proxy is enabled, the header name is exact, and the request source matches whitelist. See Troubleshooting.