Grafana generic OAuth role mapping

How Grafana generic OAuth role mapping decides who gets which role

If your identity provider already holds groups or app roles, you need Grafana to grant the right role and organization at every sign-in without manual edits. Generic OAuth role mapping is configured in Grafana's generic OAuth settings, and Grafana evaluates a claim from the identity provider on every login to decide the user's role. The integration covers four parts that you must design together: the OAuth client registration, the role_attribute_path expression that reads the role from the token, the org_mapping entries that place users into organizations, and the email claim, which Grafana requires to identify each user. Generic OAuth is available in all editions according to the Grafana authentication docs, so the open-source edition can run this design without an Enterprise license.

Team sync is outside this design. The Grafana authentication docs place team sync, SAML, active sync and SCIM provisioning in Grafana Enterprise and Grafana Cloud only, so mapping a claim to teams is not a generic OAuth option in open source. Before you build, confirm with your identity provider team which attribute will carry the group or app role values, whether it appears in the ID token, the access token or the userinfo response, and how it is formatted. The JMESPath expression you write depends on that shape, and an expression that works in a test token can fail silently for real users whose group lists are larger or nested differently. Plan for the failure cases before go-live. A user whose claim matches no expected value may receive no role or the default role, depending on how strict role handling is configured, so decide in advance whether unmatched users should be refused or admitted with minimal access. Also decide who may hold server admin, since granting it through a claim is a high-impact decision that should be limited to a small, reviewed group. Verify each mapping with test accounts from every group, and check the resulting role and organization in Grafana before you open access to the wider user population.

What you need before mapping roles in Grafana

Role and organization mapping only works when the Grafana instance, its database, the identity provider and the network path are all ready first. The four to six items below are independent workstreams that should be settled before anyone edits the Grafana configuration.

A supported Grafana release

Confirm the Grafana version you plan to run against the current release list on the grafana/grafana releases page before you write any mapping rules. Claim handling and role settings can change between releases, so test your mapping on the exact version you will run in production. Record the version in your change plan, since minor releases and patch releases arrive on a regular cadence and your mapping will need retesting after upgrades.

A production database

Grafana stores users, organizations and role assignments in its configuration database, so mapping results are only as durable as that database. SQLite is not supported for production or high availability, so provision MySQL 8.0 or later or PostgreSQL 12 or later before go-live. Confirm backup and restore for this database, because a lost database means every mapped user and organization membership must be rebuilt.

An identity provider that emits group or role claims

Generic OAuth mapping reads claims from the identity provider's token or user information response, so the provider must be able to send a group or role value for each user. Keycloak, which supports OpenID Connect and OAuth 2.0, is one option. Confirm the exact claim names, their format and how group membership is populated in your provider's own documentation, because these names differ between products and are not interchangeable.

HTTPS and a stable root URL

The OAuth redirect must point to a fixed public Grafana root URL served over HTTPS, and the same value must be registered with the identity provider as the allowed redirect. Changing the hostname later invalidates the client configuration and breaks sign-in for every user. Decide the hostname, certificate ownership and any reverse proxy path before you create the client.

Identity provider admin access

Someone must be able to create an OAuth client, set its redirect and scopes, and add a claim mapper that carries group or role values into tokens. Without that access, the Grafana team can only guess at claim names and will repeat trial-and-error logins. Agree on who owns the provider change, who approves it and who tests a sample user before role mapping is enabled.

An emergency local admin plan

If the mapping is wrong, an administrator can be locked out of Grafana entirely. Keep a local admin account with a tested password stored in your secrets vault, confirm that it can still sign in while generic OAuth is enabled, and document who may use it. Test this path before enabling strict role handling, since a mistake there can remove the only working login.

Configuring generic OAuth role mapping in sequence

This sequence takes an identity provider claim from registration through to a verified sign-in for each Grafana role. Each step closes with a check, so the team can confirm the mapping works before it reaches users. The result is a generic OAuth setup where roles, organizations and server admin rights follow claims the identity provider controls.

