Grafana Authentication and SSO
Every person who opens Grafana must prove who they are. Small teams start with a username and a password. Larger organisations connect Grafana to a central login system, so employees sign in with their work account and lose access the moment they leave the company. People call this approach single sign-on, or SSO.
The Keycard Analogy
A company building gives each employee a keycard from the human resources desk. Every door in the building trusts that one card. When someone leaves, HR cancels the card, and every door closes at once. SSO works like that card system. The company login service, called the identity provider, issues proof of identity, and Grafana trusts it.
1. User opens Grafana
|
2. Grafana redirects to the Identity Provider (Google, Okta, Azure AD)
|
3. User signs in there (password, MFA)
|
4. Identity Provider sends proof back to Grafana
|
5. Grafana opens the user's session
Login Methods
| Method | Best For |
|---|---|
| Built-in username and password | Small teams, personal servers |
| OAuth with Google, GitHub, GitLab, or Azure AD | Teams that already use those accounts |
| Generic OAuth (Okta, Keycloak, Auth0) | Companies with a standard identity provider |
| LDAP or Active Directory | Offices with a directory server |
| SAML | Enterprise single sign-on, available in Grafana Enterprise and Grafana Cloud |
| Auth proxy | A reverse proxy that handles login before Grafana |
| JWT | Embedding Grafana in an application that signs tokens |
Secure the Built-in Login First
Even with SSO in mind, protect the default login.
- Change the default admin password at the first login.
- Disable open sign-up with allow_sign_up = false in the [users] section.
- Disable anonymous access unless you want public dashboards.
- Serve Grafana over HTTPS so passwords never cross the network in plain text.
Set Up Google OAuth
Google login suits many teams. Create OAuth credentials in the Google Cloud console, and add your Grafana address as an authorised redirect address. Copy the client ID and the client secret. Add them to the configuration file.
[auth.google]
enabled = true
client_id = YOUR_CLIENT_ID
client_secret = YOUR_CLIENT_SECRET
scopes = openid email profile
allowed_domains = mycompany.com
allow_sign_up = true
Restart Grafana. A Sign in with Google button appears on the login page. The setting allowed_domains restricts access to accounts at your company domain. Keep the client secret private and out of version control. Use an environment variable such as GF_AUTH_GOOGLE_CLIENT_SECRET when you can.
Generic OAuth for Other Providers
Providers such as Okta and Keycloak follow the same pattern through the [auth.generic_oauth] section. You supply the client ID, the client secret, and three web addresses from the provider: the authorisation address, the token address, and the user information address.
[auth.generic_oauth]
enabled = true
name = Company Login
client_id = YOUR_CLIENT_ID
client_secret = YOUR_CLIENT_SECRET
scopes = openid email profile
auth_url = https://login.mycompany.com/authorize
token_url = https://login.mycompany.com/token
api_url = https://login.mycompany.com/userinfo
Map Roles Automatically
SSO tells Grafana who a person is. Role mapping tells Grafana what that person may do. Grafana can read a group or role claim from the identity provider and convert it into a Grafana role.
Identity provider group Grafana role
----------------------- ------------
grafana-admins --> Admin
grafana-editors --> Editor
everyone else --> Viewer
Use the setting role_attribute_path to describe the mapping. Manage group membership in the identity provider, and Grafana follows along. Joiners and leavers need no manual work in Grafana.
LDAP and Active Directory
Turn on LDAP in the [auth.ldap] section and point it to a file that describes your directory server, the search filters, and the group mappings. Users sign in with their directory username and password. Grafana asks the directory server to verify them.
Add Multi-Factor Authentication
Grafana relies on the identity provider for multi-factor checks. Enable MFA in Google, Okta, or Azure AD, and every Grafana login benefits. This approach keeps one policy for every company application.
Session and Token Settings
The [auth] section controls how long a session lasts and when Grafana refreshes it. Shorter sessions reduce risk on shared computers, and longer sessions reduce interruptions. Choose a balance that fits your policy.
Troubleshooting
Redirect Mismatch Error
The redirect address in the provider must match your Grafana address exactly. Check the protocol, the domain, and the path. Set root_url in the [server] section correctly when a proxy sits in front of Grafana.
User Gets the Wrong Role
Inspect the claims the provider sends and compare them with your role mapping expression.
Login Works for Some Users Only
Check allowed_domains and any group restrictions in the configuration.
Checklist
- Use HTTPS everywhere.
- Restrict sign-in to your company domain.
- Map roles from identity provider groups.
- Keep a break-glass local admin account with a very strong password, stored safely.
- Review who holds Admin rights every quarter.