Grafana’s Single Sign-On (SSO) isn’t just about letting users log in with their existing credentials; it’s a gateway to unified access control across your observability stack.
Let’s see it in action. Imagine a user, Alice, who normally logs into Grafana with her company’s Active Directory credentials. She’s used to typing her AD username and password. Now, instead of seeing a Grafana login form, she’s redirected to her company’s Okta login page. She enters her Okta credentials, Okta verifies them, and then redirects her back to Grafana, now logged in as her AD user. No Grafana password needed. This is OAuth in action.
Alternatively, if Grafana is configured with LDAP, Alice might see a "Login with LDAP" button on the Grafana login page. Clicking it presents her with Grafana’s own login form, but when she enters her AD username and password, Grafana queries the LDAP server to authenticate her. If successful, she’s logged into Grafana. This is LDAP authentication.
The magic here is that Grafana acts as a Service Provider (SP) and your chosen identity provider (IdP) – be it Okta, Azure AD, Google Workspace (for OAuth), or Active Directory, OpenLDAP (for LDAP) – acts as the Identity Provider. Grafana trusts the IdP to tell it who the user is and what groups they belong to, and then Grafana uses that information to grant access and assign roles.
The core problem this solves is reducing password fatigue and centralizing user management. Instead of managing users and their permissions in Grafana and your directory service, you manage them in one place. When a new employee joins, they get an account in your IdP, and they can immediately access Grafana. When they leave, disabling their IdP account automatically revokes their Grafana access.
Here’s how it works under the hood, focusing on OAuth as an example. When Alice tries to access Grafana, Grafana redirects her browser to the IdP (e.g., Okta). Alice authenticates with the IdP. The IdP then sends an authorization code back to Grafana. Grafana exchanges this code with the IdP for an ID token and an access token. The ID token contains information about Alice, like her username and group memberships. Grafana then uses this information to log her in and apply any role assignments based on those groups. For LDAP, the flow is simpler: Grafana directly queries the LDAP server to bind (authenticate) with the provided credentials and then searches for user attributes.
The configuration in grafana.ini is where you tie Grafana to your IdP. For OAuth, you’ll need to register Grafana as an application in your IdP to get a client_id and client_secret. You’ll also need the IdP’s auth_url and token_url, and often a api_url for user info. You configure these in the [auth.oauth] section.
[auth.oauth]
enabled = true
name = Okta
allow_sign_up = true
client_id = YOUR_CLIENT_ID_FROM_OKTA
client_secret = YOUR_CLIENT_SECRET_FROM_OKTA
scopes = openid email profile groups
auth_url = https://your-okta-domain.okta.com/oauth2/v1/authorize
token_url = https://your-okta-domain.okta.com/oauth2/v1/token
api_url = https://your-okta-domain.okta.com/oauth2/v1/userinfo
For LDAP, you specify the server address, port, and the search base for users and groups. You can also define filters to map LDAP attributes to Grafana roles.
[auth.ldap]
enabled = true
config_file = /etc/grafana/ldap.toml
The ldap.toml file contains the detailed LDAP server connection and search configurations.
[[servers]]
host = "ldap.example.com"
port = 389
use_ssl = false
start_tls = false
bind_dn = "cn=grafana-reader,ou=serviceaccounts,dc=example,dc=com"
bind_password = "your_bind_password"
[[servers.search_filter_templates]]
name = "users"
search_filter = "(&(uid=%s)(objectClass=user))"
[[servers.group_mappings]]
group_dn = "cn=grafana-admins,ou=groups,dc=example,dc=com"
org_role = "Admin"
[[servers.group_mappings]]
group_dn = "cn=grafana-viewers,ou=groups,dc=example,dc=com"
org_role = "Viewer"
The bind_dn and bind_password are used by Grafana to connect to the LDAP server to perform searches. The search_filter_templates define how to find users based on their login name (the %s is a placeholder for the username entered by the user). group_mappings allow you to assign Grafana roles based on LDAP group membership.
A common pitfall is misconfiguring the scopes in OAuth. If you don’t request groups or equivalent, Grafana won’t receive group information, and role assignments based on groups will fail. For LDAP, incorrect bind_dn or bind_password will prevent Grafana from even querying the directory, leading to authentication failures.
The most surprising thing about Grafana’s SSO configuration is how granular you can get with role mapping, especially when combining LDAP and OAuth. You can define multiple LDAP servers, multiple OAuth providers, and even fallback mechanisms. For instance, you can configure Grafana to first try authenticating via Okta. If that fails, or if the user isn’t found in Okta, it can then fall back to an LDAP lookup. This allows for phased migrations or supporting different authentication methods for different user populations within the same Grafana instance.
Once your SSO is configured, the next logical step is to explore provisioning users and dashboards automatically based on these authenticated groups.