Register the Grafana client in the identity provider
The identity team creates an OAuth client for Grafana in the identity provider, using the Grafana callback URL for your deployment as the redirect URI. Request the openid, email and profile scopes at minimum, and add any scope your group or role claim depends on. Record the client ID and secret in your secrets store, not in a shared document. The step is done when the client exists, the redirect URI matches your Grafana root URL exactly, and the identity provider lists the scopes you requested.
Expose the group or role claim and test it
Configure the identity provider to add the group or role claim to the ID token or the userinfo response, depending on what your provider supports. Sign in with a test account that belongs to each group you plan to map. Decode the ID token or call the userinfo endpoint and record the exact claim name, its nesting and its values. The check is a decoded token or userinfo response showing the expected values for every test account. Do not continue until the values are stable across sign-ins.
Enable generic OAuth in Grafana configuration
In grafana.ini, or the matching GF_ environment variables for your deployment, enable the generic OAuth provider and set the client ID, client secret, authorization URL, token URL, API URL and scopes from your identity provider's metadata. Keep the client secret out of the file itself where your deployment allows it. Restart Grafana and check the startup log for the generic OAuth provider being initialized without configuration errors. The Grafana sign-in page should show the provider button, and a sign-in attempt should reach the identity provider.
Write and test the role_attribute_path expression
Set role_attribute_path to a JMESPath expression that reads the claim from step two and returns Admin, Editor or Viewer. Test the expression offline against a saved sample payload from a real token, using a JMESPath evaluator, before you apply it. Confirm the expression returns a role for each test group and returns nothing for users outside the mapped groups. The check is a passing test for each sample payload and the same result in a Grafana test login, with the role visible on the user's profile in the admin pages.
Define org_mapping for each organization
Add org_mapping entries that pair identity provider groups with Grafana organizations and the role each group receives there. Write one entry per organization and group, and keep the syntax exactly as the Grafana authentication documentation describes for your version. Use the organization names as they exist in Grafana, since mismatched names will not map. The check is a sign-in for a user in each group, which should land in the expected organization with the expected role, shown on the organization's user list.
Set strict role handling and the default role
Decide whether a user with no matching claim should be denied, or should receive a default role such as Viewer. Enable strict role handling if your policy requires that users without a mapped role cannot sign in, and confirm the behavior in the configuration reference for your Grafana version. Then test a user outside every mapped group. The check is a denied sign-in or a Viewer account, matching the decision, and a Grafana log line that records the role-mapping outcome for that attempt.
Grant server admin through the documented expression
Grant server admin only through the expression Grafana documents for this purpose, applied to a narrow group that your security team approves. Do not give server admin through the general role expression as a side effect. Record who holds the group and review it on a schedule your organization sets. The check is a single test account in that group that reaches the server admin pages, and a second account outside the group that cannot.
Run a sign-in test for each role
Sign in with one test account for each role and each organization, starting from a clean browser session. Confirm the user lands in the correct organization, holds the expected role, and can or cannot perform the actions that role should allow, such as editing a dashboard. Review the Grafana log for each attempt. The sequence is complete when every test account matches its expected role and organization, and the results are saved with the configuration change record.

Which identity provider claims map to which Grafana settings

This table compares each Grafana setting that reads identity provider claims during generic OAuth sign-in, what it expects, an illustrative example and what to verify before go-live. Read it as a checklist: the email claim and the role expression fail silently or fall back to defaults if they are wrong, so test each row with a real test account.

Grafana setting	What it reads	Example input (illustrative)	What to verify
Email claim	The claim Grafana uses as the user's email address, which it requires for generic OAuth sign-in	email: "jane.doe@example.com"	Confirm the key name in the generic OAuth reference for your version, and test what happens when the claim is absent from the token or userinfo response
Name or login claim	The claim used for the display name and, where configured, the login identifier	name: "Jane Doe"	Confirm which claim your provider populates and that it is unique enough to avoid account collisions
Role path (role_attribute_path)	A JMESPath expression evaluated against the token or userinfo claims to return a Grafana role	An expression returning Admin, Editor or Viewer from a groups array (illustrative)	Confirm exact JMESPath syntax and the accepted role names for your version, and test users in each group
Org mapping (org_mapping)	Entries that place a user in a named organization with a specified role based on a claim value	A group value mapped to an organization name and role (illustrative)	Confirm entry format and organization name matching, and check users who belong to several groups
Default role when no expression matches	The fallback role applied when the role path returns nothing usable	Viewer as the fallback role (illustrative)	Confirm the default and whether strict role handling is enabled, since an unexpected default can grant more access than intended
Server admin expression	A separate expression that decides whether a user receives server administrator rights	A true result for a single named admin group (illustrative)	Confirm the key name and that only a small, named group evaluates to true, then test that other users are not granted server admin

