How authentik signs Grafana users in with generic OAuth
If your team runs self-hosted Grafana and wants one login for operators and viewers, authentik acts as the OAuth2/OIDC provider and Grafana acts as the client through its generic OAuth option. In this setup, authentik authenticates the user, issues tokens and returns identity claims, and Grafana trusts those claims to create the session and assign a role. Grafana's generic OAuth support is available in all editions according to the Grafana authentication docs, so you do not need an enterprise license for this path. SAML, team sync, active sync and SCIM provisioning are the exceptions, and those require Grafana Enterprise or Grafana Cloud.
The exact redirect URI, client settings and environment variables must come from the authentik integration guide for Grafana and Grafana's configuration reference for generic OAuth, not from memory or from older blog posts. Confirm the callback path against the Grafana version you run, since Grafana 13.2.0 and the 13.x patch line are current in the upstream release history, and a mismatched path is the most common cause of a failed first login. Record the client ID, the client secret handling, the issuer or discovery endpoint and the scopes you request, because each one must match on both sides. DeployOpen confirms these values against your running authentik and Grafana versions before anything is switched on for users.
Plan the rollout around the two ends of the trust relationship. On the authentik side, decide which application and provider objects grant access and which claims Grafana receives, because those claims decide who becomes an operator and who becomes a viewer. On the Grafana side, decide whether local login stays enabled as a break-glass path and whether automatic login is turned on, since both change who can reach the login page after cutover. Test one operator account and one viewer account end to end, including logout and a session after the access token expires, before you move the rest of the team.
What you need before configuring the Grafana connection
Six items need to be settled before anyone opens the Grafana configuration file. Each one fixes a version, an address, an account or a mapping that the OAuth connection depends on, so confirming them first avoids reworking the redirect URI, the role mapping and the test plan later.
A supported authentik release
Check that your authentik server and worker run a release that still receives security fixes. The authentik security policy lists 2026.5.x and 2026.8.x as supported, and 2026.8.4 is the latest release on the releases page. Confirm the version you plan to deploy against the policy before you build, because the OAuth provider settings you create depend on it. Note that authentik upgrades must follow the documented sequence, so record the current version now.
A Grafana release and its window
Pick the Grafana minor version you will run and confirm it is inside Grafana's support window. Grafana 13.2.4 and 13.1.8 were patch releases dated October 13, 2026, so the patch level matters as much as the minor line. Grafana supports each minor release for 9 months and the last minor of a major version for 15 months. Check the upgrade guidance for your chosen line before you commit to the OAuth settings.
A production database for Grafana
Grafana stores its configuration in SQLite 3 by default, but its installation docs say SQLite does not scale for production. Plan for MySQL 8.0 or later or PostgreSQL 12 or later, and provision it before the SSO work begins. Users and their OAuth-linked accounts are stored in this database, so changing it after go-live means migrating identities. Ask your team which database platform and backup routine they already operate for Grafana.
Public HTTPS hostnames for both services
Give authentik and Grafana stable, publicly resolvable HTTPS hostnames with certificates that browsers trust. The Grafana root URL and the redirect URI registered in authentik must match exactly, including scheme, host and path. Mismatches are a common cause of failed sign-in. Decide the hostnames before you create the provider, since changing them later means updating both the authentik provider and the Grafana configuration together.
Administrator accounts on both sides
Confirm that you have a named administrator in authentik who can create providers, applications and property mappings, and a separate Grafana administrator who can edit the configuration file or environment variables. Keep the local Grafana admin login available as a break-glass path until the OAuth login has been tested end to end. Avoid sharing a single administrator account across both platforms, so that changes can be traced in each audit log.
Group-to-role mapping and test users
Write down which authentik groups or application entitlements map to Grafana Admin, Editor and Viewer roles before configuration starts. Then create one test user for each role. The role mapping lives in claims that authentik sends with the token, so an unplanned group name or a missing entitlement will silently place a user in the wrong Grafana role. Confirm each test user's expected role on paper first, then verify it after login.
Configuration sequence from authentik provider to Grafana login
This sequence connects an authentik OAuth2/OIDC provider to Grafana's generic OAuth login, maps authentik entitlements to Grafana roles, and ends with a verified login for each role.
Create the OAuth2/OIDC provider and application
An authentik administrator creates an OAuth2/OIDC provider and an application that uses it, then records the client ID and client secret for later use in Grafana. Set the redirect URI to the callback path given in the authentik Grafana guide, using the exact URL of your Grafana server, including the scheme and port. Check that the provider lists the issuer and endpoint URLs authentik generated, because Grafana needs them in the next steps. Done means the provider is saved, bound to the application, and the client credentials are stored in your secrets tool, not in a shared document.
Set scopes and claims Grafana requires
Still in the provider settings, the administrator confirms the scopes Grafana will request, such as openid, profile and email, and checks that the standard claims carry the username, display name and email Grafana needs to create the user. Add a property mapping or scope mapping only if a claim Grafana expects is missing. Confirm the exact scope names against the Grafana authentication documentation for generic OAuth. Check by running a test login with a pilot account and decoding the ID token or viewing the userinfo response. Done means the test token contains a stable user identifier, an email address and the group or entitlement claim you plan to use.
Define entitlements that map to Grafana roles
The identity owner decides which authentik groups or application entitlements correspond to Grafana Admin, Editor and Viewer, and creates them in authentik. Assign a small pilot group to each role so the mapping can be tested before wider rollout. Make sure the group membership appears in the token as a claim, with a name that the Grafana role expression can read. Grafana uses a role attribute path expression, set through the
role_attribute_pathkey, to read that claim, so write the expression on paper first and confirm its syntax in the Grafana authentication docs. Done means each pilot group produces a claim value that matches exactly one planned role.Enter OAuth settings as Grafana configuration
A Grafana administrator enables generic OAuth in the Grafana configuration, either as environment variables or in grafana.ini, and enters the client ID, client secret, authorization URL, token URL and userinfo URL from the authentik provider. The environment variables follow the pattern
GF_AUTH_GENERIC_OAUTH_CLIENT_IDandGF_AUTH_GENERIC_OAUTH_CLIENT_SECRET, and the endpoint keys are documented in the Grafana authentication guide. Store the secret in your secret manager and inject it at runtime rather than writing it into a file in version control. Also set the role attribute expression from the previous step. Done means the configuration file or environment loads without errors when Grafana starts.Restart Grafana and confirm the login button
The administrator restarts the Grafana service or container so the new authentication settings load, then opens the Grafana login page in a private browser window. A sign-in option for the generic OAuth provider should appear alongside any existing local login. Check the Grafana server logs for startup errors about the OAuth configuration, such as a failed discovery or an invalid client secret. Keep local admin login available during this step so you can recover if the configuration is wrong. Done means the provider button appears, the page loads without a TLS or redirect error, and the log shows Grafana started with generic OAuth enabled.
Test login with one user per role
Sign in through the new button with one pilot user from each authentik group created earlier. After each login, open the Grafana user profile or the organization users page and confirm the role shown matches the mapping, for example Admin for the administrator group and Viewer for the read-only group. Repeat the test with a user who belongs to no mapped group and confirm that Grafana either denies access or assigns only the default role you configured. Record the user, group, expected role and observed role in a table for the change record. Done means each test account shows the expected role, and the unmapped account is denied or limited as your policy requires.
Confirm denial for users outside the group
Test a user who exists in authentik but is not assigned to any application entitlement or Grafana group, and confirm that the authentik application policy blocks sign-in or that Grafana places the user in no role. Also test a deactivated authentik account to confirm that an existing session cannot be used to reach Grafana after the account is disabled, and review how long that session persists in your configuration. Ask the authentik administrator which policy binding controls access to the application, because application access and Grafana role assignment are separate controls. Done means the outside-group user is refused or limited, and the test result is saved with the other role tests.
Mapping authentik attributes and entitlements to Grafana fields
This table compares each authentik source attribute with the Grafana setting or role it feeds and the check that confirms it works. Read it as a checklist to run in a test tenant before any group is granted access. Claim names, role paths and team handling vary by authentik scope mapping and Grafana version, so confirm each of those cells in your own environment before relying on them.
| Item | authentik source and token claim | Grafana setting or role | Validation check |
|---|---|---|---|
| Login identifier | Chosen user attribute, such as username or a stable subject value (claim name to be confirmed in environment) | Login and user identity in Grafana (to be confirmed against the generic OAuth login attribute setting) | Sign in with two test users and confirm each maps to one distinct Grafana account |
| Display name | Name claim from the scope mapping (claim name to be confirmed in environment) | Grafana user name shown in the profile and audit views | Confirm the displayed name matches the authentik user profile after first login |
| Email address | Email claim, typically released by the openid and email scopes (to be confirmed in environment) | Grafana user email, used for notifications and sometimes for account matching | Check the email in the Grafana user record matches authentik and that a changed email behaves as expected |
| Entitlements or groups claim | Groups or entitlements claim added by a custom scope mapping (claim name and path to be confirmed in environment) | Input to the role decision; Grafana reads a configured role path from the token | Decode a test token and confirm the group values appear exactly as the role path expects |
| Admin role decision | Membership in the admin group or entitlement assigned to the Grafana application | Organization Admin role when the role path evaluates to Admin (role path to be confirmed for your Grafana version) | Log in as an admin-group user and as a non-admin user, then compare their role under Administration |
| Editor role decision | Membership in the editor group or entitlement | Editor role when the role path evaluates to Editor (to be confirmed for your Grafana version) | Confirm an editor can edit dashboards and a viewer cannot save changes |
| Viewer role decision | Default group or any remaining authorized user | Viewer role as the fallback when no higher role matches (to be confirmed for your Grafana version) | Test a user with no matching group and confirm access is denied or limited to Viewer as designed |
| Org or team membership | Organization or team naming pattern in the claim, if used (to be confirmed in environment) | Organization assignment is set by the role path or org attribute; team sync is an Enterprise or Grafana Cloud feature according to the Grafana authentication docs | Confirm users land in the intended organization, and that team membership is managed manually or by the Enterprise option you have licensed |
Role mapping choices by Grafana edition
Grafana Open Source and self-managed editions support generic OAuth sign-in, so authentik can send a claim that Grafana maps to an organization role such as Viewer, Editor or Admin. The mapping is driven by the claim values authentik includes in the token, which you set through scope mappings tied to your authentik application entitlements. Team sync is not available in these editions, so group membership cannot be copied into Grafana teams for folder or dashboard permissions.
- Role source: the role comes from a claim evaluated at login, so it is refreshed each time a user signs in.
- Team permissions: teams are managed by hand inside Grafana or through provisioning, not synced from authentik groups.
- Admin access: restrict which entitlements can produce the Admin role and test that mapping with a non-production user.
- Self-managed operations: you own the upgrade cadence and the database choice, including SQLite versus PostgreSQL for production.
Confirm in the Grafana authentication docs which generic OAuth settings your version supports for role mapping and whether team sync is listed for your edition before you commit to a design.
Grafana Enterprise adds SAML, team sync, active sync and SCIM provisioning on top of the open-source features. Team sync lets Grafana teams follow group membership from your identity provider, so dashboard and folder permissions can be granted to a group once and kept current as people join or leave. This is most useful when many teams own separate dashboards and access must follow an organizational structure rather than individual edits.
- Who decides: the platform or observability lead proposes the model, and the security or IAM owner approves group ownership in authentik.
- License cost: Enterprise is a commercial license. Ask Grafana Labs for a written quote and compare it with the effort of maintaining teams manually.
- When it is worth it: many teams, frequent membership changes, or audit requirements for access reviews.
- When it is not: a small group of administrators where role claims already cover the need.
- Licensing terms: review the Grafana Labs licensing page to understand how the Enterprise option differs from the AGPLv3 open-source components.
Confirm in the Grafana authentication docs which team sync settings apply to your version and how group identifiers must be passed from authentik before you plan the license purchase.
Grafana Cloud is a hosted service, so Grafana Labs operates the instance and the supported authentication options are set through the Cloud product rather than your own configuration files. Team sync carries the same Enterprise-only limit as on self-managed Enterprise, which means a team-based model depends on the Cloud tier you buy. Your authentik work is still needed for the OIDC application, redirect URIs and the claims that drive roles, but the hosting, upgrades and database are handled by the provider.
- Who decides: the platform owner chooses the tier, and procurement confirms the commercial terms.
- Pricing: Grafana Cloud pricing is on the Grafana pricing page, which lists a free tier, a Pro tier with a platform fee plus usage, and an Enterprise tier with a minimum annual commitment. Use it to build a quote, and ask how usage is metered for your data volume.
- Network reach: confirm that your authentik instance is reachable from the Grafana Cloud sign-in path and that certificates and redirect URIs match the Cloud stack URL.
- Data residency: confirm where Cloud stores your telemetry and identity-related data.
- Exit path: ask how dashboards and provisioned resources can be exported if you change providers.
Confirm in the Grafana authentication docs which sign-in methods and team sync features your Cloud tier includes before you finalize the mapping design.
Hardening the authentik to Grafana connection
A working authentik to Grafana sign-in can still leave a path open to account takeover, role escalation or metrics exposure. The six controls below cover the connection itself, the people who can change role mappings, and the Grafana settings that protect sessions and the metrics endpoint.
Enforce HTTPS on both endpoints
The Grafana redirect URI and the authentik provider's redirect and callback endpoints should both use HTTPS with valid certificates. Authorization codes and tokens travel through the browser on these URLs, so plain HTTP lets an attacker on the network read or replay them. Check that the root URL Grafana advertises matches the public address authentik redirects to, because a mismatch causes login loops or redirects to an unexpected host.
Keep the client secret out of config files
The OAuth client secret that Grafana uses to exchange codes should not sit in plain grafana.ini or in a version-controlled file. Pass it through an environment variable sourced from your secrets store, and restrict read access to the Grafana host and its service account. Rotate the secret in authentik and in the secret store together, and confirm that Grafana logs and support bundles do not echo it.
Limit who can change role mappings
The mapping from authentik groups or application entitlements to Grafana roles decides who becomes an Admin. Restrict edit rights on the Grafana provider, its property mappings and the groups that feed them to a small set of administrators, and require a second reviewer for changes that grant Admin. Confirm what the Open Source edition records when these objects change, because authentik lists enhanced audit logging as an Enterprise feature.
Require MFA for Admin role users
Grafana Admin users can change data sources, alert rules and user roles, so their sign-in should be stronger than a password alone. Add an authenticator stage to the authentication flow that applies only to users whose authentik groups map to the Grafana Admin role, using a policy bound to that group. Test the flow with an Admin account before enforcing it, and keep a documented recovery path for lost second factors.
Apply Grafana cookie and browser settings
Grafana's security hardening guidance recommends secure cookies, SameSite cookies, a Content Security Policy and Trusted Types. Set the cookie options in the [security] section of grafana.ini (or the matching environment variables), then test the OAuth callback after each change, since a strict SameSite value can block the return from authentik. Enable domain verification so requests with unexpected host headers are rejected.
Require authentication on metrics
Grafana exposes a metrics endpoint that can reveal version and runtime details. The hardening guidance recommends requiring authentication for it, and the setting to change is in the Grafana configuration rather than in authentik. Confirm that your Prometheus scrape job presents valid credentials, and that the endpoint is not reachable from outside your monitoring network, including through a reverse proxy that forwards all paths.
Common Grafana login failures and their causes
This table pairs each sign-in symptom with its likely cause and a check the team can run to confirm it before changing settings. Work down the rows in order when a login fails, since the redirect and callback checks come before role and folder questions. The main takeaway is that most failures trace to a mismatch between the authentik provider settings and the Grafana configuration, not to the sign-in itself.
| Symptom | Likely cause | Fix and check to run |
|---|---|---|
| authentik shows an error page after Grafana redirects to it | The redirect URI registered in the authentik OAuth2/OIDC provider does not exactly match the callback URL Grafana sends, including scheme, host, port and path. | Compare the redirect URI in the authentik provider with the Grafana callback URL built from the root_url setting. Correct the provider entry so both match character for character, then retry in a private browser window. |
| Grafana loops back to the login page after authentik sign-in succeeds | The session cookie is not accepted on return, often because the cookie security or SameSite settings do not fit the HTTPS setup, or the Grafana domain does not match the configured root URL. | Check the Grafana log for cookie or state errors. Confirm the root_url matches the address users type, that the site runs over HTTPS when cookie_secure is enabled, and that no reverse proxy rewrites the host header. |
| Users sign in but receive the wrong Grafana role | The role attribute path in the Grafana generic OAuth settings does not match a claim present in the token, so Grafana falls back to a default role. | Inspect an ID token or userinfo response for a test user in authentik. Confirm the claim named in role_attribute_path exists, that its value matches the expected role names, and that the authentik property mapping includes the entitlement or group. |
| Users sign in but see no dashboards or folders | The user is in the right authentik group, but Grafana places them in a different organization or assigns a role that cannot view the folders. | Check the user's organization and role under Grafana administration. Confirm the auto-assigned organization setting and the role mapping, then verify folder permissions for the team or organization. |
| Grafana rejects the client secret after rotation | The new secret was generated in authentik but not updated in the Grafana configuration, or the running Grafana process has not reloaded its environment variables. | Confirm the value of the Grafana client secret environment variable matches the secret shown for the provider in authentik. Restart Grafana after the change and check the log for invalid client errors. |
| Callback fails with an HTTPS or certificate error | Grafana or the reverse proxy presents a certificate that the browser or the server does not trust, or the authentik token endpoint is reached over an untrusted chain. | Test the authentik issuer and token endpoints from the Grafana host with a TLS client. Install the internal certificate authority where needed and confirm the root_url and redirect use https. |
| Sign-in works in the browser but Grafana cannot reach authentik for token exchange | Grafana server-side calls to the token or userinfo endpoint are blocked by network rules, DNS or proxy settings, even though the browser can reach authentik. | Run a request to the token and userinfo endpoints from the Grafana container or host. Check DNS resolution of the authentik hostname from that network and any outbound proxy variables. |
Questions buyers ask before connecting authentik to Grafana
Can our team connect authentik to Grafana without outside help?
Yes, a team with administrative access to both authentik and Grafana can build this connection itself, because Grafana's generic OAuth setting accepts an OpenID Connect client from any identity provider. The work is mostly configuration: creating an OAuth2/OIDC provider and application in authentik, setting the redirect URI, adding the Grafana environment variables, and testing sign-in. Teams usually ask for outside help when the role model is large, when MFA and access rules must be designed alongside the connection, or when several Grafana instances must share one approach. A written scope lets you decide which parts to keep in-house.
What drives the effort of an authentik and Grafana SSO project?
The main drivers are the number of roles you need to map, the directory behind authentik, the MFA rules you want enforced, the Grafana edition in use, and the number of Grafana instances that will trust the same authentik application. Each additional role adds a mapping rule and a test case. An existing directory such as LDAP or Active Directory adds source synchronization work before group mapping can be trusted. Multiple Grafana instances add redirect URI entries, separate test passes and a consistent configuration. Ask any provider to break its quote down along these lines.
Does Grafana SSO with authentik require Grafana Enterprise?
No, Grafana Enterprise is not required for OAuth-based single sign-on with authentik. According to the Grafana authentication documentation, generic OAuth is available in all editions, so authentik can serve as the OAuth provider on Grafana Open Source. What Enterprise adds in this area includes SAML, team sync, active sync and SCIM provisioning, which are only available in Grafana Enterprise and Grafana Cloud. Confirm the current edition matrix on the Grafana licensing page before you commit, because feature availability can change between releases.
Can we map authentik groups to Grafana roles without Enterprise team sync?
Yes, role mapping can be driven from claims in the OAuth token without Grafana Enterprise team sync. The usual approach is to have authentik include group information in the token, then use a Grafana role expression that checks those groups and assigns Viewer, Editor or Admin. Team sync, which places users into Grafana teams automatically, is a separate Enterprise feature, so teams that depend on it need to plan a different model. Test each role with a user from every authentik group, including users who belong to no group, so unassigned access is caught before go-live.
What do we need to provide for an authentik and Grafana integration?
You need three things ready before work starts. First, an authentik administrator who can create providers, applications, groups and property mappings. Second, a Grafana administrator who can edit the configuration file or environment variables and restart the service. Third, a named owner for the role model who decides which authentik group maps to which Grafana role and approves changes. A written test plan should also exist, covering sign-in, role assignment, logout, denied access and the fallback local admin account. Agree on test users and the environments where tests run.
How do authentik and Grafana upgrades affect the SSO connection?
Upgrades can change either side of the connection, so each upgrade needs a short retest. Grafana publishes minor releases every other month and patch releases at least monthly, and each minor release is supported for 9 months according to its upgrade guidance. authentik publishes releases named by year and month, and its security policy lists the supported versions that receive security fixes, so confirm your version is still supported before planning. After either upgrade, retest sign-in, role assignment for each group, logout and the local admin fallback. Keep the redirect URI and environment variables in version control so changes are visible.
How is a fixed-scope authentik and Grafana engagement agreed?
A fixed-scope engagement is agreed in writing before any work starts. The written scope should list the Grafana instances in scope, the authentik application and provider configuration, the role model, the test plan, the deliverables and the timeline. DeployOpen does not publish a price list, so a quote follows from that written scope. Ask for the scope, assumptions, exclusions, what the client must provide and how changes after signing are handled. Ongoing support and upgrade testing can be arranged as a separate retainer if you want DeployOpen to retest after each release.
How DeployOpen scopes and delivers the Grafana connection
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including the authentik and Grafana SSO integration described on this page. Engagements are fixed-scope, with scope and deliverables agreed in writing before work starts.
How we scope
- We confirm which authentik and Grafana versions and hosting models are in use before writing the scope.
- The written scope names the redirect URIs, environment variables, and the group-to-role mapping to be delivered.
- We agree in writing which Grafana edition, data sources and login paths are covered, and which are excluded.
How we build
- We configure the authentik OAuth2/OIDC provider and application for Grafana in a test environment first.
- We set Grafana environment variables for generic OAuth and map authentik entitlements to Grafana roles.
- We test sign-in, role assignment, denied access and logout against documented expected results before promotion.
How we hand over
- You receive the configuration, mapping tables and settings documented against your own environment.
- We record the rollback steps, including how to restore local Grafana login if SSO fails.
- We walk your engineers through the change so they can review and operate the integration independently.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Retainer scope covers reviewing authentik and Grafana upgrade notes that affect the integration.
- Your quote follows from the written scope, so ask which upgrade and testing items it includes.
