How Grafana SSO with Okta works and when to use it
Grafana's Okta OAuth provider is available in all editions, and role and organization mapping depends on group claims that Okta includes when a user signs in. If your security or platform team runs self-hosted Grafana and must sign users in through Okta, this is the integration to evaluate first. The Grafana authentication docs list Okta as a supported method for every edition, alongside LDAP, generic OAuth, Entra ID, GitHub, GitLab, Google OAuth, auth proxy and JWT. Before you build anything, confirm which Okta groups should map to Grafana roles, because those groups determine who can reach the instance and with what permissions.
The open-source integration covers four areas: sign-in through Okta, role mapping from group claims, an allowed-groups list that limits which Okta users may log in, and logout handling for sessions that started in Okta. Those areas should drive your design decisions. Allowed groups is the control that matters most for access, because a user outside the permitted groups is refused at login instead of receiving a default role. Plan the claim format, the group names and the role assignments together, and confirm the exact settings in the Okta section of the authentication docs for the Grafana version you intend to run.
What the open-source edition does not cover is equally important. SAML, team sync, active sync and SCIM provisioning are available only in Grafana Enterprise and Grafana Cloud. Under the open-source edition, Okta groups cannot be pushed into Grafana teams, and joiners and leavers cannot be provisioned or deprovisioned automatically from Okta. If your access model depends on team membership or automated lifecycle handling, decide that before committing to the design, and confirm with Grafana Labs what your target version and license include. If several teams will share this instance, also confirm that its configuration database is MySQL or PostgreSQL, since SQLite does not scale for production.
What the team needs before configuring Okta with Grafana
Five things need to be settled before anyone edits the Grafana configuration: the version and edition, the database, the public address Okta will redirect to, the Okta tenant rights, and an admin account to make the change. Each one is a dependency for the next, so a gap in any card stalls the whole configuration.
Supported version and edition
Pick a Grafana release that is still inside its support window before you build the Okta integration, so you are not configuring a version that will be retired during rollout. The upgrade guidance says minor releases are supported for 9 months and the last minor of a major version for 15 months. Check the current release list on GitHub and the upgrade docs, then decide whether you need Enterprise. Okta OAuth works in open source, but group-based team sync and SCIM provisioning do not.
Production database
Grafana stores its configuration in SQLite by default, but the installation docs say SQLite does not scale for production. Provision MySQL 8.0 or later or PostgreSQL 12 or later before enabling SSO, because user records, sessions and the role mappings you create all live there. Changing the database after users sign in means migrating existing data, so decide it now. Confirm the exact driver settings against the installation docs for your chosen engine.
Public HTTPS root URL
Okta redirects the browser back to Grafana after sign-in, so Grafana needs a stable public HTTPS address that users and Okta can both reach. The root URL you set in the server configuration must match the redirect URI registered in the Okta application exactly, including scheme, host, port and path. A mismatch is the most common cause of a failed first login. Confirm the redirect URI format in the Okta admin console and in the current Grafana authentication docs before you register it.
Okta administrator rights
Someone needs an Okta role that can create an OIDC web application, set its sign-in redirect and assign groups to it. Without group assignment, the group claim Grafana reads for role and organization mapping will be empty, and users will sign in with no useful access. Confirm with your Okta administrators which group names will be used for Grafana roles, and whether an authorization server and the groups claim are available on the tenant plan you run.
Grafana admin account and change control
Editing the authentication settings requires a Grafana server administrator account, and the first mistake in those settings can lock out every user, including administrators who rely on local login. Keep a local admin account working through the change, record the current configuration file, and plan a rollback window. Decide who approves the change and where the configuration is stored, so the Okta settings can be reviewed and reproduced later.
Configuring Okta OAuth in Grafana step by step
This sequence connects a self-hosted Grafana instance to an Okta application, sends group membership in the ID token, maps groups to Grafana roles, and limits sign-in and server administration to named groups. Each step ends with a check you can run before moving on.
Create the Okta application integration
An Okta administrator creates an OIDC web application for Grafana in the Okta admin console and sets the sign-in redirect URI to your Grafana address with the Okta callback path that your Grafana version documents. Record the client ID and client secret and store the secret in your secrets manager, not in a shared document or ticket. Confirm the exact callback path and assignment options against the Grafana authentication documentation for your version. The step is done when the application appears in Okta with its credentials recorded and the redirect URI matches your Grafana URL exactly.
Add a groups claim to the ID token
In the Okta authorization server that Grafana will use, add a custom claim named groups to the ID token and set it to include only the groups that Grafana needs, for example groups whose names share a Grafana prefix. Avoid sending every group in the directory, because large or unrelated group lists increase token size and widen what the claim exposes. Make sure the scopes Grafana requests include groups access in the authorization server policy. The step is done when the token preview in Okta shows a groups claim containing only the intended Grafana groups for a test user.
Configure the Okta provider in Grafana
A Grafana administrator enables the Okta provider in the authentication settings and enters the client ID and client secret from step one. Set the authorization, token and user information URLs to the endpoints of the Okta authorization server, using the configuration keys shown in the authentication documentation for your version (the Okta section is typically named
[auth.okta]). Keep the client secret in an environment variable or secret store rather than in a plain configuration file, and restart Grafana to load the change. The step is done when the login page shows an Okta sign-in option and the server log reports no configuration errors at startup.Map Okta groups to Grafana roles
Set the role attribute path to a JMESPath expression that reads the groups claim and returns Admin, Editor or Viewer for each user. An illustrative expression might return Editor when the groups array contains a dashboard-editors group, and Viewer otherwise, but write the expression against your own group names and check its syntax in the version of Grafana you run. Decide now whether users with no matching group should be denied or assigned Viewer, because that choice depends on how strict role handling is configured. The step is done when a test user in the editors group shows the Editor role on their profile and a user outside it shows Viewer.
Restrict sign-in with allowed groups
Set the allowed groups option for the Okta provider to the Okta groups whose members may sign in to Grafana, using the key named in the authentication documentation for your version. Users who are not members of any allowed group should not be able to complete sign-in, even if they hold a valid Okta account. Note whether your version applies the restriction to the whole provider or only to the role mapping, and test both cases. The step is done when a user in an allowed group signs in successfully and a user outside every allowed group receives a denied login with no account created.
Test sign-in with a non-admin account
Sign out, then sign in as a standard user who belongs to an allowed group but not to any administrator group. Check the user profile for the expected organization and role, and confirm that the Administration menu and server-wide settings are not visible. Try one action that requires Editor rights and one that requires Admin rights to confirm the mapping behaves as designed. The step is done when the non-admin account reaches its dashboards and the restricted actions are refused. Keep a record of the test accounts and results for your change file.
Limit the server admin path to a named group
Confirm that server administrator rights are granted only through the one Okta group you have named for that purpose, and that the mapping for that group is the only route to server admin. Review the server admin list in Grafana and remove any account that was granted rights before the Okta mapping was in place. Keep the administrator group small and documented, and check whether your edition and version support the server admin mapping through the provider settings described in the authentication documentation. The step is done when a member of the named group signs in as server admin, a member of any other group does not, and the server admin list matches the approved group membership.
Which Okta claims map to Grafana identity, roles and organizations
This table pairs each Grafana identity, role and organization field with the Okta claim or group that feeds it. Read it as a checklist for the authorization server and the Grafana Okta settings, and confirm each claim name before go-live. The main takeaway is that role, organization and server admin decisions all depend on claims you configure in Okta, so they need to be designed together.
| Grafana field | Okta source | Purpose | What to confirm |
|---|---|---|---|
| User email | Email claim on the ID token or userinfo response, usually from the default user profile | Grafana uses the email to create and match the user record, so it must be present for every user who signs in | That the claim is populated for all users in the Okta app and that Grafana's expected email claim name matches the authorization server |
| Name or login | Name or preferred username claim from the Okta profile | Sets the display name and login shown in Grafana and in audit views | Which claim name your Grafana version reads, and whether a missing value falls back to the email |
| Groups claim for role mapping | A groups claim added to the authorization server with a filter that returns only Grafana-related groups | Carries group membership into the token so Grafana can decide the user's role | The exact claim name, the filter expression, and that group names in the token match the Okta group names you expect |
| Role attribute expression | The groups claim or other token attributes, evaluated by Grafana against the token contents | Maps group membership to Viewer, Editor or Admin roles | The expression syntax in the current authentication docs and that each Okta group produces the role you intend |
| Organization assignment (multi-org) | A dedicated claim or group naming the target Grafana organization for each user | Places users in the correct organization when one Grafana instance serves several teams | How org mapping is written for your version, and what happens to users who match no organization entry |
| Server admin assignment | A named Okta group, restricted to a small set of administrators, used in the role expression | Grants instance-wide administration, which is the highest privilege in Grafana | That only the named group can produce the server admin role and that group membership changes in Okta are reviewed regularly |
Which Okta features need Grafana Enterprise
Grafana open source supports Okta through its generic OAuth integration, as the Grafana authentication docs list for all editions. Users sign in with their Okta credentials, and Grafana can read group claims from the token to assign organization roles and restrict sign-in to approved groups. Users, teams and team membership remain managed inside Grafana, so the team still administers those objects, even though identity comes from Okta.
- Sign-in: Okta authenticates the user, and Grafana creates or matches the local account from the returned claims.
- Role mapping: Group claims map to Grafana roles, which the platform team defines in the OAuth configuration.
- Allowed groups: Sign-in can be limited to specific Okta groups, so users outside them never reach the instance.
- Teams: Team membership is not synchronized from Okta in this edition, so teams are maintained by hand or by provisioning scripts.
- Deprovisioning: Removing a user in Okta does not remove the Grafana account automatically.
Before relying on this model, confirm the exact claim names and group behavior in your Okta tenant and in the Grafana version you run.
Grafana Enterprise is a commercial edition offered as a non-AGPL option, according to the Grafana Labs licensing page. The authentication docs list SAML, team sync, active sync and SCIM provisioning as available only in Enterprise and Grafana Cloud. These features move user and team administration closer to the identity provider, which matters most when access must be removed promptly and teams mirror Okta groups.
- SAML: An alternative sign-in method to OAuth for organizations that standardize on SAML connections.
- Team sync: Maps identity provider groups to Grafana teams so membership follows Okta.
- Active sync: Keeps users and their attributes updated from the identity provider after first sign-in.
- SCIM provisioning: Lets Okta create, update and deactivate Grafana users automatically.
- Licensing: Your contract defines the license terms, support and any feature entitlements, so ask for them in writing.
Confirm with Grafana Labs which features your license includes, whether they apply to your Grafana version, and how they interact with your existing OAuth setup.
Grafana Cloud provides the same Enterprise-only identity features, as the authentication docs note, but they are billed through Grafana Cloud plans rather than a self-hosted license. The Grafana pricing page describes a free tier, a Pro tier starting with a 19 US dollar monthly platform fee plus usage, and an Enterprise tier with a minimum commitment of 25,000 US dollars per year. Choosing Cloud changes where the instance runs, so the self-hosting plan in this topic no longer applies.
- Cost model: Platform fees and usage recur monthly or annually, which differs from a one-time implementation effort.
- Hosting: Grafana Labs operates the instance, so network placement, backups and upgrades follow its service terms.
- Data location: Confirm where telemetry and configuration are stored if residency rules apply to your data.
- Feature parity: Confirm which Okta and SCIM features are included in the tier you buy, since plan names change.
- Exit path: Ask how dashboards, data sources and users would move if you later return to self-hosting.
Request a written quote from Grafana Labs that lists the included identity features, the plan tier and the terms that apply to your region.
The choice depends on who should manage users and teams, how quickly access must change when someone leaves, and what licensing and hosting you can accept. A small team with a stable group structure may accept manual team management in open source. A regulated organization that needs deprovisioning tied to Okta may need SCIM and team sync, which the docs place in Enterprise or Cloud. The decision should be made before the Okta application is built, because switching later changes how identities are linked.
- Ownership: Decide whether Okta or Grafana administrators own team membership.
- Offboarding: Define the maximum acceptable delay between removing access in Okta and in Grafana.
- Group design: Map Okta groups to roles and teams before configuring claims.
- Migration: Plan how existing local accounts and dashboard permissions move when identities change.
- Verification: Test sign-in, role changes and removal with non-production accounts.
Ask Grafana Labs to confirm feature availability for your exact license, version and hosting model before you commit.
Security settings that protect the Okta login path
Okta sign-in only protects Grafana if the settings around it are tight. The four to six controls below cover who can sign in, what they can administer, how the browser session is protected, and how the client secret and sessions are handled over time. Review them together, because a loose allowed-groups list or a broad admin mapping undoes the work of the identity provider.
Restrict sign-in with allowed groups
Set the Okta OAuth allowed groups option so that only members of named Okta groups can complete a Grafana login. Without it, any user who can authenticate to your Okta org may be able to reach the Grafana login flow, even if they hold no dashboard responsibility. Check the group names against the Okta admin console, confirm the groups are included in the ID token or userinfo response, and test with one user from an excluded group to confirm the denial. Treat the allowed group list as a access control that needs an owner and a review cycle.
Limit server admin to a narrow group
Map only a small, named Okta group to the Grafana server admin role, and keep it separate from the group that grants organization admin rights. Server admin can change global settings, manage every organization and see configuration that affects all users. Check that the role mapping expression does not default to elevated roles for unmatched users, and confirm that the admin group membership in Okta is reviewed on the same schedule as privileged accounts elsewhere in your environment.
Enable secure and SameSite cookies
The Grafana hardening guidance recommends secure and SameSite cookie settings so session cookies are sent only over HTTPS and are restricted on cross-site requests. For the Okta login path, this means the TLS-terminating proxy and the Grafana server must agree on the public root URL, and the cookie attributes must survive the proxy. Verify the flags in the browser developer tools after login, and retest after any change to the reverse proxy or load balancer.
Apply a Content Security Policy
A Content Security Policy limits which scripts, styles and frames the browser will run for the Grafana UI, which reduces the impact of injected content on the login page and in dashboards. Start from the hardening guidance, enable the policy in report-only mode where your environment allows it, and review violations for any plugins or embedded panels your teams use. Confirm that the Okta redirect and callback flow still completes after the policy is enforced.
Require a strict DNS rebinding check
Set the root URL to the exact public address users type, and enable the domain verification control so Grafana rejects requests whose host header does not match. This matters for the Okta callback, because the redirect URI registered in the Okta app must match the root URL Grafana generates. A mismatch causes failed logins or, worse, accepts requests addressed to unexpected hostnames. Test from an internal and an external network path after changes to DNS or the proxy.
Protect the client secret and review sessions
Keep the Okta client secret out of plain configuration files in source control. Store it in a secrets manager or an environment variable injected at startup, restrict read access on the Grafana configuration file, and plan rotation in Okta with a tested cutover. Also review session lifetime and logout behavior: confirm how long Grafana sessions remain valid, and test what happens to an open session after a user is disabled in Okta. Single logout depends on how Okta and Grafana are configured and tested together, so confirm current behavior in the Grafana docs before you rely on it.
Why Okta logins to Grafana fail and how to fix them
This table pairs each common Okta sign-in failure with its likely cause and fix for self-hosted Grafana. Start with the symptom you see, then check the cause in the server logs and token claims before changing configuration.
| Symptom | Likely cause | Fix |
|---|---|---|
| Redirect URI mismatch error at Okta sign-in | The sign-in callback URL registered in the Okta app does not match the Grafana root URL plus the OAuth callback path. | Register the exact callback URL in the Okta app, then align root_url in the Grafana server settings with the same scheme, host and port. |
| Token exchange fails with invalid client error | The client secret in grafana.ini is wrong, expired, or was rotated in Okta without updating Grafana. | Generate a new client secret in Okta, update the Grafana OAuth client secret, restart Grafana and confirm the change in server logs. |
| Users sign in but land with the Viewer role or no access | The groups claim is missing, named differently from the configured role expression, or the user is not in a group the mapping checks. | Compare the ID token claims for that user with the role_attribute_path expression, correct the claim name or group values, and confirm the Okta app assigns the groups. |
| Users see an access denied message after Okta authenticates them | The allowed_groups setting lists groups the user does not belong to, or the Okta group claim is not included in the token. | Confirm the user is in an allowed group in Okta, check the groups filter on the Okta authorization server, and add the group claim to the token. |
| Sign-in fails with no email address found | Grafana requires an email claim, and the Okta app or authorization server does not release it to the token. | Add the email claim to the Okta authorization server scopes and confirm the user profile holds a value for it. |
| Redirects loop to an error page or the IdP login repeats | The root URL, reverse proxy headers or external host do not match the address users type, so Grafana rejects the callback. | Set root_url to the public address, forward the original host and protocol headers from the proxy, and test from the same URL users use. |
| User is stuck in a login loop after a cookie change | Setting cookie_samesite or cookie_secure to a value that browsers reject over the current HTTP or HTTPS setup. | Set secure cookies only when the site runs over HTTPS, choose a SameSite value that matches your redirect flow, then clear cookies for the Grafana host and retest. |
| Logins work on one node but fail or drop sessions behind a load balancer | The database is SQLite, which does not support multiple Grafana nodes sharing state, so session and configuration state is not shared. | Move the database to MySQL 8.0 or later or PostgreSQL 12 or later before adding nodes, then retest sign-in through the load balancer. |
Questions buyers ask before hiring help with Grafana and Okta
How much effort does an Okta setup for Grafana take, and what drives it?
The OAuth connection itself is usually the smallest part of the work. The larger drivers are the group design in Okta, the number of organizations and roles that must be mapped, which features need Grafana Enterprise, and how many user populations must be tested before cutover. Each mapping rule needs a test account in every group it affects. Ask for a quote built from a written scope that lists the group inventory, the organization and role matrix, the edition decision, the test populations and the change window. The more of these inputs you can state up front, the more precise the quote will be.
Can our internal team set up Grafana with Okta without a partner?
Yes, a team with Okta administration rights and Grafana administration skills can often complete the basic setup using the Grafana authentication documentation. The common failure points are in the claim contract: the group names Okta sends must match the role and organization mappings exactly, and the email claim must be present for logins to work. Internal teams also need to test failure cases, such as users outside the allowed groups, users in several groups and users who leave the company. A partner is most useful when the group design, the organization model or the Enterprise decision is still open, or when the team has no time for a formal test plan and rollback.
What does the Okta and Grafana work need from our side?
Plan for five inputs. You need an Okta administrator who can create the application and assign groups, a Grafana administrator who can change server settings and restart the service, a named owner who approves each role mapping, a test plan with accounts that represent every user population, and agreed change windows for cutover. You also need access to the configuration files or the deployment pipeline, because settings may be managed by provisioning or infrastructure code. Without these inputs, the schedule usually slips at the first approval. Ask the provider to list each dependency and the party responsible for it in the written scope.
Do SCIM and team sync require Grafana Enterprise?
Yes. According to the Grafana authentication docs, SAML, team sync, active sync and SCIM provisioning are available only in Grafana Enterprise and Grafana Cloud. Generic OAuth sign-in with Okta is available in every edition. This changes the budget in two ways. The license is a recurring cost on top of the implementation work, and the Enterprise features need their own design, such as deciding whether Okta groups should drive team membership or whether teams stay managed by hand. Ask for quotes that separate the open-source implementation from Enterprise licensing, and confirm license terms and pricing directly with Grafana Labs, because DeployOpen does not set license prices.
Does single logout work between Okta and Grafana?
Confirm this against the Grafana authentication documentation for your exact version before you rely on it. Signing in through OAuth creates a Grafana session, and whether ending the Okta session also ends that Grafana session depends on the flow and the settings you choose. Plan for it explicitly. Test what happens when an employee is deactivated in Okta, when a session is revoked, and when a user signs out on a shared workstation. Review Grafana's session lifetime settings, and decide whether administrator accounts need stricter re-authentication. Ask the implementer for written logout test results that show the browser state and the Okta session state at each step.
How does our Grafana deployment affect the timing of Okta work?
A single Grafana node is quicker to change, but the Grafana installation docs say SQLite does not scale for production, so a production deployment needs MySQL 8.0 or later or PostgreSQL 12 or later. High availability uses two or more active-active Grafana servers behind a load balancer sharing that database, with database-backed auth tokens so users can reach any node. Those topologies add testing. Sign-in must work on every node, load balancer behavior must be validated, and alerting needs additional configuration to avoid duplicate notifications. Grafana Live also has limitations in high availability. Ask for a quote that states the topology, the database version and whether any database migration is in scope.
What should a quote for Okta and Grafana work include?
Ask for a written scope that lists the Grafana topology and edition, the Okta objects to be created (application, groups, claims and assignments), the role and organization mapping table, the allowed-group rules, logout testing, test populations, cutover and rollback steps, and handover documentation. Separate one-time implementation from recurring costs, such as Grafana upgrades, license renewals and any support retainer, since DeployOpen offers ongoing support and upgrades as retainers. Ask what is excluded, such as Okta and Grafana licensing, which you buy from those vendors. Quotes follow from the written scope, so request every assumption in writing and review it before work starts.
How DeployOpen scopes and delivers Grafana SSO with Okta
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, so Grafana sign-in with Okta is scoped and built in your cloud account, data center or restricted network. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- We confirm your Grafana edition, because SAML, team sync, active sync and SCIM depend on Grafana Enterprise or Grafana Cloud.
- We record which Okta group claims map to Grafana roles and organizations, and which groups are allowed to sign in.
- We agree in writing whether single logout, SCIM provisioning and team sync are in scope, and who owns each Okta and Grafana setting.
How we build
- We configure the Okta OAuth application, redirect URIs and claim settings in a staging Grafana before touching production.
- We set role and organization mapping from group claims, then test each mapped role with named test accounts from every group.
- We store client secrets and configuration as provisioned or managed settings, and verify the sign-in and logout path end to end.
How we hand over
- You receive a written configuration record covering Okta app settings, Grafana auth settings, group-to-role mappings and the tests run.
- We document the runbook for adding users to groups, rotating the client secret and recovering from a failed sign-in.
- We walk your identity and platform teams through the configuration and the edition-specific limits that remain after handover.
How we support
- Ongoing support, upgrades and re-testing after Grafana releases are available as a retainer.
- We can review the Okta configuration again when group structures, allowed groups or Grafana editions change.
- Scope changes, such as adding SCIM or team sync later, are quoted and agreed in writing before work starts.