Granting server admin and keeping elevated access narrow

Server admin is a separate grant from organization roles. A user with the Admin role in an organization can manage that organization, but instance-wide control depends on the GrafanaAdmin flag, which is assigned only when allow_assign_grafana_admin is enabled for generic OAuth. Once it is enabled, the role_attribute_path expression can return GrafanaAdmin for matching users. Match a single group that your identity team controls and audits. Broad groups, such as all staff, or groups that application owners can edit, widen the set of people who can administer the whole instance. Illustrative expression: contains(groups, 'grafana-server-admins') && 'GrafanaAdmin' || 'Editor'. Confirm the claim name and group membership rules with your identity provider before you rely on the expression.

Strict role handling decides what happens when the claim does not resolve to a valid Grafana role. With role_attribute_strict set to true, Grafana refuses the login for any user whose claims produce no role, so the group claim becomes a gate as well as a mapping. With it off, those users sign in with the default role configured for the provider. Strict mode protects against a missing or misconfigured group claim quietly admitting people, and it also keeps users outside the intended groups out of Grafana entirely. Decide which behavior you want before go-live. Then check in a test environment how your version treats a user who matches no role, and whether that setting changes the outcome for server admin grants.

Role changes take effect at the next sign-in, not when the identity provider changes group membership, unless your version applies role sync through another mechanism. Confirm the exact timing for your Grafana version in the Grafana authentication documentation before you promise anyone a removal date. Until then, a user removed from the admin group may keep elevated access through an existing session, so plan to revoke sessions where your process requires it. Test with a dedicated account: move it into and out of the admin group, sign in each time, and check the server administration pages. Keep the list of server admins short and reviewed on a schedule that your access policy sets.

Choosing a role strategy by identity provider and team structure

This is the simplest pattern: one Grafana organization, a small set of roles such as Viewer, Editor and Admin, and a single claim that carries the role decision. The claim design is flat. One JMESPath expression in role_attribute_path returns the role for each user, and the expression is short enough to review by reading it. You maintain one expression and, usually, one list of groups or attribute values that map to each role.

Claim design: Choose one claim your provider already populates for group or role membership, and keep the expression to a few conditions.
Expression count: Expect one expression in total. Every change to it affects all users at their next login.
Drift risk: Group names in the provider get renamed or reused, and Grafana keeps the old role until the user signs in again. Confirm how your provider handles deleted groups.
Strict handling: Decide whether a user with no matching claim should fall back to a default role or be denied. Test both cases.
What to test: Sign in as one user per role, plus a user with no group membership, and confirm the resulting role in Grafana's user list.

Before go-live, confirm the claim contents in a test login, since the expression can only work with claims the provider actually sends.

Use this pattern when different teams need separate Grafana organizations with their own dashboards, data sources and admins. Each organization needs its own mapping from provider groups to organization and role, which is typically expressed through org_mapping entries. The claim design has to carry both the organization and the role, so the number of expressions grows with the number of organizations.

Claim design: Use group names that encode organization membership clearly, and keep the organization name list identical in the provider and in Grafana.
Expression count: Plan for one org_mapping entry per organization or group pairing, plus the role expression. Count these before you start so reviews are manageable.
Drift risk: Adding a team in the provider without a matching org_mapping entry leaves that team without access. Removing an organization in Grafana while groups still exist creates orphaned mappings.
Overlap: A user who belongs to groups for two organizations needs a defined outcome. Test whether they land in both, in one, or in the default organization.
What to test: For each organization, sign in with a member, a member of a different team, and a user in no group, and verify the organization and role for each.

Record the mapping in version control so changes go through review, and confirm with the vendor how your release handles multi-organization membership.

Securing the email claim and the sign-in boundary

Role and organization mapping only holds if the identity behind each login is trustworthy and the people who can change it are limited. The cards below pair each control with a check you can run before and after go-live.

Verify the email claim

Grafana uses the email claim to identify a user, so a shared or unverified address can attach one person's account to another's. Confirm in your identity provider that the email attribute is verified, unique per user and not editable by end users. Then sign in with two test accounts that share a display name and confirm each lands in its own Grafana user record. Check the mapping again after any change to attribute sources or directory synchronization.

Restrict who can sign in

