Introduction

Single sign-on (SSO) allows users to authenticate once and access multiple applications, including Grafana. Setting up SSO involves configuring Grafana as a service provider that trusts an identity provider (IdP) like Okta, Azure AD, Ping Identity, or ADFS. Configuration errors typically manifest as login failures, attribute mapping issues, or role synchronization problems.

Symptoms

  • SSO login button redirects to an error page
  • Users authenticate with IdP but are not logged into Grafana
  • Error: "SAML response validation failed" or "invalid signature"
  • User attributes (email, name, groups) are missing or incorrect in Grafana
  • Role assignment does not match group membership in IdP
  • Error: "No matching user" or "user not found"

Common Causes

  • SAML metadata or certificates are mismatched between IdP and Grafana
  • Assertion Consumer Service (ACS) URL is incorrect in IdP configuration
  • Attribute statements are not configured correctly in IdP
  • Certificate for signing assertions is expired or wrong
  • Clock skew between Grafana and IdP servers
  • NameID format does not match what Grafana expects

Step-by-Step Configuration

SAML Configuration

  1. 1.Configure SAML in grafana.ini:
  2. 2.```ini
  3. 3.[auth.saml]
  4. 4.enabled = true
  5. 5.single_logout = true
  6. 6.allow_idp_initiated = true

# Identity Provider metadata idp_metadata_url = https://idp.example.com/metadata

# Or use file-based metadata # idp_metadata_path = /etc/grafana/saml-idp-metadata.xml

# Service Provider configuration entity_id = https://grafana.example.com/saml/metadata assertion_attribute_name = displayName assertion_attribute_login = email assertion_attribute_email = email assertion_attribute_org = organization ```

  1. 1.Generate or obtain SP certificate and key:
  2. 2.```bash
  3. 3.# Generate new key pair
  4. 4.openssl req -x509 -newkey rsa:2048 -keyout saml-key.pem -out saml-cert.pem -days 365 -nodes -subj "/CN=grafana.example.com"

# Set permissions chmod 640 saml-key.pem saml-cert.pem chown grafana:grafana saml-key.pem saml-cert.pem ```

  1. 1.Configure certificate paths:
  2. 2.```ini
  3. 3.[auth.saml]
  4. 4.certificate_path = /etc/grafana/saml-cert.pem
  5. 5.private_key_path = /etc/grafana/saml-key.pem
  6. 6.`
  7. 7.Register Grafana as a Service Provider in your IdP:

For Okta: - Application label: Grafana - ACS URL: https://grafana.example.com/saml/acs - SP Entity ID: https://grafana.example.com/saml/metadata - Name ID format: EmailAddress

For Azure AD: - Identifier: https://grafana.example.com/saml/metadata - Reply URL: https://grafana.example.com/saml/acs - User identifier: user.email

  1. 1.Configure attribute mappings in IdP:
  2. 2.`
  3. 3.Name: email
  4. 4.Value: user.email

Name: displayName Value: user.displayName

Name: groups Value: user.groups ```

Role Mapping Configuration

  1. 1.Configure role mapping from SAML attributes:
  2. 2.```ini
  3. 3.[auth.saml]
  4. 4.assertion_attribute_groups = groups
  5. 5.assertion_attribute_role = role

[auth.saml.role_values] admin = Grafana Admins editor = Grafana Editors ```

  1. 1.For more complex role mapping, use organization mapping:
  2. 2.```ini
  3. 3.[users]
  4. 4.auto_assign_org = true
  5. 5.auto_assign_org_id = 1
  6. 6.auto_assign_org_role = Viewer

[auth.saml] org_mapping = "Engineering:engineering-org" role_values_editor = "developers,engineers" role_values_admin = "grafana-admins,platform-admins" ```

OAuth SSO Configuration

  1. 1.For Okta OAuth:
  2. 2.```ini
  3. 3.[auth.okta]
  4. 4.enabled = true
  5. 5.client_id = your-okta-client-id
  6. 6.client_secret = your-okta-client-secret
  7. 7.auth_url = https://your-org.okta.com/oauth2/v1/authorize
  8. 8.token_url = https://your-org.okta.com/oauth2/v1/token
  9. 9.api_url = https://your-org.okta.com/oauth2/v1/userinfo
  10. 10.scopes = openid profile email groups
  11. 11.allowed_domains = example.com
  12. 12.`
  13. 13.For Azure AD OAuth:
  14. 14.```ini
  15. 15.[auth.azuread]
  16. 16.enabled = true
  17. 17.client_id = your-azure-client-id
  18. 18.client_secret = your-azure-client-secret
  19. 19.scopes = openid email profile
  20. 20.auth_url = https://login.microsoftonline.com/tenant-id/oauth2/v2.0/authorize
  21. 21.token_url = https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token
  22. 22.allowed_domains = company.com
  23. 23.allowed_groups = Grafana-Admins Grafana-Editors
  24. 24.`

Troubleshooting SSO Issues

  1. 1.Enable debug logging:
  2. 2.```ini
  3. 3.[log]
  4. 4.level = debug

[log.filters] saml = debug oauth = debug ```

  1. 1.Check SAML metadata:
  2. 2.```bash
  3. 3.curl -k https://grafana.example.com/saml/metadata
  4. 4.`
  5. 5.Verify certificate expiration:
  6. 6.```bash
  7. 7.openssl x509 -in /etc/grafana/saml-cert.pem -noout -dates
  8. 8.`
  9. 9.Test clock synchronization:
  10. 10.```bash
  11. 11.# On Grafana server
  12. 12.timedatectl status
  13. 13.ntpdate -q pool.ntp.org
  14. 14.`

Verification

  1. 1.Test SSO login:
  2. 2.- Navigate to Grafana login page
  3. 3.- Click "Sign in with SSO" or IdP-specific button
  4. 4.- Complete IdP authentication
  5. 5.- Verify successful redirect to Grafana dashboard
  6. 6.Verify user attributes in Grafana:
  7. 7.- Check Configuration > Users
  8. 8.- Verify email, name, and role are correct
  9. 9.- Confirm organization membership
  10. 10.Test SAML metadata exchange:
  11. 11.```bash
  12. 12.curl -k https://idp.example.com/metadata > idp-metadata.xml
  13. 13.# Verify metadata contains correct certificates and endpoints
  14. 14.`