Role mapping decides what a user can do after sign-in, but it does not by itself stop people outside your teams from authenticating. Limit the identity provider application to the groups or assignments that should reach Grafana, so unassigned users are refused before Grafana sees the request. Test with an account that is not in any permitted group and confirm the login fails at the provider.

Limit server admin to break-glass

Granting server admin through a claim gives every member of the source group control over the whole instance, including data sources and users. Map server admin to one small, named break-glass group and keep ordinary operators at Admin or Editor within their organizations. Verify by listing server admins in Grafana after a test login and confirming no routine account appears.

Keep the client secret out of version control

The OAuth client secret in grafana.ini or a provisioning file is a credential that anyone with repository access can read. Supply it through an environment variable or a secrets store, and keep only the non-secret settings in files under version control. Verify by searching the configuration repository and the running container's environment for the secret value, and by confirming the secret can be rotated without editing files.

Enforce HTTPS and secure cookies

Sign-in cookies and the OAuth redirect flow must travel only over HTTPS. Follow the Grafana security hardening guidance for secure and SameSite cookie settings, and set the public root URL to the HTTPS address users actually open. Verify by checking the response headers on the login page and confirming the browser sends the session cookie only over TLS.

Review changes to claim mappings

A change to a group claim, an app role or a JMESPath expression can silently move users between roles the next time they sign in. Require a documented review and a named approver for any change in the identity provider that feeds Grafana. After each change, sign in with a representative test account per role and compare the result with the expected role and organization.

Why generic OAuth role mapping fails and how to fix it

This table pairs common symptoms of broken Grafana role and organization mapping with their likely causes and fixes. Read each row against the log or admin page named in the fix column, starting with the symptom your users report. Most failures trace back to the token contents, the JMESPath expression or the org_mapping entries, so check those before changing anything else.

Symptom	Likely cause	Fix
Users land with the default role	The JMESPath expression in role_attribute_path returns nothing for their token, so Grafana falls back to the default role	Decode a sample token from the identity provider and test the expression against it. Check the Grafana server log for the login attempt and confirm the claim name and values match exactly.
Expression looks valid but no role is assigned	The claim is absent from the token because the scope or claim mapper that adds it is missing on the identity provider client	Add the scope or mapper that emits the group or role claim, then sign out and sign in again. Confirm the claim appears in the ID token or userinfo response Grafana reads.
Login fails for some or all users	The email claim is missing or empty, and Grafana needs it to create or match the user	Map the email attribute in the generic OAuth settings to a claim that is always populated for your users. Verify it in the identity provider user profile and in the token sample.
Users reach the wrong organization	org_mapping entries are out of order, use the wrong group values, or do not match the organization names Grafana holds	Review each org_mapping entry against the group values in the token and the organization list under Administration. Correct the order and spelling, then have a test user sign in again.
Server admin is granted or withheld unexpectedly	The role expression or the server admin setting does not match the intended group, or a previous role was cached in the user record	Check the Grafana server admin mapping and the role returned for the test user in the Users page. Remove admin mapping from groups that should not carry it and confirm with a test account.
Redirect URI mismatch at sign-in	The callback URL registered with the identity provider does not match the root URL Grafana is configured to use, including scheme, host, port or path	Compare the redirect URI in the identity provider client with the Grafana root URL and callback path in the server configuration. Correct whichever side differs and retry in a private browser session.
Role changes do not appear until the user signs in again	Grafana assigns the role from the token at login, so changes in the identity provider only reach Grafana on the next authentication	Tell users and administrators that role changes apply at the next sign-in. Confirm the expected session lifetime with your identity provider and plan changes with that delay in mind.
Access works in testing but not for a group in production	The group claim is returned only for a subset of users, or group names differ between environments	Compare token samples from a working and a failing user. Check group membership in the identity provider and confirm the same client and mapper configuration is applied in each environment.

Questions teams ask before setting up Grafana role mapping

Does Grafana role mapping with generic OAuth need Grafana Enterprise?

No. Generic OAuth is available in all Grafana editions, so role mapping from an identity provider claim with role_attribute_path works in the open-source edition. The features that need Enterprise are SAML, team sync, active sync and SCIM provisioning, according to the Grafana authentication documentation. Team sync is the one most teams confuse with role mapping, because it copies group membership into Grafana teams. If you want groups to drive team membership automatically, confirm that requirement early, since it changes the licensing decision. Confirm the current edition feature list against the Grafana authentication documentation before you commit.

What drives the effort of a Grafana role mapping project?

The main drivers are the number of organizations, the design of claims in your identity provider, the number of roles, and how much testing you need across test users. Each organization adds its own org_mapping entries and role rules, so a multi-organization setup takes more design and more verification than a single organization. Claim design matters because the group or app role values your identity provider emits decide what JMESPath expressions can match. If those claims are inconsistent or owned by several teams, the design work grows. Testing scales with the number of roles and edge cases, such as users who belong to no mapped group, users in several groups, and the server admin grant.

How long does Grafana role mapping take to set up?

The duration depends on scope, so ask for it in a written quote rather than relying on a general figure. A single organization with a few roles and an identity provider that already emits clean group claims is a much smaller job than several organizations with unclear group ownership. Ask the provider to state the phases in the quote: claim design, configuration in a non-production Grafana, test sign-ins for each role, and the production cutover with rollback steps. Also ask whether the timeline depends on identity provider changes made by another team, because those approvals often set the schedule more than the Grafana configuration does.

What does my team need to provide for role mapping work?

You need four things before work starts. First, administrator access to the identity provider, so claims and app registrations can be inspected and changed. Second, named owners for each group or app role, who can confirm which users belong and which Grafana role they should receive. Third, test accounts that cover each role and each organization, plus at least one account with no mapped group. Fourth, a sign-off owner who approves the role model and the production cutover. Without these, the work stalls on questions that only your organization can answer, so list them in the scope document and assign a name to each.

Can our own team set up Grafana role mapping without a partner?

Yes, for a single organization with a few roles and an identity provider your team already administers. The configuration itself is a bounded set of settings, and the Grafana authentication documentation covers the generic OAuth options. The work gets harder when several organizations need different role sets, when group claims are owned by several departments, or when the identity provider is being migrated at the same time. In those cases, the risk is misassigned admin or editor roles, which is hard to spot without a structured test plan. A partner can be useful for the design and test matrix even if your team runs the change.

What needs ongoing attention after Grafana role mapping goes live?

Three things recur. Claim and group changes in the identity provider can silently move users to different roles, so changes need review and a repeat sign-in test. Grafana version upgrades can change authentication behavior, so the mapping should be retested after each upgrade you plan, and the release cadence is covered in the Grafana upgrade guidance. Client secret rotation for the OAuth application must be scheduled and tested before the old secret expires. Assign an owner for each of these, and keep the role model documented so new administrators can read it.

What should a written quote for Grafana role mapping include?

Ask for the scope in terms you can check: the number of Grafana instances and organizations, the identity provider and application registrations involved, and the roles and org mappings to be delivered. Ask for each deliverable, such as the role model document, the configuration, the test matrix and the runbook. Ask which items are one-time and which recur, such as retesting after upgrades or support retainers. Ask what the customer must provide, the timeline with its dependencies, and the acceptance criteria that close the work. Finally, ask how changes to scope are priced and approved, since fixed-scope agreements are typically agreed in writing before work starts.

How DeployOpen scopes and delivers Grafana role mapping

DeployOpen plans and implements the mapping between your identity provider's claims and Grafana roles, organizations and server admin rights as part of a fixed-scope engagement. The work runs inside your own infrastructure, with each claim rule written down, tested against real test accounts and handed over with the configuration and the steps your team needs to maintain it.

How we scope

Written scope lists the identity provider, the claims available for role and organization decisions, and the Grafana edition in use.
Scope records which users may reach which organizations and which accounts, if any, should receive server admin rights.
Scope names the email claim source and the sign-in behavior when a user's claims are missing or unexpected.

How we build

JMESPath expressions for role_attribute_path are written and checked against sample token payloads before they reach a live Grafana.
org_mapping entries are defined for each target organization, with the default role and strict role handling agreed in advance.
Configuration is stored as code so changes to claim rules go through version control and review in your environment.

How we hand over

Test cases cover each role, each organization mapping, denied sign-ins and a user who lacks the email claim.
Documentation describes every claim rule, the group or attribute values behind it and who approves changes to them.
Your administrators receive a runbook for adding a new organization, changing a role rule and reviewing server admin grants.

How we support

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
Ongoing support, Grafana upgrades and continuous testing are available as retainers, so claim rules are re-tested after each upgrade.
Ask any provider to confirm how they test claim rules after identity provider changes and who owns the mapping after handover.

Grafana role and organization mapping with generic OAuth