Configure authentication on Grafana Labs

Configure basic authentication

Fri, 03 Apr 2026 19:43:06 +0000

Configure basic authentication

Grafana provides a basic authentication system with password authentication enabled by default. This document details configuration options to manage and enhance basic authentication.

Disable basic authentication

To disable basic authentication, use the following configuration:

[auth.basic]
enabled = false

Password policy

By default, Grafana’s password policy requires a minimum of four characters for basic auth users. For a stronger password policy, enable the password_policy configuration option.

With the password_policy option enabled, new and updated passwords must meet the following criteria:

At least 12 characters
At least one uppercase letter
At least one lowercase letter
At least one number
At least one special character

[auth.basic]
password_policy = true

Note
Existing passwords that do not comply with the new password policy will not be affected until the user updates their password.

To hide the Grafana login form, use the following configuration setting:

[auth]
disable_login_form = true

This can be helpful in setups where authentication is handled entirely through external mechanisms or single sign-on (SSO).

Configure passwordless authentication with magic links

Fri, 03 Apr 2026 19:43:06 +0000

Configure passwordless authentication with magic links

Passwordless authentication lets Grafana users authenticate with a magic link or one-time password (OTP) sent via email.

Enable passwordless authentication

Note
Passwordless authentication is an experimental feature. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided. Enable the passwordlessMagicLinkAuthentication feature toggle in Grafana to use this feature.

To enable passwordless authentication, use the following configuration:

[auth.passwordless]
enabled = true

Code expiration

By default, the one-time password (OTP) sent to a user’s email is valid for 20 minutes. Use the code_expiration option to change the duration that the OTP is valid.

[auth.passwordless]
enabled = true
code_expiration = 20m

Enable SMTP server

The SMTP server must be enabled so that Grafana can send emails. The following configuration enables the SMTP server. For more information on configuring the SMTP server, refer to SMTP.

[smtp]
enabled = true

Configure anonymous access

Fri, 03 Apr 2026 19:43:06 +0000

Anonymous authentication

You can make Grafana accessible without any login required by enabling anonymous access in the configuration file.

Note
Anonymous users are charged as active users in Grafana Enterprise

Before you begin

To see the devices, you need:

Permissions users:read which is normally only granted to server admins, that allow you to read users and devices tab.

Anonymous devices

The anonymous devices feature enhances the management and monitoring of anonymous access within your Grafana instance. This feature is part of ongoing efforts to provide more control and transparency over anonymous usage.

Users can now view anonymous usage statistics, including the count of devices and users over the last 30 days.

Go to Administration -> Users to access the anonymous devices tab.
A new stat for the usage stats page -> Usage & Stats page shows the active anonymous devices last 30 days.

The number of anonymous devices is not limited by default. The configuration option device_limit allows you to enforce a limit on the number of anonymous devices. This enables you to have greater control over the usage within your Grafana instance and keep the usage within the limits of your environment. Once the limit is reached, any new devices that try to access Grafana will be denied access.

Configuration

Example:

[auth.anonymous]
enabled = true

# Organization name that should be used for unauthenticated users
org_name = Main Org.

# Role for unauthenticated users, other valid values are `Editor` and `Admin`
org_role = Viewer

# Hide the Grafana version text from the footer and help tooltip for unauthenticated users (default: false)
hide_version = true

# Setting this limits the number of anonymous devices in your instance. Any new anonymous devices added after the limit has been reached will be denied access.
device_limit =

If you change your organization name in the Grafana UI this setting needs to be updated to match the new name.

Licensing for anonymous access

Grafana Enterprise (self-managed) licenses anonymous access as active users.

Anonymous access lets people use Grafana without login credentials. It was an early way to share dashboards, but Public dashboards gives you a more secure way to share dashboards.

How anonymous usage is counted

Grafana estimates anonymous active users from anonymous devices:

Counting rule: Grafana counts 1 anonymous user for every 3 anonymous devices detected.

Configure LDAP authentication

Fri, 03 Apr 2026 19:43:06 +0000

Configure LDAP authentication

The LDAP integration in Grafana allows your Grafana users to login with their LDAP credentials. You can also specify mappings between LDAP group memberships and Grafana Organization user roles.

Note
Enhanced LDAP authentication is available in Grafana Cloud and in Grafana Enterprise.

Refer to Role-based access control to understand how you can control access with role-based permissions.

Supported LDAP Servers

Grafana uses a third-party LDAP library under the hood that supports basic LDAP v3 functionality. This means that you should be able to configure LDAP integration using any compliant LDAPv3 server, for example OpenLDAP or Active Directory among others.

Enable LDAP

In order to use LDAP integration you’ll first need to enable LDAP in the main config file as well as specify the path to the LDAP specific configuration file (default: /etc/grafana/ldap.toml).

After enabling LDAP, the default behavior is for Grafana users to be created automatically upon successful LDAP authentication. If you prefer for only existing Grafana users to be able to sign in, you can change allow_sign_up to false in the [auth.ldap] section.

[auth.ldap]
# Set to `true` to enable LDAP integration (default: `false`)
enabled = true

# Path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`)
config_file = /etc/grafana/ldap.toml

# Allow sign-up should be `true` (default) to allow Grafana to create users on successful LDAP authentication.
# If set to `false` only already existing Grafana users will be able to login.
allow_sign_up = true

Disable org role synchronization

If you use LDAP to authenticate users but don’t use role mapping, and prefer to manually assign organizations and roles, you can use the skip_org_role_sync configuration option.

[auth.ldap]
# Set to `true` to enable LDAP integration (default: `false`)
enabled = true

# Path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`)
config_file = /etc/grafana/ldap.toml

# Allow sign-up should be `true` (default) to allow Grafana to create users on successful LDAP authentication.
# If set to `false` only already existing Grafana users will be able to login.
allow_sign_up = true

# Prevent synchronizing ldap users organization roles
skip_org_role_sync = true

Grafana LDAP Configuration

Depending on which LDAP server you’re using and how that’s configured, your Grafana LDAP configuration may vary. See configuration examples for more information.

LDAP specific configuration file (ldap.toml) example:

[[servers]]
# Ldap server host (specify multiple hosts space separated)
host = "ldap.my_secure_remote_server.org"
# Default port is 389 or 636 if use_ssl = true
port = 636
# Set to true if LDAP server should use an encrypted TLS connection (either with STARTTLS or LDAPS)
use_ssl = true
# If set to true, use LDAP with STARTTLS instead of LDAPS
start_tls = false
# The value of an accepted TLS cipher. By default, this value is empty. Example value: ["TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"])
# For a complete list of supported ciphers and TLS versions, refer to: https://go.dev/src/crypto/tls/cipher_suites.go
# Starting with Grafana v11.0 only ciphers with ECDHE support are accepted for TLS 1.2 connections.
tls_ciphers = []
# This is the minimum TLS version allowed. By default, this value is empty. Accepted values are: TLS1.1 (only for Grafana v10.4 or earlier), TLS1.2, TLS1.3.
min_tls_version = ""
# set to true if you want to skip SSL cert validation
ssl_skip_verify = false
# set to the path to your root CA certificate or leave unset to use system defaults
# root_ca_cert = "/path/to/certificate.crt"
# Authentication against LDAP servers requiring client certificates
# client_cert = "/path/to/client.crt"
# client_key = "/path/to/client.key"

# Search user bind dn
bind_dn = "cn=admin,dc=grafana,dc=org"
# Search user bind password
# If the password contains # or ; you have to wrap it with triple quotes. Ex """#password;"""
bind_password = "grafana"
# We recommend using variable expansion for the bind_password, for more info https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#variable-expansion
# bind_password = '$__env{LDAP_BIND_PASSWORD}'

# Timeout in seconds. Applies to each host specified in the 'host' entry (space separated).
timeout = 10

# User search filter, for example "(cn=%s)" or "(sAMAccountName=%s)" or "(uid=%s)"
# Allow login from email or username, example "(|(sAMAccountName=%s)(userPrincipalName=%s))"
search_filter = "(cn=%s)"

# An array of base dns to search through
search_base_dns = ["dc=grafana,dc=org"]

# group_search_filter = "(&(objectClass=posixGroup)(memberUid=%s))"
# group_search_filter_user_attribute = "distinguishedName"
# group_search_base_dns = ["ou=groups,dc=grafana,dc=org"]

# Specify names of the LDAP attributes your LDAP uses
[servers.attributes]
member_of = "memberOf"
email =  "email"

Note
Whenever you modify the ldap.toml file, you must restart Grafana in order for the change(s) to take effect.

Using the Grafana user interface

You can configure LDAP using the Grafana user interface by navigating to Administration > Authentication > LDAP. Please refer to the LDAP user interface documentation for more information.

Using environment variables

You can interpolate variables in the TOML configuration from environment variables. For instance, you could externalize your bind_password that way:

bind_password = "${LDAP_ADMIN_PASSWORD}"

Bind and bind password

By default the configuration expects you to specify a bind DN and bind password. This should be a read only user that can perform LDAP searches. When the user DN is found a second bind is performed with the user provided username and password (in the normal Grafana login form).

bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"

Single bind example

If you can provide a single bind expression that matches all possible users, you can skip the second bind and bind against the user DN directly. This allows you to not specify a bind_password in the configuration file.

bind_dn = "cn=%s,o=users,dc=grafana,dc=org"

In this case you skip providing a bind_password and instead provide a bind_dn value with a %s somewhere. This will be replaced with the username entered in on the Grafana login page. The search filter and search bases settings are still needed to perform the LDAP search to retrieve the other LDAP information (like LDAP groups and email).

POSIX schema

If your LDAP server does not support the memberOf attribute, add the following options:

## Group search filter, to retrieve the groups of which the user is a member (only set if memberOf attribute is not available)
group_search_filter = "(&(objectClass=posixGroup)(memberUid=%s))"
## An array of the base DNs to search through for groups. Typically uses ou=groups
group_search_base_dns = ["ou=groups,dc=grafana,dc=org"]
## the %s in the search filter will be replaced with the attribute defined below
group_search_filter_user_attribute = "uid"

Group mappings

In [[servers.group_mappings]] you can map an LDAP group to a Grafana organization and role. These will be synced every time the user logs in, with LDAP being the authoritative source.

The first group mapping that an LDAP user is matched to will be used for the sync. If you have LDAP users that fit multiple mappings, the topmost mapping in the TOML configuration will be used.

LDAP specific configuration file (ldap.toml) example:

[[servers]]
# other settings omitted for clarity

[[servers.group_mappings]]
group_dn = "cn=superadmins,dc=grafana,dc=org"
org_role = "Admin"
grafana_admin = true

[[servers.group_mappings]]
group_dn = "cn=admins,dc=grafana,dc=org"
org_role = "Admin"

[[servers.group_mappings]]
group_dn = "cn=users,dc=grafana,dc=org"
org_role = "Editor"

[[servers.group_mappings]]
group_dn = "*"
org_role = "Viewer"

Setting	Required	Description	Default
`group_dn`	Yes	LDAP distinguished name (DN) of LDAP group. If you want to match all (or no LDAP groups) then you can use wildcard (`"*"`)
`org_role`	Yes	Assign users of `group_dn` the organization role `Admin`, `Editor`, or `Viewer`. The organization role name is case sensitive.
`org_id`	No	The Grafana organization database id. Setting this allows for multiple group_dn’s to be assigned to the same `org_role` provided the `org_id` differs	`1` (default org id)
`grafana_admin`	No	When `true` makes user of `group_dn` Grafana server admin. A Grafana server admin has admin access over all organizations and users.	`false`

Note
Commenting out a group mapping requires also commenting out the header of said group or it will fail validation as an empty mapping.

Example:

[[servers]]
# other settings omitted for clarity

[[servers.group_mappings]]
group_dn = "cn=superadmins,dc=grafana,dc=org"
org_role = "Admin"
grafana_admin = true

# [[servers.group_mappings]]
# group_dn = "cn=admins,dc=grafana,dc=org"
# org_role = "Admin"

[[servers.group_mappings]]
group_dn = "cn=users,dc=grafana,dc=org"
org_role = "Editor"

Nested/recursive group membership

Users with nested/recursive group membership must have an LDAP server that supports LDAP_MATCHING_RULE_IN_CHAIN and configure group_search_filter in a way that it returns the groups the submitted username is a member of.

To configure group_search_filter:

You can set group_search_base_dns to specify where the matching groups are defined.
If you do not use group_search_base_dns, then the previously defined search_base_dns is used.

Active Directory example:

Active Directory groups store the Distinguished Names (DNs) of members, so your filter needs to know the DN for the user based only on the submitted username. Multiple DN templates are searched by combining filters with the LDAP OR-operator. Two examples:

group_search_filter = "(member:1.2.840.113556.1.4.1941:=%s)"
group_search_base_dns = ["DC=mycorp,DC=mytld"]
group_search_filter_user_attribute = "dn"

group_search_filter = "(member:1.2.840.113556.1.4.1941:=CN=%s,[user container/OU])"
group_search_filter = "(|(member:1.2.840.113556.1.4.1941:=CN=%s,[user container/OU])(member:1.2.840.113556.1.4.1941:=CN=%s,[another user container/OU]))"
group_search_filter_user_attribute = "cn"

For more information on AD searches refer to Microsoft’s Search Filter Syntax documentation.

For troubleshooting, changing member_of in [servers.attributes] to “dn” will show you more accurate group memberships when debug is enabled.

Configuration examples

The following examples describe different LDAP configuration options.

OpenLDAP

OpenLDAP is an open source directory service.

LDAP specific configuration file (ldap.toml):

[[servers]]
host = "127.0.0.1"
port = 389
use_ssl = false
start_tls = false
ssl_skip_verify = false
bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"
search_filter = "(cn=%s)"
search_base_dns = ["dc=grafana,dc=org"]

[servers.attributes]
member_of = "memberOf"
email =  "email"

# [[servers.group_mappings]] omitted for clarity

Multiple LDAP servers

Grafana does support receiving information from multiple LDAP servers.

LDAP specific configuration file (ldap.toml):

# --- First LDAP Server ---

[[servers]]
host = "10.0.0.1"
port = 389
use_ssl = false
start_tls = false
ssl_skip_verify = false
bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"
search_filter = "(cn=%s)"
search_base_dns = ["ou=users,dc=grafana,dc=org"]

[servers.attributes]
member_of = "memberOf"
email =  "email"

[[servers.group_mappings]]
group_dn = "cn=admins,ou=groups,dc=grafana,dc=org"
org_role = "Admin"
grafana_admin = true

# --- Second LDAP Server ---

[[servers]]
host = "10.0.0.2"
port = 389
use_ssl = false
start_tls = false
ssl_skip_verify = false

bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"
search_filter = "(cn=%s)"
search_base_dns = ["ou=users,dc=grafana,dc=org"]

[servers.attributes]
member_of = "memberOf"
email =  "email"

[[servers.group_mappings]]
group_dn = "cn=editors,ou=groups,dc=grafana,dc=org"
org_role = "Editor"

[[servers.group_mappings]]
group_dn = "*"
org_role = "Viewer"

Active Directory

Active Directory is a directory service which is commonly used in Windows environments.

Assuming the following Active Directory server setup:

IP address: 10.0.0.1
Domain: CORP
DNS name: corp.local

LDAP specific configuration file (ldap.toml):

[[servers]]
host = "10.0.0.1"
port = 3269
use_ssl = true
start_tls = false
ssl_skip_verify = true
bind_dn = "CORP\\%s"
search_filter = "(sAMAccountName=%s)"
search_base_dns = ["dc=corp,dc=local"]

[servers.attributes]
member_of = "memberOf"
email =  "mail"

# [[servers.group_mappings]] omitted for clarity

Port requirements

In the previous example, SSL is enabled and an encrypted port has been configured. If your Active Directory doesn’t support SSL, use enable_ssl = false and port = 389 instead.

Inspect your Active Directory configuration and documentation to find the correct settings. For more information about Active Directory and port requirements, refer to the Microsoft documentation.

Troubleshooting

To troubleshoot and get more log information, enable LDAP debug logging in the grafana.ini or custom.ini file:

[log]
filters = ldap:debug

Configure LDAP authentication using the Grafana user interface

Fri, 03 Apr 2026 19:43:06 +0000

Configure LDAP authentication using the Grafana user interface

This page explains how to configure LDAP authentication in Grafana using the Grafana user interface. For more detailed information about configuring LDAP authentication using the configuration file, refer to LDAP authentication.

Benefits of using the Grafana user interface to configure LDAP authentication include:

No need to edit the configuration file manually.
Quickly test the connection to the LDAP server.
No need to restart Grafana after making changes.

Note
Any configuration changes made through the Grafana user interface (UI) will take precedence over settings specified in the Grafana configuration file or through environment variables. If you modify any configuration settings in the UI, they will override any corresponding settings set via environment variables or defined in the configuration file.

Before you begin

To follow these instructions, you need:

Knowledge of LDAP authentication and how it works.
A Grafana instance v11.3.0 or later.
Permissions settings:read and settings:write with settings:auth.ldap:* scope.
The ssoSettingsLDAP feature toggle enabled.

Steps to configure LDAP authentication

1. Complete mandatory fields

The mandatory fields have an asterisk (*) next to them. Complete the following fields:

Server host: Host name or IP address of the LDAP server.
Search filter: The LDAP search filter finds entries within the directory.
Search base DNS: List of base DNs to search through.

2. Complete optional fields

Complete the optional fields as needed:

Bind DN: Distinguished name (DN) of the user to bind to.
Bind password: Password for the server.

3. Advanced settings

Click the Edit button in the Advanced settings section to configure the following settings:

1. Miscellaneous settings

Complementary settings for LDAP authentication.

Allow sign-up: Allows new users to register upon logging in.
Port: Port number of the LDAP server. The default is 389.
Timeout: Time in seconds to wait for a response from the LDAP server.

2. Attributes

Attributes used to map LDAP user assertion to Grafana user attributes.

Name: Name of the assertion attribute to map to the Grafana user name.
Surname: Name of the assertion attribute to map to the Grafana user surname.
Username: Name of the assertion attribute to map to the Grafana user username.
Member Of: Name of the assertion attribute to map to the Grafana user membership.
Email: Name of the assertion attribute to map to the Grafana user email.

3. Group mapping

Map LDAP groups to Grafana roles.

Skip organization role sync: This option avoids syncing organization roles. It is useful when you want to manage roles manually.
Group search filter: The LDAP search filter finds groups within the directory.
Group search base DNS: List of base DNS to specify the matching groups’ locations.
Group name attribute: Identifies users within group entries.
Manage group mappings:

When managing group mappings, the following fields are available. To add a new group mapping, click the Add group mapping button.
1. Add a group DN mapping: The name of the key used to extract the ID token.
2. Add an organization role mapping: Select the Basic Role mapped to this group.
3. Add the organization ID membership mapping: Map the group to an organization ID.
4. Define Grafana Admin membership: Enable Grafana Admin privileges to the group.

4. Extra security settings

Additional security settings options for LDAP authentication.

Enable SSL: This option will enable SSL to connect to the LDAP server.
Start TLS: Use StartTLS to secure the connection to the LDAP server.
Min TLS version: Choose the minimum TLS version to use. TLS1.2 or TLS1.3
TLS ciphers: List the ciphers to use for the connection. For a complete list of ciphers, refer to the Cipher Go library.
Encryption key and certificate provision specification: This section allows you to specify the key and certificate for the LDAP server. You can provide the key and certificate in two ways: base-64 encoded or path to files.
1. Base-64 encoded certificate: All values used in this section must be base-64 encoded.
  1. Root CA certificate content: List of root CA certificates.
  2. Client certificate content: Client certificate content.
  3. Client key content: Client key content.
2. Path to files: Path in the file system to the key and certificate files
  1. Root CA certificate path: Path to the root CA certificate.
  2. Client certificate path: Path to the client certificate.
  3. Client key path: Path to the client key.

4. Persisting the configuration

Once you have configured the LDAP settings, click Save to persist the configuration.

If you want to delete all the changes made through the UI and revert to the configuration file settings, click the three dots menu icon and click Reset to default values.

Configure enhanced LDAP integration

Fri, 03 Apr 2026 19:43:06 +0000

Configure enhanced LDAP integration

The enhanced LDAP integration adds additional functionality on top of the LDAP integration available in the open source edition of Grafana.

Note
Available in Grafana Enterprise and Grafana Cloud. If you are a Grafana Cloud customer, please open a support ticket in the Cloud Portal to request this feature.

To control user access with role-based permissions, refer to role-based access control.

LDAP group synchronization for teams

With enhanced LDAP integration, you can set up synchronization between LDAP groups and teams. This enables LDAP users that are members of certain LDAP groups to automatically be added or removed as members to certain teams in Grafana.

Grafana keeps track of all synchronized users in teams, and you can see which users have been synchronized from LDAP in the team members list, see LDAP label in screenshot. This mechanism allows Grafana to remove an existing synchronized user from a team when its LDAP group membership changes. This mechanism also allows you to manually add a user as member of a team, and it will not be removed when the user signs in. This gives you flexibility to combine LDAP group memberships and Grafana team memberships.

Learn more about team sync.

Active LDAP synchronization

In the open source version of Grafana, user data from LDAP is synchronized only during the login process when authenticating using LDAP.

With active LDAP synchronization, you can configure Grafana to actively sync users with LDAP servers in the background. Only users that have logged into Grafana at least once are synchronized.

Users with updated role and team membership will need to refresh the page to get access to the new features.

Removed users are automatically logged out and their account disabled. These accounts are displayed in the Server Admin > Users page with a disabled label. Disabled users keep their custom permissions on dashboards, folders, and data sources, so if you add them back in your LDAP database, they have access to the application with the same custom permissions as before.

[auth.ldap]
...

# You can use the Cron syntax or several predefined schedulers -
# @yearly (or @annually) | Run once a year, midnight, Jan. 1st        | 0 0 1 1 *
# @monthly               | Run once a month, midnight, first of month | 0 0 1 * *
# @weekly                | Run once a week, midnight between Sat/Sun  | 0 0 * * 0
# @daily (or @midnight)  | Run once a day, midnight                   | 0 0 * * *
# @hourly                | Run once an hour, beginning of hour        | 0 * * * *
sync_cron = "0 1 * * *" # This is default value (At 1 am every day)
# This cron expression format uses 5 space-separated fields, for example
# sync_cron = "*/10 * * * *"
# This will run the LDAP Synchronization every 10th minute, which is also the minimal interval between the Grafana sync times i.e. you cannot set it for every 9th minute

# You can also disable active LDAP synchronization
active_sync_enabled = true # enabled by default

Single bind configuration (as in the Single bind example) is not supported with active LDAP synchronization because Grafana needs user information to perform LDAP searches.

For the synchronization to work, the servers.search_filter and servers.attributes.username in the ldap.toml configuration file must match. By default, the servers.attributes.username is cn, so if you use another attribute as the search filter, you must also update the username attribute.

For example:

[[servers]]
search_filter = "(sAMAccountName=%s)"

[servers.attributes]
username  = "sAMAccountName"

If the attributes aren’t the same, the users’ sessions will be terminated after each synchronization. That’s because the search will be done using the username’s value, and that value doesn’t exist for the attribute used in the search filter.

Configure SAML authentication in Grafana

Fri, 03 Apr 2026 19:43:06 +0000

SAML authentication in Grafana

Note
Available in Grafana Enterprise and Grafana Cloud.

The SAML authentication integration allows your Grafana users to log in by using an external SAML 2.0 Identity Provider (IdP). To enable this, Grafana becomes a Service Provider (SP) in the authentication flow, interacting with the IdP to exchange user information.

Set up options for SAML authentication in Grafana

You can configure SAML authentication in Grafana with different methods. While the configuration options don’t change, if you want to keep all of Grafana authentication settings in one place, use the Grafana configuration file or the Terraform provider. If you’re a Grafana Cloud user, you don’t have access to Grafana configuration file. Instead, configure SAML through the other methods.

Caution
Configuration in the API or UI takes precedence over the configuration in the Grafana configuration file. SAML settings from the API will override any SAML configuration set in the Grafana configuration file.

For more information on how Grafana determines the order of precedence for its settings, refer to the SSO Settings API.

The available methods are:

Configure SAML using the SSO Settings API
Configure SAML using the SAML user interface
Configure SAML using the Grafana configuration file - not available in Grafana Cloud
Configure SAML using the Grafana Terraform provider

If you’re using Okta or Entra ID as Identity Provider, see the following documentation for configuration:

SAML bindings

Grafana supports the following SAML 2.0 bindings:

From the Service Provider (SP) to the Identity Provider (IdP):
- HTTP-POST binding
- HTTP-Redirect binding
From the Identity Provider (IdP) to the Service Provider (SP):
- HTTP-POST binding

Request initiation

Grafana supports:

SP-initiated requests
IdP-initiated requests

By default, SP-initiated requests are enabled. For instructions on how to enable IdP-initiated logins, see IdP-initiated Single Sign-On (SSO).

Identity provider (IdP) registration

For the SAML integration to work correctly, you need to make your IdP aware that Grafana is the SP.

The integration provides two key endpoints as part of Grafana:

The /saml/metadata endpoint, which contains the SP metadata. You can either download and upload it manually, or you make the IdP request it directly from the endpoint. Some providers name it Identifier or Entity ID.
The /saml/acs endpoint, which is intended to receive the ACS (Assertion Customer Service) callback. Some providers name it SSO URL or Reply URL.

IdP metadata

You also need to define the public part of the IdP for message verification. The SAML IdP metadata XML defines where and how Grafana exchanges user information.

Grafana supports three ways of specifying the IdP metadata.

Without a suffix idp_metadata, Grafana assumes base64-encoded XML file contents.
With the _path suffix, Grafana assumes a path and attempts to read the file from the file system.
With the _url suffix, Grafana assumes a URL and attempts to load the metadata from the given location.

Assertion mapping

During the SAML SSO authentication flow, Grafana receives the ACS callback. The callback contains all the relevant information of the user under authentication embedded in the SAML response. Grafana parses the response to create (or update) the user within its internal database.

For Grafana to map the user information, it looks at the individual attributes within the assertion. You can think of these attributes as Key/Value pairs (although, they contain more information than that).

Grafana provides configuration options that let you modify which keys to look at for these values. The data we need to create the user in Grafana is Name, Login handle, and email.

Integrate with SCIM Provisioning

If you’re also using SCIM provisioning for this Grafana application in Entra ID, it’s crucial to align the user identifiers between SAML and SCIM for seamless operation. The unique identifier that links the SAML user to the SCIM provisioned user is determined by the assertion_attribute_external_uid setting in the Grafana SAML configuration. This assertion_attribute_external_uid should correspond to the externalId used in SCIM provisioning (typically set to the Entra ID user.objectid).

Ensure Consistent Identifier in SAML Assertion:
- The unique identifier from Entra ID (typically user.objectid) that you mapped to the externalId attribute in Grafana in your SCIM provisioning setup must also be sent as a claim in the SAML assertion. For more details on SCIM, refer to the SCIM provisioning documentation.
- In the Entra ID Enterprise Application, under Single sign-on > Attributes & Claims, ensure you add a claim that provides this identifier. For example, you might add a claim named UserID (or similar, like externalId) that sources its value from user.objectid.
Configure Grafana SAML Settings for SCIM:
- In the [auth.saml] section of your Grafana configuration, set assertion_attribute_external_uid to the name of the SAML claim you configured in the previous step (e.g., userUID or the full URI like http://schemas.microsoft.com/identity/claims/objectidentifier if that’s how Entra ID sends it).
- The assertion_attribute_login setting should still be configured to map to the attribute your users will log in with (e.g., userPrincipalName, mail).
Example Grafana Configuration:
ini
```
[auth.saml]
# ... other SAML settings ...
assertion_attribute_login = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier # Or other login attribute
assertion_attribute_external_uid = http://schemas.microsoft.com/identity/claims/objectidentifier # Or your custom claim name for user.objectid
```
Ensure that the value specified in assertion_attribute_external_uid precisely matches the name of the claim as it’s sent in the SAML assertion from Entra ID.
SCIM Linking Identifier and Entra ID:
- By default (if assertion_attribute_external_uid is not set), Grafana uses the userUID attribute from the SAML assertion for SCIM linking.
- Recommended for Entra ID: For SCIM integration with Entra ID, it is necessary to:
  1. Ensure Entra ID sends the user.objectid in a claim.
  2. Either set this claim name in Entra ID to userUID, or, if you want to use a different claim name, set assertion_attribute_external_uid in Grafana to match the claim name you chose in Entra ID.

Advanced configuration

For advanced configuration and troubleshooting, refer to the one of the following pages:

Configure Generic OAuth authentication

Fri, 03 Apr 2026 19:43:06 +0000

Configure Generic OAuth authentication

There are numerous authentication methods available in Grafana to verify user identity. The authentication configuration dictates which users can access Grafana and the methods they can use for logging in. You can also configure Grafana to automatically update users’ roles and team memberships in Grafana based on the information returned by the auth provider integration.

When deciding on an authentication method, it’s important to take into account your current identity and access management system as well as the specific authentication and authorization features you require. For a complete list of the available authentication options and the features they support, refer to Configure authentication.

Grafana provides OAuth2 integrations for the following auth providers:

If your OAuth2 provider is not listed, you can use Generic OAuth authentication.

This topic describes how to configure Generic OAuth authentication using different methods and includes examples of setting up Generic OAuth with specific OAuth2 providers.

Before you begin

To follow this guide:

Ensure you know how to create an OAuth2 application with your OAuth2 provider. Consult the documentation of your OAuth2 provider for more information.
Ensure your identity provider returns OpenID UserInfo compatible information such as the sub claim.
If you are using refresh tokens, ensure you know how to set them up with your OAuth2 provider. Consult the documentation of your OAuth2 provider for more information.

Note
If Users use the same email address in Entra ID that they use with other authentication providers (such as Grafana.com), you need to do additional configuration to ensure that the users are matched correctly. Please refer to the Using the same email address to login with different identity providers documentation for more information.

Configure generic OAuth authentication client using the Grafana UI

As a Grafana Admin, you can configure Generic OAuth client from within Grafana using the Generic OAuth UI. To do this, navigate to Administration > Authentication > Generic OAuth page and fill in the form. If you have a current configuration in the Grafana configuration file then the form will be pre-populated with those values otherwise the form will contain default values.

After you have filled in the form, click Save to save the configuration. If the save was successful, Grafana will apply the new configurations.

If you need to reset changes you made in the UI back to the default values, click Reset. After you have reset the changes, Grafana will apply the configuration from the Grafana configuration file (if there is any configuration) or the default values.

Note
If you run Grafana in high availability mode, configuration changes may not get applied to all Grafana instances immediately. You may need to wait a few minutes for the configuration to propagate to all Grafana instances.

Refer to configuration options for more information.

Configure generic OAuth authentication client using the Terraform provider

resource "grafana_sso_settings" "generic_sso_settings" {
  provider_name = "generic_oauth"
  oauth2_settings {
    name              = "Auth0"
    auth_url          = "https://<domain>/authorize"
    token_url         = "https://<domain>/oauth/token"
    api_url           = "https://<domain>/userinfo"
    client_id         = "<client id>"
    client_secret     = "<client secret>"
    allow_sign_up     = true
    auto_login        = false
    scopes            = "openid profile email offline_access"
    use_pkce          = true
    use_refresh_token = true
  }
}

Refer to Terraform Registry for a complete reference on using the grafana_sso_settings resource.

Configure generic OAuth authentication client using the Grafana configuration file

Ensure that you have access to the Grafana configuration file.

Steps

To integrate your OAuth2 provider with Grafana using our Generic OAuth authentication, follow these steps:

Create an OAuth2 application in your chosen OAuth2 provider.
Set the callback URL for your OAuth2 app to http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/generic_oauth.

Ensure that the callback URL is the complete HTTP address that you use to access Grafana via your browser, but with the appended path of /login/generic_oauth.

For the callback URL to be correct, it might be necessary to set the root_url option in the [server]section of the Grafana configuration file. For example, if you are serving Grafana behind a proxy.

Refer to the following table to update field values located in the [auth.generic_oauth] section of the Grafana configuration file:

Field	Description
`client_id`, `client_secret`	These values must match the client ID and client secret from your OAuth2 app.
`auth_url`	The authorization endpoint of your OAuth2 provider.
`api_url`	The user information endpoint of your OAuth2 provider. Information returned by this endpoint must be compatible with OpenID UserInfo.
`enabled`	Enables Generic OAuth authentication. Set this value to `true`.

Review the list of other Generic OAuth configuration options and complete them, as necessary.

Optional: Configure a refresh token:

a. Extend the scopes field of [auth.generic_oauth] section in Grafana configuration file with refresh token scope used by your OAuth2 provider.

b. Set use_refresh_token to true in [auth.generic_oauth] section in Grafana configuration file.

c. Enable the refresh token on the provider if required.
Configure role mapping.
Optional: Configure team synchronization.
Restart Grafana.

You should now see a Generic OAuth login button on the login page and be able to log in or sign up with your OAuth2 provider.

Grafana can resolve a user’s login from the OAuth2 ID token, user information retrieved from the OAuth2 UserInfo endpoint, or the OAuth2 access token. Grafana looks at these sources in the order listed until it finds a login. If no login is found, then the user’s login is set to user’s email address.

Important
Email is required for successful sign-up and login with Generic OAuth. Even if you map login from another claim (for example sub), Grafana still requires the user to have an email. Ensure your provider returns an email claim or configure email_attribute_path so Grafana can resolve it. Including the email scope is strongly recommended (for OIDC providers use openid profile email).

Refer to the following table for information on what to configure based on how your Oauth2 provider returns a user’s login:

Source of login	Required configuration
`login` or `username` field of the OAuth2 ID token.	N/A
Another field of the OAuth2 ID token.	Set `login_attribute_path` configuration option.
`login` or `username` field of the user information from the UserInfo endpoint.	N/A
Another field of the user information from the UserInfo endpoint.	Set `login_attribute_path` configuration option.
`login` or `username` field of the OAuth2 access token.	N/A
Another field of the OAuth2 access token.	Set `login_attribute_path` configuration option.

Use the `sub` claim for login

Most of the OAuth2 providers expose a stable subject identifier in the sub claim. You can use it to populate the Grafana login by setting login_attribute_path to sub. Because email is still required, also make sure Grafana can resolve the user’s email (for example by including the email scope or mapping a custom field via email_attribute_path).

Example configuration:

[auth.generic_oauth]
enabled = true
scopes = openid profile email
login_attribute_path = sub
# If your provider does not return `email` at the top level, map it explicitly
# email_attribute_path = user.email

Configure display name

Grafana can resolve a user’s display name from the OAuth2 ID token, user information retrieved from the OAuth2 UserInfo endpoint, or the OAuth2 access token. Grafana looks at these sources in the order listed until it finds a display name. If no display name is found, then user’s login is displayed instead.

Refer to the following table for information on what you need to configure depending on how your Oauth2 provider returns a user’s name:

Source of display name	Required configuration
`name` or `display_name` field of the OAuth2 ID token.	N/A
Another field of the OAuth2 ID token.	Set `name_attribute_path` configuration option.
`name` or `display_name` field of the user information from the UserInfo endpoint.	N/A
Another field of the user information from the UserInfo endpoint.	Set `name_attribute_path` configuration option.
`name` or `display_name` field of the OAuth2 access token.	N/A
Another field of the OAuth2 access token.	Set `name_attribute_path` configuration option.

Configure email address

Grafana can resolve the user’s email address from the OAuth2 ID token, the user information retrieved from the OAuth2 UserInfo endpoint, the OAuth2 access token, or the OAuth2 /emails endpoint. Grafana looks at these sources in the order listed until an email address is found. If no email is found, then the email address of the user is set to an empty string.

Refer to the following table for information on what to configure based on how the Oauth2 provider returns a user’s email address:

Source of email address	Required configuration
`email` field of the OAuth2 ID token.	N/A
`attributes` map of the OAuth2 ID token.	Set `email_attribute_name` configuration option. By default, Grafana searches for email under `email:primary` key.
`upn` field of the OAuth2 ID token.	N/A
`email` field of the user information from the UserInfo endpoint.	N/A
Another field of the user information from the UserInfo endpoint.	Set `email_attribute_path` configuration option.
`email` field of the OAuth2 access token.	N/A
`attributes` map of the OAuth2 access token.	Set `email_attribute_name` configuration option. By default, Grafana searches for email under `email:primary` key.
`upn` field of the OAuth2 access token.	N/A
Another field of the OAuth2 access token.	Set `email_attribute_path` configuration option.
Email address marked as primary from the `/emails` endpoint of the OAuth2 provider (obtained by appending `/emails` to the URL configured with `api_url`)	N/A

Configure a refresh token

When a user logs in using an OAuth2 provider, Grafana verifies that the access token has not expired. When an access token expires, Grafana uses the provided refresh token (if any exists) to obtain a new access token.

Grafana uses a refresh token to obtain a new access token without requiring the user to log in again. If a refresh token doesn’t exist, Grafana logs the user out of the system after the access token has expired.

To configure Generic OAuth to use a refresh token, set use_refresh_token configuration option to true and perform one or both of the following steps, if required:

Extend the scopes field of [auth.generic_oauth] section in Grafana configuration file with additional scopes.
Enable the refresh token on the provider.

Note
The accessTokenExpirationCheck feature toggle has been removed in Grafana v10.3.0 and the use_refresh_token configuration value will be used instead for configuring refresh token fetching and access token expiration check.

Configure JWT ID token validation

By default, Grafana extracts user information from ID tokens without validating their cryptographic signatures. To enhance security, you can enable JWT signature validation to ensure that ID tokens are authentic and have not been tampered with.

To enable JWT ID token validation:

Set validate_id_token to true in the [auth.generic_oauth] section of the Grafana configuration file.
Configure jwk_set_url with the URL of your OAuth2 provider’s JSON Web Key Set (JWKS) endpoint. This endpoint provides the public keys used to verify JWT signatures.

Common JWKS endpoint locations:
- OIDC providers: https://<provider-domain>/.well-known/jwks.json
- Auth0: https://<tenant>.auth0.com/.well-known/jwks.json
- Keycloak: https://<keycloak-domain>/realms/<realm>/.well-known/openid-configuration (contains jwks_uri)

Example configuration:

[auth.generic_oauth]
enabled = true
validate_id_token = true
jwk_set_url = https://your-provider.com/.well-known/jwks.json
client_id = <client id>
client_secret = <client secret>
auth_url = https://your-provider.com/authorize
token_url = https://your-provider.com/token
api_url = https://your-provider.com/userinfo

Note
When JWT validation is enabled, Grafana caches the JWKS keys to improve performance. The cache respects the Cache-Control header from the JWKS endpoint response. If no cache expiration is specified, keys are cached for 5 minutes by default.

Caution
If validate_id_token is set to true, you must configure jwk_set_url. Authentication will fail if the JWK Set URL is not provided or if the ID token signature cannot be verified.

Configure role mapping

Unless skip_org_role_sync option is enabled, the user’s role will be set to the role retrieved from the auth provider upon user login.

The user’s role is retrieved using a JMESPath expression from the role_attribute_path configuration option. Grafana will first evaluate the expression using the OAuth2 ID token. If no role is found, the expression will be evaluated using the user information obtained from the UserInfo endpoint. If still no role is found, the expression will be evaluated using the OAuth2 access token. To map the server administrator role, use the allow_assign_grafana_admin configuration option. Refer to configuration options for more information.

If no valid role is found, the user is assigned the role specified by the auto_assign_org_role option. You can disable this default role assignment by setting role_attribute_strict = true. This setting denies user access if no role or an invalid role is returned after evaluating the role_attribute_path and the org_mapping expressions.

You can use the org_attribute_path and org_mapping configuration options to assign the user to organizations and specify their role. For more information, refer to Org roles mapping example. If both org role mapping (org_mapping) and the regular role mapping (role_attribute_path) are specified, then the user will get the highest of the two mapped roles.

To ease configuration of a proper JMESPath expression, go to JMESPath to test and evaluate expressions with custom payloads.

Note
When using org_attribute_path, the value returned by the JMESPath expression must be an array, not a string.

Role mapping examples

This section includes examples of JMESPath expressions used for role mapping.

Map user organization role

In this example, the user has been granted the role of an Editor. The role assigned is based on the value of the property role, which must be a valid Grafana role such as Admin, Editor, Viewer or None.

Payload:

{
    ...
    "role": "Editor",
    ...
}

Config:

role_attribute_path = role

In the following more complex example, the user has been granted the Admin role. This is because they are a member of the admin group of their OAuth2 provider. If the user was a member of the editor group, they would be granted the Editor role, otherwise Viewer.

Payload:

{
    ...
    "groups": [
        "engineer",
        "admin",
    ],
    ...
}

Config:

role_attribute_path = contains(groups[*], 'admin') && 'Admin' || contains(groups[*], 'editor') && 'Editor' || 'Viewer'

Map server administrator role

In the following example, the user is granted the Grafana server administrator role.

Payload:

{
    ...
    "roles": [
        "admin",
    ],
    ...
}

Config:

role_attribute_path = contains(roles[*], 'admin') && 'GrafanaAdmin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'
allow_assign_grafana_admin = true

Map one role to all users

In this example, all users will be assigned Viewer role regardless of the user information received from the identity provider.

Config:

role_attribute_path = "'Viewer'"
skip_org_role_sync = false

Org roles mapping example

In this example, the user has been granted the role of a Viewer in the org_foo org, and the role of an Editor in the org_bar and org_baz orgs.

If the user was a member of the admin group, they would be granted the Grafana server administrator role.

Payload:

{
  "roles": ["org_foo", "org_bar", "another_org"]
}

Config:

role_attribute_path = contains(roles[*], 'admin') && 'GrafanaAdmin' || 'None'
allow_assign_grafana_admin = true
org_attribute_path = roles
org_mapping = org_foo:org_foo:Viewer org_bar:org_bar:Editor *:org_baz:Editor

Configure team synchronization

Note
Available in Grafana Enterprise and to customers on select Grafana Cloud plans. For pricing information, visit pricing or contact our sales team.

By using Team Sync, you can link your OAuth2 groups to teams within Grafana. This will automatically assign users to the appropriate teams. Teams for each user are synchronized when the user logs in.

Generic OAuth groups can be referenced by group ID, such as 8bab1c86-8fba-33e5-2089-1d1c80ec267d or myteam. Group information can be extracted from the OAuth2 ID token, user information from the UserInfo endpoint, or the OAuth2 access token. For information on configuring OAuth2 groups with Grafana using the groups_attribute_path configuration option, refer to configuration options.

To learn more about Team Sync, refer to Configure team sync.

Team synchronization example

Configuration:

groups_attribute_path = groups

Payload:

{
    ...
    "groups": [
        "engineers",
        "analysts",
    ],
    ...
}

Configuration options

The following table outlines the various Generic OAuth configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana. For more information, refer to Override configuration with environment variables.

Note
If the configuration option requires a JMESPath expression that includes a colon, enclose the entire expression in quotes to prevent parsing errors. For example role_attribute_path: "role:view"

Setting	Required	Supported on Cloud	Description	Default
`enabled`	No	Yes	Enables Generic OAuth authentication.	`false`
`name`	No	Yes	Name that refers to the Generic OAuth authentication from the Grafana user interface.	`OAuth`
`icon`	No	Yes	Icon used for the Generic OAuth authentication in the Grafana user interface.	`signin`
`client_id`	Yes	Yes	Client ID provided by your OAuth2 app.
`client_secret`	Yes	Yes	Client secret provided by your OAuth2 app.
`auth_url`	Yes	Yes	Authorization endpoint of your OAuth2 provider.
`token_url`	Yes	Yes	Endpoint used to obtain the OAuth2 access token.
`api_url`	Yes	Yes	Endpoint used to obtain user information compatible with OpenID UserInfo.
`auth_style`	No	Yes	Name of the OAuth2 AuthStyle to be used when ID token is requested from OAuth2 provider. It determines how `client_id` and `client_secret` are sent to Oauth2 provider. Available values are `AutoDetect`, `InParams` and `InHeader`.	`AutoDetect`
`scopes`	No	Yes	List of comma- or space-separated OAuth2 scopes.	`user:email`
`empty_scopes`	No	Yes	Set to `true` to use an empty scope during authentication.	`false`
`allow_sign_up`	No	Yes	Controls Grafana user creation through the Generic OAuth login. Only existing Grafana users can log in with Generic OAuth if set to `false`.	`true`
`auto_login`	No	Yes	Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login.	`false`
`login_prompt`	No	Yes	Indicates the type of user interaction when the user logs in with the IdP. Available values are `login`, `consent` and `select_account`.
`id_token_attribute_name`	No	Yes	The name of the key used to extract the ID token from the returned OAuth2 token.	`id_token`
`login_attribute_path`	No	Yes	JMESPath expression to use for user login lookup from the user ID token. For more information on how user login is retrieved, refer to Configure login.
`name_attribute_path`	No	Yes	JMESPath expression to use for user name lookup from the user ID token. This name will be used as the user’s display name. For more information on how user display name is retrieved, refer to Configure display name.
`email_attribute_path`	No	Yes	JMESPath expression to use for user email lookup from the user information. For more information on how user email is retrieved, refer to Configure email address.
`email_attribute_name`	No	Yes	Name of the key to use for user email lookup within the `attributes` map of OAuth2 ID token. For more information on how user email is retrieved, refer to Configure email address.	`email:primary`
`role_attribute_path`	No	Yes	JMESPath expression to use for Grafana role lookup. Grafana will first evaluate the expression using the OAuth2 ID token. If no role is found, the expression will be evaluated using the user information obtained from the UserInfo endpoint. If still no role is found, the expression will be evaluated using the OAuth2 access token. The result of the evaluation should be a valid Grafana role (`None`, `Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to Configure role mapping.
`role_attribute_strict`	No	Yes	Set to `true` to deny user login if the Grafana org role cannot be extracted using `role_attribute_path` or `org_mapping`. For more information on user role mapping, refer to Configure role mapping.	`false`
`skip_org_role_sync`	No	Yes	Set to `true` to stop automatically syncing user roles. This will allow you to set organization roles for your users from within Grafana manually.	`false`
`org_attribute_path`	No	No	JMESPath expression to use for Grafana org to role lookup. Grafana will first evaluate the expression using the OAuth2 ID token. If no value is returned, the expression will be evaluated using the user information obtained from the UserInfo endpoint. If still no value is returned, the expression will be evaluated using the OAuth2 access token. The result of the evaluation will be mapped to org roles based on `org_mapping`. For more information on org to role mapping, refer to Org roles mapping example.
`org_mapping`	No	No	List of comma- or space-separated `<ExternalOrgName>:<OrgIdOrName>:<Role>` mappings. Value can be `*` meaning “All users”. Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. For more information on external organization to role mapping, refer to Org roles mapping example.
`allow_assign_grafana_admin`	No	No	Set to `true` to enable automatic sync of the Grafana server administrator role. If this option is set to `true` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user the server administrator privileges and organization administrator role. If this option is set to `false` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user only organization administrator role. For more information on user role mapping, refer to Configure role mapping.	`false`
`groups_attribute_path`	No	Yes	JMESPath expression to use for user group lookup. Grafana will first evaluate the expression using the OAuth2 ID token. If no groups are found, the expression will be evaluated using the user information obtained from the UserInfo endpoint. If still no groups are found, the expression will be evaluated using the OAuth2 access token. The result of the evaluation should be a string array of groups.
`allowed_groups`	No	Yes	List of comma- or space-separated groups. The user should be a member of at least one group to log in. If you configure `allowed_groups`, you must also configure `groups_attribute_path`.
`allowed_organizations`	No	Yes	List of comma- or space-separated organizations. The user should be a member of at least one organization to log in.
`allowed_domains`	No	Yes	List of comma- or space-separated domains. The user should belong to at least one domain to log in.
`team_ids`	No	Yes	String list of team IDs. If set, the user must be a member of one of the given teams to log in. If you configure `team_ids`, you must also configure `teams_url` and `team_ids_attribute_path`.
`team_ids_attribute_path`	No	Yes	The JMESPath expression to use for Grafana team ID lookup within the results returned by the `teams_url` endpoint.
`teams_url`	No	Yes	The URL used to query for team IDs. If not set, the default value is `/teams`. If you configure `teams_url`, you must also configure `team_ids_attribute_path`.
`tls_skip_verify_insecure`	No	No	If set to `true`, the client accepts any certificate presented by the server and any host name in that certificate. You should only use this for testing, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks.	`false`
`tls_client_cert`	No	No	The path to the certificate.
`tls_client_key`	No	No	The path to the key.
`tls_client_ca`	No	No	The path to the trusted certificate authority list.
`use_pkce`	No	Yes	Set to `true` to use Proof Key for Code Exchange (PKCE). Grafana uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier.	`false`
`use_refresh_token`	No	Yes	Set to `true` to use refresh token and check access token expiration.	`false`
`validate_id_token`	No	Yes	Set to `true` to enable JWT signature validation for ID tokens. When enabled, `jwk_set_url` must be configured.	`false`
`jwk_set_url`	No	Yes	URL of the JSON Web Key Set (JWKS) endpoint used to verify JWT ID token signatures. Required when `validate_id_token` is set to `true`.
`signout_redirect_url`	No	Yes	URL to redirect to after the user logs out.

Examples of setting up Generic OAuth

This section includes examples of setting up Generic OAuth integration.

Set up OAuth2 with Descope

To set up Generic OAuth authentication with Descope, follow these steps:

Create a Descope Project here, and go through the Getting Started Wizard to configure your authentication. You can skip step if you already have Descope project set up.
If you wish to use a flow besides Sign Up or In, go to the IdP Applications menu in the console, and select your IdP application. Then alter the Flow Hosting URL query parameter ?flow=sign-up-or-in to change which flow id you wish to use.
Click Save.

Update the [auth.generic_oauth] section of the Grafana configuration file using the values from the Settings tab:

Note
You can get your Client ID (Descope Project ID) under Project Settings. Your Client Secret (Descope Access Key) can be generated under Access Keys.

[auth.generic_oauth]
enabled = true
allow_sign_up = true
auto_login = false
team_ids =
allowed_organizations =
name = Descope
client_id = <Descope Project ID>
client_secret = <Descope Access Key>
scopes = openid profile email descope.claims descope.custom_claims
auth_url = https://api.descope.com/oauth2/v1/authorize
token_url = https://api.descope.com/oauth2/v1/token
api_url = https://api.descope.com/oauth2/v1/userinfo
use_pkce = true
use_refresh_token = true

Set up OAuth2 with Auth0

Note
Support for the Auth0 “audience” feature is not currently available in Grafana. For roles and permissions, the available options are described here.

To set up Generic OAuth authentication with Auth0, follow these steps:

Create an Auth0 application using the following parameters:
- Name: Grafana
- Type: Regular Web Application
Go to the Settings tab of the application and set Allowed Callback URLs to https://<grafana domain>/login/generic_oauth.
Click Save Changes.

Update the [auth.generic_oauth] section of the Grafana configuration file using the values from the Settings tab:

[auth.generic_oauth]
enabled = true
allow_sign_up = true
auto_login = false
team_ids =
allowed_organizations =
name = Auth0
client_id = <client id>
client_secret = <client secret>
scopes = openid profile email offline_access
auth_url = https://<domain>/authorize
token_url = https://<domain>/oauth/token
api_url = https://<domain>/userinfo
use_pkce = true
use_refresh_token = true

Set up OAuth2 with Bitbucket

To set up Generic OAuth authentication with Bitbucket, follow these steps:

Navigate to Settings > Workspace setting > OAuth consumers in BitBucket.
Create an application by selecting Add consumer and using the following parameters:
- Allowed Callback URLs: https://<grafana domain>/login/generic_oauth
Click Save.

Update the [auth.generic_oauth] section of the Grafana configuration file using the values from the Key and Secret from the consumer description:

[auth.generic_oauth]
name = BitBucket
enabled = true
allow_sign_up = true
auto_login = false
client_id = <client key>
client_secret = <client secret>
scopes = account email
auth_url = https://bitbucket.org/site/oauth2/authorize
token_url = https://bitbucket.org/site/oauth2/access_token
api_url = https://api.bitbucket.org/2.0/user
teams_url = https://api.bitbucket.org/2.0/user/permissions/workspaces
team_ids_attribute_path = values[*].workspace.slug
team_ids =
allowed_organizations =
use_refresh_token = true

By default, a refresh token is included in the response for the Authorization Code Grant.

Set up OAuth2 with OneLogin

To set up Generic OAuth authentication with OneLogin, follow these steps:

Create a new Custom Connector in OneLogin with the following settings:
- Name: Grafana
- Sign On Method: OpenID Connect
- Redirect URI: https://<grafana domain>/login/generic_oauth
- Signing Algorithm: RS256
- Login URL: https://<grafana domain>/login/generic_oauth
Add an app to the Grafana Connector:
- Display Name: Grafana

Update the [auth.generic_oauth] section of the Grafana configuration file using the client ID and client secret from the SSO tab of the app details page:

Your OneLogin Domain will match the URL you use to access OneLogin.

[auth.generic_oauth]
name = OneLogin
enabled = true
allow_sign_up = true
auto_login = false
client_id = <client id>
client_secret = <client secret>
scopes = openid email name
auth_url = https://<onelogin domain>.onelogin.com/oidc/2/auth
token_url = https://<onelogin domain>.onelogin.com/oidc/2/token
api_url = https://<onelogin domain>.onelogin.com/oidc/2/me
team_ids =
allowed_organizations =

Set up OAuth2 with Dex

To set up Generic OAuth authentication with Dex IdP, follow these steps:

Add Grafana as a client in the Dex config YAML file:
YAML
```
staticClients:
  - id: <client id>
    name: Grafana
    secret: <client secret>
    redirectURIs:
      - 'https://<grafana domain>/login/generic_oauth'
```
Note
Unlike many other OAuth2 providers, Dex doesn’t provide <client secret>. Instead, a secret can be generated with for example openssl rand -hex 20.

Update the [auth.generic_oauth] section of the Grafana configuration:

[auth.generic_oauth]
name = Dex
enabled = true
client_id = <client id>
client_secret = <client secret>
scopes = openid email profile groups offline_access
auth_url = https://<dex base uri>/auth
token_url = https://<dex base uri>/token
api_url = https://<dex base uri>/userinfo

<dex base uri> corresponds to the issuer: configuration in Dex (e.g. the Dex domain possibly including a path such as e.g. /dex). The offline_access scope is needed when using refresh tokens.

Configure Microsoft Entra ID OAuth authentication

Fri, 03 Apr 2026 19:43:06 +0000

Configure Microsoft Entra ID OAuth authentication

The Microsoft Entra ID authentication allows you to use a Microsoft Entra ID (formerly known as Azure Active Directory) tenant as an identity provider for Grafana. You can use Entra ID application roles to assign users and groups to Grafana roles from the Azure Portal.

Caution
If you use the same email address in Microsoft Entra ID and in other authentication providers (such as Grafana.com), you need to do additional configuration to ensure that your users are matched correctly.

Refer to Using the same email address to login with different identity providers for more information.

Register your application with Microsoft Entra ID

To enable the Entra ID OAuth, register your application with Entra ID.

Log in to the Azure portal, then click Microsoft Entra ID in the side menu.
If you have access to more than one tenant, select your account in the upper right. Set your session to the Entra ID tenant you wish to use.
Under Manage in the side menu, click App Registrations > New Registration. Enter a descriptive name.
Under Redirect URI, select the app type Web.
Add the redirect URLs https://<grafana domain>/login/azuread and https://<grafana domain>, then click Register. The app’s Overview page opens.
Note the Application ID. This is the OAuth client ID.
Click Endpoints from the top menu.
- Note the OAuth 2.0 authorization endpoint (v2) URL. This is the authorization URL.
- Note the OAuth 2.0 token endpoint (v2). This is the token URL.
Click Certificates & secrets in the side menu, then add a new entry under the supported client authentication option you want to use. The following are the supported client authentication options with their respective configuration steps.
- Client secrets
  1. Add a new entry under Client secrets with the following configuration.
    - Description: Grafana OAuth 2.0
    - Expires: Select an expiration period
  2. Click Add then copy the key Value. This is the OAuth 2.0 client secret.
  Note
  Make sure that you copy the string in the Value field, rather than the one in the Secret ID field.
  1. You must have set client_authentication under [auth.azuread] to client_secret_post in the Grafana server configuration for this to work.
- Federated credentials
  - Managed Identity
    1. Refer to Configure an application to trust a managed identity (preview) for a complete guide on setting up a managed identity as a federated credential. Add a new entry under Federated credentials with the following configuration.
      - Federated credential scenario: Select Other issuer.
      - Issuer: The OAuth 2.0 / OIDC issuer URL of the Microsoft Entra ID authority. For example: https://login.microsoftonline.com/{tenantID}/v2.0.
      - Subject identifier: The Object (Principal) ID GUID of the Managed Identity.
      - Name: A unique descriptive name for the credential.
      - Description: Grafana OAuth.
      - Audience: The audience value that must appear in the external token. For Public cloud, it would be api://AzureADTokenExchange. See mentioned documentation for the full list of available audiences.
    2. Click Add, and then copy the Managed Identity Client ID and the federated credential Audience values. This is your OAuth 2.0 federated credential.
    3. You must have set client_authentication under [auth.azuread] to managed_identity in the Grafana server configuration for this to work.
    Note
    Managed identities as federated credentials are only applicable to workloads hosted in Azure.
    
    You can only add user-assigned managed identities as federated credentials on Entra ID applications.
  - Workload Identity (K8s/AKS)
    1. Refer to Federated identity credential for an Entra ID application for a complete guide on setting up a federated credential for workload identity. Add a new entry under Federated credentials with the following configuration.
      - Federated credential scenario: Select Kubernetes accessing Azure resources.
      - Cluster issuer URL: The OIDC issuer URL that your cluster is integrated with. For example: https://{region}.oic.prod-aks.azure.com/{tenant_id}/{uuid}.
      - Namespace: Namespace of your Grafana deployment. For example: grafana.
      - Service account name: Service account name of your Grafana deployment. For example: grafana.
      - Subject identifier: The expected identity (subject claim) from the OIDC token, which Azure uses to validate and authorize token issuance to the requesting workload. For example: system:serviceaccount:grafana:grafana.
      - Name: A unique descriptive name for the credential.
      - Description: Grafana OAuth.
      - Audience: The audience value that must appear in the external token. For Public cloud, it would be api://AzureADTokenExchange. See mentioned documentation for the full list of available audiences.
    2. You must have set client_authentication (env var GF_AUTH_AZUREAD_CLIENT_AUTHENTICATION) under [auth.azuread] to workload_identity in the Grafana server configuration for this to work.
    3. You may optionally set workload_identity_token_file (env var GF_AUTH_AZUREAD_WORKLOAD_IDENTITY_TOKEN_FILE) under [auth.azuread] to /var/run/secrets/azure/tokens/azure-identity-token in the Grafana server configuration for this to work. (Optional, defaults to /var/run/secrets/azure/tokens/azure-identity-token)
    4. You must have set client_id (env var GF_AUTH_AZUREAD_CLIENT_ID) under [auth.azuread] in the Grafana server configuration for this to work. This must match the Entra ID/Entra ID App Registration Application (client) ID.
    5. You must have set token_url (env var GF_AUTH_AZUREAD_TOKEN_URL) under [auth.azuread] to https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token in the Grafana server configuration for this to work.
    6. You must have set auth_url (env var GF_AUTH_AZUREAD_AUTH_URL) under [auth.azuread] to https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/authorize in the Grafana server configuration for this to work.
    7. You must have set federated_credential_audience (env var GF_AUTH_AZUREAD_FEDERATED_CREDENTIAL_AUDIENCE) under [auth.azuread] to api://AzureADTokenExchange in the Grafana server configuration for this to work.
  Note
  Managed identities as federated credentials are only applicable to workloads hosted in Azure.
  
  You can only add user-assigned managed identities as federated credentials on Entra ID applications.
Define the required application roles for Grafana using the Azure Portal or using the manifest file.
Go to Microsoft Entra ID and then to Enterprise Applications, under Manage.
Search for your application and click it.
Click Users and Groups.
Click Add user/group to add a user or group to the Grafana roles.

Note
When assigning a group to a Grafana role, ensure that users are direct members of the group. Users in nested groups will not have access to Grafana due to limitations within Entra ID side. For more information, see Microsoft Entra service limits and restrictions.

Configure application roles for Grafana in the Microsoft Entra ID portal

This section describes setting up basic application roles for Grafana within the Entra ID Portal. For more information, see Add app roles to your application and receive them in the token.

Go to App Registrations, search for your application, and click it.
Click App roles and then Create app role.
Define a role corresponding to each Grafana role: Viewer, Editor, and Admin.
1. Choose a Display name for the role. For example, “Grafana Editor”.
2. Set the Allowed member types to Users/Groups.
3. Ensure that the Value field matches the Grafana role name. For example, “Editor”.
4. Choose a Description for the role. For example, “Grafana Editor Users”.
5. Click Apply.

Configure application roles for Grafana in the manifest file

If you prefer to configure the application roles for Grafana in the manifest file, complete the following steps:

Go to App Registrations, search for your application, and click it.
Click Manifest.
Add a Universally Unique Identifier to each role.

Note
Every role requires a Universally Unique Identifier which you can generate on Linux with uuidgen, and on Windows through Microsoft PowerShell with New-Guid.

Replace each “SOME_UNIQUE_ID” with the generated ID in the manifest file:

	"appRoles": [
			{
				"allowedMemberTypes": [
					"User"
				],
				"description": "Grafana org admin Users",
				"displayName": "Grafana Org Admin",
				"id": "SOME_UNIQUE_ID",
				"isEnabled": true,
				"lang": null,
				"origin": "Application",
				"value": "Admin"
			},
			{
				"allowedMemberTypes": [
					"User"
				],
				"description": "Grafana read only Users",
				"displayName": "Grafana Viewer",
				"id": "SOME_UNIQUE_ID",
				"isEnabled": true,
				"lang": null,
				"origin": "Application",
				"value": "Viewer"
			},
			{
				"allowedMemberTypes": [
					"User"
				],
				"description": "Grafana Editor Users",
				"displayName": "Grafana Editor",
				"id": "SOME_UNIQUE_ID",
				"isEnabled": true,
				"lang": null,
				"origin": "Application",
				"value": "Editor"
			}
		],

Click Save.

Assign server administrator privileges

Use the application role GrafanaAdmin to grant users server administrator privileges. This is useful if you want to grant server administrator privileges to a subset of users.

Grafana also assigns the user the Admin role of the default organization.

Set the setting allow_assign_grafana_admin under [auth.azuread] to true for this to work. If the setting is set to false, the user is assigned the role of Admin of the default organization, but not server administrator privileges.

{
  "allowedMemberTypes": ["User"],
  "description": "Grafana server admin Users",
  "displayName": "Grafana Server Admin",
  "id": "SOME_UNIQUE_ID",
  "isEnabled": true,
  "lang": null,
  "origin": "Application",
  "value": "GrafanaAdmin"
}

Configure the Entra ID authentication client using the Grafana UI

After you’ve registered your application with Entra Id, As a Grafana Admin, you can configure your Entra ID OAuth client from within Grafana using the Grafana UI. To do this, navigate to the Administration > Authentication > Entra ID page and fill in the form. If you have a current configuration in the Grafana configuration file, the form will be pre-populated with those values. Otherwise the form will contain default values.

After you have filled in the form, click Save to save the configuration. If the save was successful, Grafana will apply the new configurations.

Note
If you run Grafana in high availability mode, configuration changes may not get applied to all Grafana instances immediately. You may need to wait a few minutes for the configuration to propagate to all Grafana instances.

Configure the Entra ID authentication client using the Terraform provider

resource "grafana_sso_settings" "azuread_sso_settings" {
  provider_name = "azuread"
  oauth2_settings {
    name                          = "Entra ID"
    auth_url                      = "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize"
    token_url                     = "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token"
    client_authentication         = "CLIENT_AUTHENTICATION_OPTION"
    client_id                     = "APPLICATION_ID"
    client_secret                 = "CLIENT_SECRET"
    managed_identity_client_id    = "MANAGED_IDENTITY_CLIENT_ID"
    federated_credential_audience = "FEDERATED_CREDENTIAL_AUDIENCE"
    allow_sign_up                 = true
    auto_login                    = false
    scopes                        = "openid email profile"
    allowed_organizations         = "TENANT_ID"
    role_attribute_strict         = false
    allow_assign_grafana_admin    = false
    skip_org_role_sync            = false
    use_pkce                      = true
    custom = {
      domain_hint = "contoso.com"
      force_use_graph_api = "true"
    }
  }
}

Refer to Terraform Registry for a complete reference on using the grafana_sso_settings resource.

Configure the Entra ID authentication client using the Grafana configuration file

Ensure that you have access to the Grafana configuration file.

Enable Entra ID OAuth in Grafana

Add the following to the Grafana configuration file:

[auth.azuread]
name = Entra ID
enabled = true
allow_sign_up = true
auto_login = false
client_authentication = CLIENT_AUTHENTICATION_OPTION
client_id = APPLICATION_ID
client_secret = CLIENT_SECRET
managed_identity_client_id = MANAGED_IDENTITY_CLIENT_ID
federated_credential_audience = FEDERATED_CREDENTIAL_AUDIENCE
scopes = openid email profile
auth_url = https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize
token_url = https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token
allowed_domains =
allowed_groups =
allowed_organizations = TENANT_ID
role_attribute_strict = false
allow_assign_grafana_admin = false
skip_org_role_sync = false
use_pkce = true

You can also use these environment variables to configure client_authentication, client_id, client_secret, managed_identity_client_id, and federated_credential_audience:

GF_AUTH_AZUREAD_CLIENT_AUTHENTICATION
GF_AUTH_AZUREAD_CLIENT_ID
GF_AUTH_AZUREAD_CLIENT_SECRET
GF_AUTH_AZUREAD_MANAGED_IDENTITY_CLIENT_ID
GF_AUTH_AZUREAD_FEDERATED_CREDENTIAL_AUDIENCE

Note
Verify that the Grafana root_url is set in your Azure Application Redirect URLs.

Configure refresh token

When a user logs in using an OAuth provider, Grafana verifies that the access token has not expired. When an access token expires, Grafana uses the provided refresh token (if any exists) to obtain a new access token.

Refresh token fetching and access token expiration check is enabled by default for the Entra ID provider since Grafana v10.1.0. If you would like to disable access token expiration check then set the use_refresh_token configuration value to false.

Note
The accessTokenExpirationCheck feature toggle has been removed in Grafana v10.3.0 and the use_refresh_token configuration value will be used instead for configuring refresh token fetching and access token expiration check.

Configure allowed tenants

To limit access to authenticated users who are members of one or more tenants, set allowed_organizations to a comma- or space-separated list of tenant IDs. You can find tenant IDs on the Azure portal under Microsoft Entra ID -> Overview.

Make sure to include the tenant IDs of all the federated Users’ root directory if your Entra ID contains external identities.

For example, if you want to only give access to members of the tenant example with an ID of 8bab1c86-8fba-33e5-2089-1d1c80ec267d, then set the following:

allowed_organizations = 8bab1c86-8fba-33e5-2089-1d1c80ec267d

Configure allowed groups

Microsoft Entra ID groups can be used to limit user access to Grafana. For more information about managing groups in Entra ID, refer to Manage Microsoft Entra groups and group membership.

To limit access to authenticated users who are members of one or more Entra ID groups, set allowed_groups to a comma- or space-separated list of group object IDs.

To find object IDs for a specific group on the Azure portal, go to Microsoft Entra ID > Manage > Groups.

You can find the Object Id of a group by clicking on the group and then clicking on Properties. The object ID is listed under Object ID. If you want to only give access to members of the group example with an Object Id of 8bab1c86-8fba-33e5-2089-1d1c80ec267d, then set the following:
```
  allowed_groups = 8bab1c86-8fba-33e5-2089-1d1c80ec267d
```
You must enable adding the group attribute to the tokens in your Entra ID App registration either from the Azure Portal or from the manifest file.

Configure group membership claims on the Azure Portal

To ensure that the groups claim is included in the token, add the groups claim to the token configuration either through the Azure Portal UI or by editing the manifest file.

To configure group membership claims from the Azure Portal UI, complete the following steps:

Navigate to the App Registrations page and select your application.
Under Manage in the side menu, select Token configuration.
Click Add groups claim and select the relevant option for your use case (for example, Security groups and Groups assigned to the application).

For more information, see Configure groups optional claims.

Note
If the user is a member of more than 200 groups, Entra ID does not emit the groups claim in the token and instead emits a group overage claim. To set up a group overage claim, see Users with over 200 Group assignments.

Configure group membership claim in the manifest file

Go to App Registrations, search for your application, and click it.
Click Manifest.

Add the following to the root of the manifest file:

"groupMembershipClaims": "ApplicationGroup, SecurityGroup"

Configure allowed domains

The allowed_domains option limits access to users who belong to specific domains. Separate domains with space or comma. For example,

allowed_domains = mycompany.com mycompany.org

PKCE

IETF’s RFC 7636 introduces “proof key for code exchange” (PKCE) which provides additional protection against some forms of authorization code interception attacks. PKCE will be required in OAuth 2.1.

You can disable PKCE in Grafana by setting use_pkce to false in the[auth.azuread] section.

To bypass the login screen and log in automatically, enable the “auto_login” feature. This setting is ignored if multiple auth providers are configured to use auto login.

auto_login = true

Team Sync

Note
Available in Grafana Enterprise and to customers on select Grafana Cloud plans. For pricing information, visit pricing or contact our sales team.

With Team Sync you can map your Entra ID groups to teams in Grafana so that your users will automatically be added to the correct teams.

You can reference Entra ID groups by group object ID, like 8bab1c86-8fba-33e5-2089-1d1c80ec267d.

To learn more, refer to the Team Sync documentation.

Skip organization role sync

If you don’t want Entra ID authentication to sync user roles and organization membership and prevent the sync of org roles from Entra ID, set skip_org_role_sync to true. Use this if you want to manage the organization roles for your users from within Grafana or that your organization roles are synced from another provider. See Configure Grafana for more details.

[auth.azuread]
# ..
# prevents the sync of org roles from Entra ID
skip_org_role_sync = true

Configuration options

The following table outlines the various Entra ID configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana. For more information, refer to Override configuration with environment variables.

Setting	Required	Supported on Cloud	Description	Default
`enabled`	No	Yes	Enables Entra ID authentication.	`false`
`name`	No	Yes	Name that refers to the Entra ID authentication from the Grafana user interface.	`OAuth`
`icon`	No	Yes	Icon used for the Entra ID authentication in the Grafana user interface.	`signin`
`client_authentication`	Yes	Yes	Defines the client authentication method used to authenticate to the token endpoint. Supported values: `none`, `client_secret_post`, `managed_identity`, or `workload_identity`.
`workload_identity_token_file`	No	Yes	The path to the token file used to authenticate to the OAuth2 provider. This is only required when `client_authentication` is set to `workload_identity`. The token file contains the service account token projected by Kubernetes.	`/var/run/secrets/azure/tokens/azure-identity-token`
`federated_credential_audience`	No	Yes	The audience of the federated identity credential of your OAuth2 app. Required when `client_authentication` is set to `managed_identity` or `workload_identity`. For public cloud, this is typically `api://AzureADTokenExchange`.	`api://AzureADTokenExchange`
`client_id`	Yes	Yes	Client ID of the App (`Application (client) ID` on the App registration dashboard).
`client_secret`	Yes	Yes	Client secret of the App.
`auth_url`	Yes	Yes	Authorization endpoint of the Entra ID OAuth2 provider.
`token_url`	Yes	Yes	Endpoint used to obtain the OAuth2 access token.
`auth_style`	No	Yes	Name of the OAuth2 AuthStyle to be used when ID token is requested from OAuth2 provider. It determines how `client_id` and `client_secret` are sent to Oauth2 provider. Available values are `AutoDetect`, `InParams` and `InHeader`.	`AutoDetect`
`scopes`	No	Yes	List of comma- or space-separated OAuth2 scopes.	`openid email profile`
`allow_sign_up`	No	Yes	Controls Grafana user creation through the Entra ID login. Only existing Grafana users can log in with Entra ID if set to `false`.	`true`
`auto_login`	No	Yes	Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login.	`false`
`login_prompt`	No	Yes	Indicates the type of user interaction when the user logs in with Entra ID. Available values are `login`, `consent` and `select_account`.
`role_attribute_strict`	No	Yes	Set to `true` to deny user login if the Grafana org role cannot be extracted using `role_attribute_path` or `org_mapping`. For more information on user role mapping, refer to Map roles.	`false`
`org_attribute_path`	No	No	JMESPath expression to use for Grafana org to role lookup. Grafana will first evaluate the expression using the OAuth2 ID token. If no value is returned, the expression will be evaluated using the user information obtained from the UserInfo endpoint. The result of the evaluation will be mapped to org roles based on `org_mapping`. For more information on org to role mapping, refer to Org roles mapping example.
`org_mapping`	No	No	List of comma- or space-separated `<ExternalOrgName>:<OrgIdOrName>:<Role>` mappings. Value can be `*` meaning “All users”. Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. For more information on external organization to role mapping, refer to Org roles mapping example.
`allow_assign_grafana_admin`	No	No	Set to `true` to automatically sync the Grafana server administrator role. When enabled, if the Entra ID user’s App role is `GrafanaAdmin`, Grafana grants the user server administrator privileges and the organization administrator role. If disabled, the user will only receive the organization administrator role. For more details on user role mapping, refer to Map roles.	`false`
`skip_org_role_sync`	No	Yes	Set to `true` to stop automatically syncing user roles. This will allow you to set organization roles for your users from within Grafana manually.	`false`
`allowed_groups`	No	Yes	List of comma- or space-separated groups. The user should be a member of at least one group to log in. If you configure `allowed_groups`, you must also configure Entra ID to include the `groups` claim following Configure group membership claims on the Azure Portal.
`allowed_organizations`	No	Yes	List of comma- or space-separated Azure tenant identifiers. The user should be a member of at least one tenant to log in.
`allowed_domains`	No	Yes	List of comma- or space-separated domains. The user should belong to at least one domain to log in.
`domain_hint`	No	Yes	The realm of the user in a federated directory. This skips the email-based discovery process that the user goes through on the Entra ID sign-in page, for a slightly more streamlined user experience. More info here.
`tls_skip_verify_insecure`	No	No	If set to `true`, the client accepts any certificate presented by the server and any host name in that certificate. You should only use this for testing, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks.	`false`
`tls_client_cert`	No	No	The path to the certificate.
`tls_client_key`	No	No	The path to the key.
`tls_client_ca`	No	No	The path to the trusted certificate authority list.
`use_pkce`	No	Yes	Set to `true` to use Proof Key for Code Exchange (PKCE). Grafana uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier.	`true`
`use_refresh_token`	No	Yes	Enables the use of refresh tokens and checks for access token expiration. When enabled, Grafana automatically adds the `offline_access` scope to the list of scopes.	`true`
`force_use_graph_api`	No	Yes	Set to `true` to always fetch groups from the Microsoft Graph API instead of the `id_token`. If a user belongs to more than 200 groups, the Microsoft Graph API will be used to retrieve the groups regardless of this setting.	`false`
`signout_redirect_url`	No	Yes	URL to redirect to after the user logs out.

Common troubleshooting

Here are some common issues and particulars you can run into when configuring Entra ID authentication in Grafana.

Users with over 200 Group assignments

To ensure that the token size doesn’t exceed HTTP header size limits, Entra ID limits the number of object IDs that it includes in the groups claim. If a user is member of more groups than the coverage limit (200), then Entra ID does not emit the groups claim in the token and emits a group overage claim instead.

More information in Groups overage claim

If Grafana receives a token with a group overage claim instead of a groups claim, Grafana attempts to retrieve the user’s group membership by calling the included endpoint.

The Entra ID App registration must include the following API permissions for group overage claim calls to succeed:

Permissions name	Type	Admin consent required	Status
`GroupMember.Read.All`	Delegated	Yes	Granted
`User.Read`	Delegated	No	Granted

Admin consent is required for the GroupMember.Read.All permission. To grant admin consent, navigate to API permissions in the App registration and select Grant admin consent for [your-organization].

Note
You can make Grafana always get group information from the Microsoft Graph API by turning on the force_use_graph_api setting in the configuration.

Configure the required Graph API permissions

Navigate to Microsoft Entra ID > Manage > App registrations and select your application.
Select API permissions and then click on Add a permission.
Select Microsoft Graph from the list of APIs.
Select Delegated permissions.
Under the GroupMember section, select GroupMember.Read.All.
Click Add permissions.
Select Microsoft Graph from the list of APIs.
Select Delegated permissions.
In the Select permissions pane, under the User section, select User.Read.
Click the Add permissions button at the bottom of the page.

Note
Admin consent may be required for this permission.

Force fetching groups from Microsoft Graph API

To force fetching groups from Microsoft Graph API instead of the id_token, you can use the force_use_graph_api configuration option.

[auth.azuread]
force_use_graph_api = true

Map roles

By default, Entra ID authentication will map users to organization roles based on the most privileged application role assigned to the user in Entra ID.

If no application role is found, the user is assigned the role specified by the auto_assign_org_role option. You can disable this default role assignment by setting role_attribute_strict = true. This setting denies user access if no role or an invalid role is returned and the org_mapping expression evaluates to an empty mapping.

You can use the org_mapping configuration option to assign the user to multiple organizations and specify their role based on their Entra ID group membership. For more information, refer to Org roles mapping example. If the org role mapping (org_mapping) is specified and Entra ID returns a valid role, then the user will get the highest of the two roles.

On every login the user organization role will be reset to match Entra ID’s application role and their organization membership will be reset to the default organization.

Org roles mapping example

The Entra ID integration uses the external users’ groups in the org_mapping configuration to map organizations and roles based on their Entra ID group membership.

In this example, the user has been granted the role of a Viewer in the org_foo organization, and the role of an Editor in the org_bar and org_baz orgs.

The external user is part of the following Entra ID groups: 032cb8e0-240f-4347-9120-6f33013e817a and bce1c492-0679-4989-941b-8de5e6789cb9.

Config:

org_mapping = ["032cb8e0-240f-4347-9120-6f33013e817a:org_foo:Viewer", "bce1c492-0679-4989-941b-8de5e6789cb9:org_bar:Editor", "*:org_baz:Editor"]

Configure GitHub OAuth authentication

Fri, 03 Apr 2026 19:43:06 +0000

Configure GitHub OAuth authentication

This topic describes how to configure GitHub OAuth authentication.

Note
If Users use the same email address in GitHub that they use with other authentication providers (such as Grafana.com), you need to do additional configuration to ensure that the users are matched correctly. Please refer to the Using the same email address to login with different identity providers documentation for more information.

Before you begin

Ensure you know how to create a GitHub OAuth app. Consult GitHub’s documentation on creating an OAuth app for more information.

Create a GitHub OAuth App

Log in to your GitHub account. In Profile > Settings > Developer settings, select OAuth Apps.
Click New OAuth App.
Fill out the fields, using your Grafana homepage URL when appropriate. In the Authorization callback URL field, enter the following: https://<YOUR-GRAFANA-URL>/login/github .
Note your client ID.
Generate, then note, your client secret.

Configure GitHub authentication client using the Grafana UI

As a Grafana Admin, you can configure GitHub OAuth client from within Grafana using the GitHub UI. To do this, navigate to Administration > Authentication > GitHub page and fill in the form. If you have a current configuration in the Grafana configuration file, the form will be pre-populated with those values. Otherwise the form will contain default values.

After you have filled in the form, click Save. If the save was successful, Grafana will apply the new configurations.

Note
If you run Grafana in high availability mode, configuration changes may not get applied to all Grafana instances immediately. You may need to wait a few minutes for the configuration to propagate to all Grafana instances.

Refer to configuration options for more information.

Configure GitHub authentication client using the Terraform provider

resource "grafana_sso_settings" "github_sso_settings" {
  provider_name = "github"
  oauth2_settings {
    name                  = "Github"
    client_id             = "YOUR_GITHUB_APP_CLIENT_ID"
    client_secret         = "YOUR_GITHUB_APP_CLIENT_SECRET"
    allow_sign_up         = true
    auto_login            = false
    scopes                = "user:email,read:org"
    team_ids              = "150,300"
    allowed_organizations = "[\"My Organization\", \"Octocats\"]"
    allowed_domains       = "mycompany.com mycompany.org"
    role_attribute_path   = "[login=='octocat'][0] && 'GrafanaAdmin' || 'Viewer'"
  }
}

Go to Terraform Registry for a complete reference on using the grafana_sso_settings resource.

Configure GitHub authentication client using the Grafana configuration file

Ensure that you have access to the Grafana configuration file.

Configure GitHub authentication

To configure GitHub authentication with Grafana, follow these steps:

Create an OAuth application in GitHub.
Set the callback URL for your GitHub OAuth app to http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/github.

Ensure that the callback URL is the complete HTTP address that you use to access Grafana via your browser, but with the appended path of /login/github.

For the callback URL to be correct, it might be necessary to set the root_url option in the [server]section of the Grafana configuration file. For example, if you are serving Grafana behind a proxy.

Refer to the following table to update field values located in the [auth.github] section of the Grafana configuration file:

Field	Description
`client_id`, `client_secret`	These values must match the client ID and client secret from your GitHub OAuth app.
`enabled`	Enables GitHub authentication. Set this value to `true`.

Review the list of other GitHub configuration options and complete them, as necessary.

Configure role mapping.
Optional: Configure team synchronization.
Restart Grafana.

You should now see a GitHub login button on the login page and be able to log in or sign up with your GitHub accounts.

Configure role mapping

Unless the skip_org_role_sync option is enabled, the user’s role will be set to the role retrieved from GitHub upon user login.

The user’s role is retrieved using a JMESPath expression from the role_attribute_path configuration option. To map the server administrator role, use the allow_assign_grafana_admin configuration option. Refer to configuration options for more information.

You can use the org_mapping configuration options to assign the user to organizations and specify their role based on their GitHub team membership. For more information, refer to Org roles mapping example. If both org role mapping (org_mapping) and the regular role mapping (role_attribute_path) are specified, then the user will get the highest of the two mapped roles.

To ease configuration of a proper JMESPath expression, go to JMESPath to test and evaluate expressions with custom payloads.

Role mapping examples

This section includes examples of JMESPath expressions used for role mapping.

Org roles mapping example

The GitHub integration uses the external users’ teams in the org_mapping configuration to map organizations and roles based on their GitHub team membership.

In this example, the user has been granted the role of a Viewer in the org_foo organization, and the role of an Editor in the org_bar and org_baz orgs.

The external user is part of the following GitHub teams: @my-github-organization/my-github-team-1 and @my-github-organization/my-github-team-2.

Config:

org_mapping = @my-github-organization/my-github-team-1:org_foo:Viewer @my-github-organization/my-github-team-2:org_bar:Editor *:org_baz:Editor

Map roles using GitHub user information

In this example, the user with login octocat has been granted the Admin role. All other users are granted the Viewer role.

role_attribute_path = [login=='octocat'][0] && 'Admin' || 'Viewer'

Map roles using GitHub teams

In this example, the user from GitHub team my-github-team has been granted the Editor role. All other users are granted the Viewer role.

role_attribute_path = contains(groups[*], '@my-github-organization/my-github-team') && 'Editor' || 'Viewer'

Map roles using multiple GitHub teams

In this example, the users from GitHub teams admins and devops have been granted the Admin role, the users from GitHub teams engineers and managers have been granted the Editor role, the users from GitHub team qa have been granted the Viewer role and all other users are granted the None role.

role_attribute_path = contains(groups[*], '@my-github-organization/admins') && 'Admin' || contains(groups[*], '@my-github-organization/devops') && 'Admin' || contains(groups[*], '@my-github-organization/engineers') && 'Editor' || contains(groups[*], '@my-github-organization/managers') && 'Editor' || contains(groups[*], '@my-github-organization/qa') && 'Viewer' || 'None'

Map server administrator role

In this example, the user with login octocat has been granted the Admin organization role as well as the Grafana server admin role. All other users are granted the Viewer role.

role_attribute_path = [login=='octocat'][0] && 'GrafanaAdmin' || 'Viewer'

Map one role to all users

In this example, all users will be assigned Viewer role regardless of the user information received from the identity provider.

role_attribute_path = "'Viewer'"
skip_org_role_sync = false

Example of GitHub configuration in Grafana

This section includes an example of GitHub configuration in the Grafana configuration file.

[auth.github]
enabled = true
client_id = YOUR_GITHUB_APP_CLIENT_ID
client_secret = YOUR_GITHUB_APP_CLIENT_SECRET
scopes = user:email,read:org
auth_url = https://github.com/login/oauth/authorize
token_url = https://github.com/login/oauth/access_token
api_url = https://api.github.com/user
allow_sign_up = true
auto_login = false
team_ids = 150,300
allowed_organizations = ["My Organization", "Octocats"]
allowed_domains = mycompany.com mycompany.org
role_attribute_path = [login=='octocat'][0] && 'GrafanaAdmin' || 'Viewer'

Configure team synchronization

Note
Available in Grafana Enterprise and Grafana Cloud

By using Team Sync, you can map teams from your GitHub organization to teams within Grafana. This will automatically assign users to the appropriate teams. Teams for each user are synchronized when the user logs in.

GitHub teams can be referenced in two ways:

https://github.com/orgs/<org>/teams/<slug>
@<org>/<slug>

Examples: https://github.com/orgs/grafana/teams/developers or @grafana/developers.

To learn more about Team Sync, refer to Configure team sync.

Configuration options

The table below describes all GitHub OAuth configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana. For more information, refer to Override configuration with environment variables.

Note
If the configuration option requires a JMESPath expression that includes a colon, enclose the entire expression in quotes to prevent parsing errors. For example role_attribute_path: "role:view"

Setting	Required	Supported on Cloud	Description	Default
`enabled`	No	Yes	Whether GitHub OAuth authentication is allowed.	`false`
`name`	No	Yes	Name used to refer to the GitHub authentication in the Grafana user interface.	`GitHub`
`icon`	No	Yes	Icon used for GitHub authentication in the Grafana user interface.	`github`
`client_id`	Yes	Yes	Client ID provided by your GitHub OAuth app.
`client_secret`	Yes	Yes	Client secret provided by your GitHub OAuth app.
`auth_url`	Yes	Yes	Authorization endpoint of your GitHub OAuth provider.	`https://github.com/login/oauth/authorize`
`token_url`	Yes	Yes	Endpoint used to obtain GitHub OAuth access token.	`https://github.com/login/oauth/access_token`
`api_url`	Yes	Yes	Endpoint used to obtain GitHub user information compatible with OpenID UserInfo.	`https://api.github.com/user`
`scopes`	No	Yes	List of comma- or space-separated GitHub OAuth scopes.	`user:email,read:org`
`allow_sign_up`	No	Yes	Whether to allow new Grafana user creation through GitHub login. If set to `false`, then only existing Grafana users can log in with GitHub OAuth.	`true`
`auto_login`	No	Yes	Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login.	`false`
`login_prompt`	No	Yes	Indicates the type of user interaction when the user logs in with GitHub. Available values are `login`, `consent` and `select_account`.
`role_attribute_path`	No	Yes	JMESPath expression to use for Grafana role lookup. Grafana will first evaluate the expression using the user information obtained from the UserInfo endpoint. If no role is found, Grafana creates a JSON data with `groups` key that maps to GitHub teams obtained from GitHub’s `/api/user/teams` endpoint, and evaluates the expression using this data. The result of the evaluation should be a valid Grafana role (`None`, `Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to Configure role mapping.
`role_attribute_strict`	No	Yes	Set to `true` to deny user login if the Grafana org role cannot be extracted using `role_attribute_path` or `org_mapping`. For more information on user role mapping, refer to Configure role mapping.	`false`
`org_mapping`	No	No	List of comma- or space-separated `<ExternalGitHubTeamName>:<OrgIdOrName>:<Role>` mappings. Value can be `*` meaning “All users”. Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. For more information on external organization to role mapping, refer to Org roles mapping example.
`skip_org_role_sync`	No	Yes	Set to `true` to stop automatically syncing user roles.	`false`
`allow_assign_grafana_admin`	No	No	Set to `true` to enable automatic sync of the Grafana server administrator role. If this option is set to `true` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user the server administrator privileges and organization administrator role. If this option is set to `false` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user only organization administrator role. For more information on user role mapping, refer to Configure role mapping.	`false`
`allowed_organizations`	No	Yes	List of comma- or space-separated organizations. User must be a member of at least one organization to log in.
`allowed_domains`	No	Yes	List of comma- or space-separated domains. User must belong to at least one domain to log in.
`team_ids`	No	Yes	Integer list of team IDs. If set, user has to be a member of one of the given teams to log in.
`tls_skip_verify_insecure`	No	No	If set to `true`, the client accepts any certificate presented by the server and any host name in that certificate. You should only use this for testing, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks.	`false`
`tls_client_cert`	No	No	The path to the certificate.
`tls_client_key`	No	No	The path to the key.
`tls_client_ca`	No	No	The path to the trusted certificate authority list.
`signout_redirect_url`	No	Yes	URL to redirect to after the user logs out.

Configure GitLab OAuth authentication

Fri, 03 Apr 2026 19:43:06 +0000

Configure GitLab OAuth authentication

This topic describes how to configure GitLab OAuth authentication.

Note
If Users use the same email address in GitLab that they use with other authentication providers (such as Grafana.com), you need to do additional configuration to ensure that the users are matched correctly. Please refer to the Using the same email address to login with different identity providers documentation for more information.

Before you begin

Ensure you know how to create a GitLab OAuth application. Consult GitLab’s documentation on creating a GitLab OAuth application for more information.

Create a GitLab OAuth Application

Log in to your GitLab account and go to Profile > Preferences > Applications.
Click Add new application.
Fill out the fields.
- In the Redirect URI field, enter the following: https://<YOUR-GRAFANA-URL>/login/gitlab and check openid, email, profile in the Scopes list.
- Leave the Confidential checkbox checked.
Click Save application.
Note your Application ID (this is the Client Id) and Secret (this is the Client Secret).

Configure GitLab authentication client using the Grafana UI

As a Grafana Admin, you can configure GitLab OAuth client from within Grafana using the GitLab UI. To do this, navigate to Administration > Authentication > GitLab page and fill in the form. If you have a current configuration in the Grafana configuration file then the form will be pre-populated with those values otherwise the form will contain default values.

After you have filled in the form, click Save to save the configuration. If the save was successful, Grafana will apply the new configurations.

Note
If you run Grafana in high availability mode, configuration changes may not get applied to all Grafana instances immediately. You may need to wait a few minutes for the configuration to propagate to all Grafana instances.

Refer to configuration options for more information.

Configure GitLab authentication client using the Terraform provider

resource "grafana_sso_settings" "gitlab_sso_settings" {
  provider_name = "gitlab"
  oauth2_settings {
    name                  = "Gitlab"
    client_id             = "YOUR_GITLAB_APPLICATION_ID"
    client_secret         = "YOUR_GITLAB_APPLICATION_SECRET"
    allow_sign_up         = true
    auto_login            = false
    scopes                = "openid email profile"
    allowed_domains       = "mycompany.com mycompany.org"
    role_attribute_path   = "contains(groups[*], 'example-group') && 'Editor' || 'Viewer'"
    role_attribute_strict = false
    allowed_groups        = "[\"admins\", \"software engineers\", \"developers/frontend\"]"
    use_pkce              = true
    use_refresh_token     = true
  }
}

Go to Terraform Registry for a complete reference on using the grafana_sso_settings resource.

Configure GitLab authentication client using the Grafana configuration file

Ensure that you have access to the Grafana configuration file.

Steps

To configure GitLab authentication with Grafana, follow these steps:

Create an OAuth application in GitLab.
1. Set the redirect URI to http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/gitlab.
  
  Ensure that the Redirect URI is the complete HTTP address that you use to access Grafana via your browser, but with the appended path of /login/gitlab.
  
  For the Redirect URI to be correct, it might be necessary to set the root_url option in the [server]section of the Grafana configuration file. For example, if you are serving Grafana behind a proxy.
2. Set the OAuth2 scopes to openid, email and profile.

Refer to the following table to update field values located in the [auth.gitlab] section of the Grafana configuration file:

Field	Description
`client_id`, `client_secret`	These values must match the `Application ID` and `Secret` from your GitLab OAuth application.
`enabled`	Enables GitLab authentication. Set this value to `true`.

Review the list of other GitLab configuration options and complete them, as necessary.

Optional: Configure a refresh token:

a. Set use_refresh_token to true in [auth.gitlab] section in Grafana configuration file.
Configure role mapping.
Optional: Configure team synchronization.
Restart Grafana.

You should now see a GitLab login button on the login page and be able to log in or sign up with your GitLab accounts.

Configure a refresh token

By default, GitLab provides a refresh token.

Refresh token fetching and access token expiration check is enabled by default for the GitLab provider since Grafana v10.1.0. If you would like to disable access token expiration check then set the use_refresh_token configuration value to false.

Note
The accessTokenExpirationCheck feature toggle has been removed in Grafana v10.3.0. Use the use_refresh_token configuration value instead for configuring refresh token fetching and access token expiration check.

Configure JWT ID token validation

To enable JWT ID token validation:

Set validate_id_token to true in the [auth.gitlab] section of the Grafana configuration file.
Configure jwk_set_url with the URL of your GitLab instance’s JSON Web Key Set (JWKS) endpoint. This endpoint provides the public keys used to verify JWT signatures.

For GitLab.com, the JWKS endpoint is: https://gitlab.com/oauth/discovery/keys

For self-hosted GitLab instances, the JWKS endpoint is typically: https://<your-gitlab-domain>/oauth/discovery/keys

Example configuration:

[auth.gitlab]
enabled = true
validate_id_token = true
jwk_set_url = https://gitlab.com/oauth/discovery/keys
client_id = <client id>
client_secret = <client secret>
scopes = openid email profile

Note
When JWT validation is enabled, Grafana caches the JWKS keys to improve performance. The cache respects the Cache-Control header from the JWKS endpoint response. If no cache expiration is specified, keys are cached for 5 minutes by default.

Caution
If validate_id_token is set to true, you must configure jwk_set_url. Authentication will fail if the JWK Set URL is not provided or if the ID token signature cannot be verified.

Configure allowed groups

To limit access to authenticated users that are members of one or more GitLab groups, set allowed_groups to a comma or space-separated list of groups.

GitLab’s groups are referenced by the group name. For example, developers. To reference a subgroup frontend, use developers/frontend. Note that in GitLab, the group or subgroup name does not always match its display name, especially if the display name contains spaces or special characters. Make sure you always use the group or subgroup name as it appears in the URL of the group or subgroup.

Configure role mapping

Unless skip_org_role_sync option is enabled, the user’s role will be set to the role retrieved from GitLab upon user login.

You can use the org_mapping configuration option to assign the user to multiple organizations and specify their role based on their GitLab group membership. For more information, refer to Org roles mapping example. If the org role mapping (org_mapping) is specified and Entra ID returns a valid role, then the user will get the highest of the two roles.

To ease configuration of a proper JMESPath expression, go to JMESPath to test and evaluate expressions with custom payloads.

Role mapping examples

This section includes examples of JMESPath expressions used for role mapping.

Org roles mapping example

The GitLab integration uses the external users’ groups in the org_mapping configuration to map organizations and roles based on their GitLab group membership.

In this example, the user has been granted the role of a Viewer in the org_foo organization, and the role of an Editor in the org_bar and org_baz orgs.

The external user is part of the following GitLab groups: groupd-1 and group-2.

Config:

org_mapping = group-1:org_foo:Viewer groupd-1:org_bar:Editor *:org_baz:Editor

Map roles using user information from OAuth token

In this example, the user with email admin@company.com has been granted the Admin role. All other users are granted the Viewer role.

role_attribute_path = email=='admin@company.com' && 'Admin' || 'Viewer'

Map roles using groups

In this example, the user from GitLab group ’example-group’ have been granted the Editor role. All other users are granted the Viewer role.

role_attribute_path = contains(groups[*], 'example-group') && 'Editor' || 'Viewer'

Map server administrator role

In this example, the user with email admin@company.com has been granted the Admin organization role as well as the Grafana server admin role. All other users are granted the Viewer role.

role_attribute_path = email=='admin@company.com' && 'GrafanaAdmin' || 'Viewer'

Map one role to all users

In this example, all users will be assigned Viewer role regardless of the user information received from the identity provider.

role_attribute_path = "'Viewer'"
skip_org_role_sync = false

Example of GitLab configuration in Grafana

This section includes an example of GitLab configuration in the Grafana configuration file.

[auth.gitlab]
enabled = true
allow_sign_up = true
auto_login = false
client_id = YOUR_GITLAB_APPLICATION_ID
client_secret = YOUR_GITLAB_APPLICATION_SECRET
scopes = openid email profile
auth_url = https://gitlab.com/oauth/authorize
token_url = https://gitlab.com/oauth/token
api_url = https://gitlab.com/api/v4
role_attribute_path = contains(groups[*], 'example-group') && 'Editor' || 'Viewer'
role_attribute_strict = false
allow_assign_grafana_admin = false
allowed_groups = ["admins", "software engineers", "developers/frontend"]
allowed_domains = mycompany.com mycompany.org
tls_skip_verify_insecure = false
use_pkce = true
use_refresh_token = true

Configure team synchronization

Note
Available in Grafana Enterprise and Grafana Cloud

By using Team Sync, you can map GitLab groups to teams within Grafana. This will automatically assign users to the appropriate teams. Teams for each user are synchronized when the user logs in.

GitLab groups are referenced by the group name. For example, developers. To reference a subgroup frontend, use developers/frontend. Note that in GitLab, the group or subgroup name does not always match its display name, especially if the display name contains spaces or special characters. Make sure you always use the group or subgroup name as it appears in the URL of the group or subgroup.

To learn more about Team Sync, refer to Configure team sync.

Configuration options

The following table describes all GitLab OAuth configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana. For more information, refer to Override configuration with environment variables.

Note
If the configuration option requires a JMESPath expression that includes a colon, enclose the entire expression in quotes to prevent parsing errors. For example role_attribute_path: "role:view"

Setting	Required	Supported on Cloud	Description	Default
`enabled`	Yes	Yes	Whether GitLab OAuth authentication is allowed.	`false`
`client_id`	Yes	Yes	Client ID provided by your GitLab OAuth app.
`client_secret`	Yes	Yes	Client secret provided by your GitLab OAuth app.
`auth_url`	Yes	Yes	Authorization endpoint of your GitLab OAuth provider. If you use your own instance of GitLab instead of gitlab.com, adjust `auth_url` by replacing the `gitlab.com` hostname with your own.	`https://gitlab.com/oauth/authorize`
`token_url`	Yes	Yes	Endpoint used to obtain GitLab OAuth access token. If you use your own instance of GitLab instead of gitlab.com, adjust `token_url` by replacing the `gitlab.com` hostname with your own.	`https://gitlab.com/oauth/token`
`api_url`	No	Yes	Grafana uses `<api_url>/user` endpoint to obtain GitLab user information compatible with OpenID UserInfo.	`https://gitlab.com/api/v4`
`name`	No	Yes	Name used to refer to the GitLab authentication in the Grafana user interface.	`GitLab`
`icon`	No	Yes	Icon used for GitLab authentication in the Grafana user interface.	`gitlab`
`scopes`	No	Yes	List of comma or space-separated GitLab OAuth scopes.	`openid email profile`
`allow_sign_up`	No	Yes	Whether to allow new Grafana user creation through GitLab login. If set to `false`, then only existing Grafana users can log in with GitLab OAuth.	`true`
`auto_login`	No	Yes	Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login.	`false`
`login_prompt`	No	Yes	Indicates the type of user interaction when the user logs in with GitLab. Available values are `login`, `consent` and `select_account`.
`role_attribute_path`	No	Yes	JMESPath expression to use for Grafana role lookup. Grafana will first evaluate the expression using the GitLab OAuth token. If no role is found, Grafana creates a JSON data with `groups` key that maps to groups obtained from GitLab’s `/oauth/userinfo` endpoint, and evaluates the expression using this data. Finally, if a valid role is still not found, the expression is evaluated against the user information retrieved from `api_url/users` endpoint and groups retrieved from `api_url/groups` endpoint. The result of the evaluation should be a valid Grafana role (`None`, `Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to Configure role mapping.
`role_attribute_strict`	No	Yes	Set to `true` to deny user login if the Grafana role cannot be extracted using `role_attribute_path`. For more information on user role mapping, refer to Configure role mapping.	`false`
`org_mapping`	No	No	List of comma- or space-separated `<ExternalGitlabGroupName>:<OrgIdOrName>:<Role>` mappings. Value can be `*` meaning “All users”. Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. For more information on external organization to role mapping, refer to Org roles mapping example.
`skip_org_role_sync`	No	Yes	Set to `true` to stop automatically syncing user roles.	`false`
`allow_assign_grafana_admin`	No	No	Set to `true` to enable automatic sync of the Grafana server administrator role. If this option is set to `true` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user the server administrator privileges and organization administrator role. If this option is set to `false` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user only organization administrator role. For more information on user role mapping, refer to Configure role mapping.	`false`
`allowed_domains`	No	Yes	List of comma or space-separated domains. User must belong to at least one domain to log in.
`allowed_groups`	No	Yes	List of comma or space-separated groups. The user should be a member of at least one group to log in.
`tls_skip_verify_insecure`	No	No	If set to `true`, the client accepts any certificate presented by the server and any host name in that certificate. You should only use this for testing, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks.	`false`
`tls_client_cert`	No	No	The path to the certificate.
`tls_client_key`	No	No	The path to the key.
`tls_client_ca`	No	No	The path to the trusted certificate authority list.
`use_pkce`	No	Yes	Set to `true` to use Proof Key for Code Exchange (PKCE). Grafana uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier.	`true`
`use_refresh_token`	No	Yes	Set to `true` to use refresh token and check access token expiration. The `accessTokenExpirationCheck` feature toggle should also be enabled to use refresh token.	`true`
`validate_id_token`	No	Yes	If enabled, Grafana will validate the JWT signature of ID tokens using the JWKS endpoint. This enhances security by ensuring tokens are authentic and have not been tampered with.	`false`
`jwk_set_url`	No	Yes	URL of the JSON Web Key Set (JWKS) endpoint used to verify JWT ID token signatures. Required when ID token validation is enabled. For GitLab.com, use `https://gitlab.com/oauth/discovery/keys`. For self-hosted GitLab instances, use `https://<your-gitlab-domain>/oauth/discovery/keys`.
`signout_redirect_url`	No	Yes	URL to redirect to after the user logs out.

Configure Google OAuth authentication

Fri, 03 Apr 2026 19:43:06 +0000

Configure Google OAuth authentication

To enable Google OAuth you must register your application with Google. Google will generate a client ID and secret key for you to use.

Note
If Users use the same email address in Google that they use with other authentication providers (such as Grafana.com), you need to do additional configuration to ensure that the users are matched correctly. Please refer to the Using the same email address to login with different identity providers documentation for more information.

Create Google OAuth keys

First, you need to create a Google OAuth Client:

Go to https://console.developers.google.com/apis/credentials.
Create a new project if you don’t have one already.
1. Enter a project name. The Organization and Location fields should both be set to your organization’s information.
2. In OAuth consent screen select the External User Type. Click CREATE.
3. Fill out the requested information using the URL of your Grafana Cloud instance.
4. Accept the defaults, or customize the consent screen options.
Click Create Credentials, then click OAuth Client ID in the drop-down menu
Enter the following:
- Application Type: Web application
- Name: Grafana
- Authorized JavaScript origins: https://<YOUR_GRAFANA_URL>
- Authorized redirect URIs: https://<YOUR_GRAFANA_URL>/login/google
- Replace <YOUR_GRAFANA_URL> with the URL of your Grafana instance.
  Note
  The URL you enter is the one for your Grafana instance home page, not your Grafana Cloud portal URL.
Click Create
Copy the Client ID and Client Secret from the ‘OAuth Client’ modal

Configure Google authentication client using the Grafana UI

As a Grafana Admin, you can configure Google OAuth client from within Grafana using the Google UI. To do this, navigate to Administration > Authentication > Google page and fill in the form. If you have a current configuration in the Grafana configuration file then the form will be pre-populated with those values otherwise the form will contain default values.

After you have filled in the form, click Save. If the save was successful, Grafana will apply the new configurations.

If you need to reset changes made in the UI back to the default values, click Reset. After you have reset the changes, Grafana will apply the configuration from the Grafana configuration file (if there is any configuration) or the default values.

Note
If you run Grafana in high availability mode, configuration changes may not get applied to all Grafana instances immediately. You may need to wait a few minutes for the configuration to propagate to all Grafana instances.

Configure Google authentication client using the Terraform provider

resource "grafana_sso_settings" "google_sso_settings" {
  provider_name = "google"
  oauth2_settings {
    name            = "Google"
    client_id       = "CLIENT_ID"
    client_secret   = "CLIENT_SECRET"
    allow_sign_up   = true
    auto_login      = false
    scopes          = "openid email profile"
    allowed_domains = "mycompany.com mycompany.org"
    hosted_domain   = "mycompany.com"
    use_pkce        = true
  }
}

Go to Terraform Registry for a complete reference on using the grafana_sso_settings resource.

Configure Google authentication client using the Grafana configuration file

Ensure that you have access to the Grafana configuration file.

Enable Google OAuth in Grafana

Specify the Client ID and Secret in the Grafana configuration file. For example:

[auth.google]
enabled = true
allow_sign_up = true
auto_login = false
client_id = CLIENT_ID
client_secret = CLIENT_SECRET
scopes = openid email profile
auth_url = https://accounts.google.com/o/oauth2/v2/auth
token_url = https://oauth2.googleapis.com/token
api_url = https://openidconnect.googleapis.com/v1/userinfo
allowed_domains = mycompany.com mycompany.org
hosted_domain = mycompany.com
use_pkce = true

You may have to set the root_url option of [server] for the callback URL to be correct. For example, in case you are serving Grafana behind a proxy.

Restart the Grafana backend. You should now see a Google login button on the login page. You can now login or sign up with your Google accounts. The allowed_domains option is optional, and domains were separated by space.

You may allow users to sign-up via Google authentication by setting the allow_sign_up option to true. When this option is set to true, any user successfully authenticating via Google authentication will be automatically signed up.

You may specify a domain to be passed as hd query parameter accepted by Google’s OAuth 2.0 authentication API. Refer to Google’s OAuth documentation.

Note
Since Grafana 10.3.0, the hd parameter retrieved from Google ID token is also used to determine the user’s hosted domain. The Google Oauth allowed_domains configuration option is used to restrict access to users from a specific domain. If the allowed_domains configuration option is set, the hd parameter from the Google ID token must match the allowed_domains configuration option. If the hd parameter from the Google ID token does not match the allowed_domains configuration option, the user is denied access.

When an account does not belong to a google workspace, the hd claim will not be available.

This validation is enabled by default. To disable this validation, set the validate_hd configuration option to false. The allowed_domains configuration option will use the email claim to validate the domain.

PKCE

Note
You can disable PKCE in Grafana by setting use_pkce to false in the[auth.google] section.

Configure refresh token

By default, Grafana includes the access_type=offline parameter in the authorization request to request a refresh token.

Refresh token fetching and access token expiration check is enabled by default for the Google provider since Grafana v10.1.0. If you would like to disable access token expiration check then set the use_refresh_token configuration value to false.

Note
The accessTokenExpirationCheck feature toggle has been removed in Grafana v10.3.0 and the use_refresh_token configuration value will be used instead for configuring refresh token fetching and access token expiration check.

Configure JWT ID token validation

To enable JWT ID token validation:

Set validate_id_token to true in the [auth.google] section of the Grafana configuration file.
Configure jwk_set_url with the URL of Google’s JSON Web Key Set (JWKS) endpoint. This endpoint provides the public keys used to verify JWT signatures.

For Google, the JWKS endpoint is: https://www.googleapis.com/oauth2/v3/certs

Example configuration:

[auth.google]
enabled = true
validate_id_token = true
jwk_set_url = https://www.googleapis.com/oauth2/v3/certs
client_id = <client id>
client_secret = <client secret>
scopes = openid email profile

Note
When JWT validation is enabled, Grafana caches the JWKS keys to improve performance. The cache respects the Cache-Control header from the JWKS endpoint response. If no cache expiration is specified, keys are cached for 5 minutes by default.

Caution
If validate_id_token is set to true, you must configure jwk_set_url. Authentication will fail if the JWK Set URL is not provided or if the ID token signature cannot be verified.

Set the auto_login option to true to attempt log in automatically, skipping the login screen. This setting is ignored if multiple auth providers are configured to use auto login.

auto_login = true

Configure team synchronization

Note
Available in Grafana Enterprise and Grafana Cloud.

With team sync, you can easily add users to teams by utilizing their Google groups. To set up team sync for Google OAuth, refer to the following example.

To set up team sync for Google OAuth:

Enable the Google Cloud Identity API on your organization’s dashboard.
Add the https://www.googleapis.com/auth/cloud-identity.groups.readonly scope to your Grafana [auth.google] configuration:

Example:
ini
```
[auth.google]
# ..
scopes = openid email profile https://www.googleapis.com/auth/cloud-identity.groups.readonly
```
Configure team sync in your Grafana team’s External group sync tab. The external group ID for a Google group is the group’s email address, such as dev@grafana.com.

To learn more about Team Sync, refer to Configure Team Sync.

Configure allowed groups

To limit access to authenticated users that are members of one or more groups, set allowed_groups to a comma or space separated list of groups.

Google groups are referenced by the group email key. For example, developers@google.com.

Note
Add the https://www.googleapis.com/auth/cloud-identity.groups.readonly scope to your Grafana [auth.google] scopes configuration to retrieve groups.

Configure role mapping

Unless the skip_org_role_sync option is enabled, the user’s role will be set to the role mapped from Google upon user login. If no mapping is set the default instance role is used.

To ease configuration of a proper JMESPath expression, go to JMESPath to test and evaluate expressions with custom payloads.

Note
By default the skip_org_role_sync option is enabled. The skip_org_role_sync option defaults to false in Grafana v10.3.0 and later versions.

Role mapping examples

This section includes examples of JMESPath expressions used for role mapping.

Org roles mapping example

The Google integration uses the external users’ groups in the org_mapping configuration to map organizations and roles based on their Google group membership.

In this example, the user has been granted the role of a Viewer in the org_foo organization, and the role of an Editor in the org_bar and org_baz orgs.

The external user is part of the following Google groups: group-1 and group-2.

Config:

org_mapping = group-1:org_foo:Viewer group-2:org_bar:Editor *:org_baz:Editor

Map roles using user information from OAuth token

In this example, the user with email admin@company.com has been granted the Admin role. All other users are granted the Viewer role.

role_attribute_path = email=='admin@company.com' && 'Admin' || 'Viewer'
skip_org_role_sync = false

Map roles using groups

In this example, the user from Google group ’example-group@google.com’ have been granted the Editor role. All other users are granted the Viewer role.

role_attribute_path = contains(groups[*], 'example-group@google.com') && 'Editor' || 'Viewer'
skip_org_role_sync = false

Note
Add the https://www.googleapis.com/auth/cloud-identity.groups.readonly scope to your Grafana [auth.google] scopes configuration to retrieve groups.

Map server administrator role

In this example, the user with email admin@company.com is granted the Admin organization role as well as the Grafana server admin role. All other users are granted the Viewer role.

allow_assign_grafana_admin = true
skip_org_role_sync = false
role_attribute_path = email=='admin@company.com' && 'GrafanaAdmin' || 'Viewer'

Map one role to all users

In this example, all users are assigned the Viewer role regardless of the user information received from the identity provider.

role_attribute_path = "'Viewer'"
skip_org_role_sync = false

Configuration options

The following table outlines the various Google OAuth configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana. For more information, refer to Override configuration with environment variables.

Setting	Required	Supported on Cloud	Description	Default
`enabled`	No	Yes	Enables Google authentication.	`false`
`name`	No	Yes	Name that refers to the Google authentication from the Grafana user interface.	`Google`
`icon`	No	Yes	Icon used for the Google authentication in the Grafana user interface.	`google`
`client_id`	Yes	Yes	Client ID of the App.
`client_secret`	Yes	Yes	Client secret of the App.
`auth_url`	Yes	Yes	Authorization endpoint of the Google OAuth provider.	`https://accounts.google.com/o/oauth2/v2/auth`
`token_url`	Yes	Yes	Endpoint used to obtain the OAuth2 access token.	`https://oauth2.googleapis.com/token`
`api_url`	Yes	Yes	Endpoint used to obtain user information compatible with OpenID UserInfo.	`https://openidconnect.googleapis.com/v1/userinfo`
`auth_style`	No	Yes	Name of the OAuth2 AuthStyle to be used when ID token is requested from OAuth2 provider. It determines how `client_id` and `client_secret` are sent to Oauth2 provider. Available values are `AutoDetect`, `InParams` and `InHeader`.	`AutoDetect`
`scopes`	No	Yes	List of comma- or space-separated OAuth2 scopes.	`openid email profile`
`allow_sign_up`	No	Yes	Controls Grafana user creation through the Google login. Only existing Grafana users can log in with Google if set to `false`.	`true`
`auto_login`	No	Yes	Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login.	`false`
`login_prompt`	No	Yes	Indicates the type of user interaction when the user logs in with Google. Available values are `login`, `consent` and `select_account`.
`hosted_domain`	No	Yes	Specifies the domain to restrict access to users from that domain. This value is appended to the authorization request using the `hd` parameter.
`validate_hd`	No	Yes	Set to `false` to disable the validation of the `hd` parameter from the Google ID token. For more informatiion, refer to Enable Google OAuth in Grafana.	`true`
`role_attribute_strict`	No	Yes	Set to `true` to deny user login if the Grafana org role cannot be extracted using `role_attribute_path` or `org_mapping`. For more information on user role mapping, refer to Configure role mapping.	`false`
`org_attribute_path`	No	No	JMESPath expression to use for Grafana org to role lookup. Grafana will first evaluate the expression using the OAuth2 ID token. If no value is returned, the expression will be evaluated using the user information obtained from the UserInfo endpoint. The result of the evaluation will be mapped to org roles based on `org_mapping`. For more information on org to role mapping, refer to Org roles mapping example.
`org_mapping`	No	No	List of comma- or space-separated `<ExternalOrgName>:<OrgIdOrName>:<Role>` mappings. Value can be `*` meaning “All users”. Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. For more information on external organization to role mapping, refer to Org roles mapping example.
`allow_assign_grafana_admin`	No	No	Set to `true` to automatically sync the Grafana server administrator role. When enabled, if the Google user’s App role is `GrafanaAdmin`, Grafana grants the user server administrator privileges and the organization administrator role. If disabled, the user will only receive the organization administrator role. For more details on user role mapping, refer to Map roles.	`false`
`skip_org_role_sync`	No	Yes	Set to `true` to stop automatically syncing user roles. This will allow you to set organization roles for your users from within Grafana manually.	`false`
`allowed_groups`	No	Yes	List of comma- or space-separated groups. The user should be a member of at least one group to log in. If you configure `allowed_groups`, you must also configure Google to include the `groups` claim following Configure allowed groups.
`allowed_organizations`	No	Yes	List of comma- or space-separated Azure tenant identifiers. The user should be a member of at least one tenant to log in.
`allowed_domains`	No	Yes	List of comma- or space-separated domains. The user should belong to at least one domain to log in.
`tls_skip_verify_insecure`	No	No	If set to `true`, the client accepts any certificate presented by the server and any host name in that certificate. You should only use this for testing, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks.	`false`
`tls_client_cert`	No	No	The path to the certificate.
`tls_client_key`	No	No	The path to the key.
`tls_client_ca`	No	No	The path to the trusted certificate authority list.
`use_pkce`	No	Yes	Set to `true` to use Proof Key for Code Exchange (PKCE). Grafana uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier.	`true`
`use_refresh_token`	No	Yes	Enables the use of refresh tokens and checks for access token expiration. When enabled, Grafana automatically adds the `promp=consent` and `access_type=offline` parameters to the authorization request.	`true`
`validate_id_token`	No	Yes	If enabled, Grafana will validate the JWT signature of ID tokens using the JWKS endpoint. This enhances security by ensuring tokens are authentic and have not been tampered with.	`false`
`jwk_set_url`	No	Yes	URL of the JSON Web Key Set (JWKS) endpoint used to verify JWT ID token signatures. Required when ID token validation is enabled. For Google, use `https://www.googleapis.com/oauth2/v3/certs`.
`signout_redirect_url`	No	Yes	URL to redirect to after the user logs out.

Configure Grafana Cloud authentication

Fri, 03 Apr 2026 19:43:06 +0000

Configure Grafana Cloud authentication

To enable Grafana Cloud as the Identity Provider for a Grafana instance, generate a client ID and client secret and apply the configuration to Grafana.

Create Grafana Cloud OAuth Client Credentials

To use Grafana Cloud authentication:

Log in to Grafana Cloud.
To create an OAuth client, locate your organization and click OAuth Clients.
Click Add OAuth Client Application.
Add the name and URL of your running Grafana instance.
Click Add OAuth Client.
Copy the client ID and client secret or the configuration that has been generated.

The following snippet shows an example configuration:

[auth.grafana_com]
enabled = true
allow_sign_up = true
auto_login = false
client_id = 450bc21c10dc2194879d
client_secret = eyJ0Ijoib2F1dGgyYyIhlmlkIjoiNzUwYmMzM2MxMGRjMjE6NDh3OWQiLCJ2IjoiZmI1YzVlYmIwYzFmN2ZhYzZmNjIwOGI1NmVkYTRlNWYxMzgwM2NkMiJ9
scopes = user:email
allowed_organizations = sampleorganization
enabled = true

Set auto_login option to true to attempt login automatically, skipping the login screen. This setting is ignored if multiple auth providers are configured to use auto login.

auto_login = true

Skip organization role sync

If a user signs in with their Grafana Cloud credentials, their assigned org role overrides the role defined in the Grafana instance. To prevent Grafana Cloud roles from synchronizing, set skip_org_role_sync to true. This is useful if you want to manage the organization roles for your users from within Grafana.

[auth.grafana_com]
# ..
# prevents the sync of org roles from Grafana.com
skip_org_role_sync = true

Configure Keycloak OAuth2 authentication

Fri, 03 Apr 2026 19:43:06 +0000

Configure Keycloak OAuth2 authentication

Keycloak OAuth2 authentication allows users to log in to Grafana using their Keycloak credentials. This guide explains how to set up Keycloak as an authentication provider in Grafana.

Refer to Generic OAuth authentication for extra configuration options available for this provider.

Note
If you use the same email address in Keycloak as in other authentication providers (such as Grafana.com), you need to do additional configuration to ensure that the users are matched correctly. Please refer to the Using the same email address to login with different identity providers documentation for more information.

You may have to set the root_url option of [server] for the callback URL to be correct. For example in case you are serving Grafana behind a proxy.

Example config:

[auth.generic_oauth]
enabled = true
name = Keycloak-OAuth
allow_sign_up = true
client_id = YOUR_APP_CLIENT_ID
client_secret = YOUR_APP_CLIENT_SECRET
scopes = openid email profile offline_access roles
email_attribute_path = email
login_attribute_path = username
name_attribute_path = full_name
auth_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/auth
token_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/token
api_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/userinfo
role_attribute_path = contains(roles[*], 'admin') && 'Admin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'

As an example, <PROVIDER_DOMAIN> can be keycloak-demo.grafana.org and <REALM_NAME> can be grafana.

To configure the kc_idp_hint parameter for Keycloak, you need to change the auth_url configuration to include the kc_idp_hint parameter. For example if you want to hint the Google identity provider:

auth_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/auth?kc_idp_hint=google

Note
api_url is not required if the id_token contains all the necessary user information and can add latency to the login process. It is useful as a fallback or if the user has more than 150 group memberships.

Keycloak configuration

Create a client in Keycloak with the following settings:

Client ID: grafana-oauth
Enabled: ON
Client Protocol: openid-connect
Access Type: confidential
Standard Flow Enabled: ON
Implicit Flow Enabled: OFF
Direct Access Grants Enabled: ON
Root URL: <grafana_root_url>
Valid Redirect URIs: <grafana_root_url>/login/generic_oauth
Web Origins: <grafana_root_url>
Admin URL: <grafana_root_url>
Base URL: <grafana_root_url>

As an example, <grafana_root_url> can be https://play.grafana.org. Non-listed configuration options can be left at their default values.

In the client scopes configuration, Assigned Default Client Scopes should match:

email
offline_access
profile
roles

Warning
These scopes do not add group claims to the id_token. Without group claims, teamsync will not work. Teamsync is covered further down in this document.

For role mapping to work with the example configuration above, you need to create the following roles and assign them to users:

admin
editor
viewer

Team sync

Note
Available in Grafana Enterprise and Grafana Cloud.

Team Sync is a feature that allows you to map groups from your identity provider to Grafana teams. This is useful if you want to give your users access to specific dashboards or folders based on their group membership.

To enable teamsync, you need to add a groups mapper to the client configuration in Keycloak. This will add the groups claim to the id_token. You can then use the groups claim to map groups to teams in Grafana.

In the client configuration, head to Mappers and create a mapper with the following settings:

Name: Group Mapper
Mapper Type: Group Membership
Token Claim Name: groups
Full group path: OFF
Add to ID token: ON
Add to access token: OFF
Add to userinfo: ON

In Grafana’s configuration add the following option:

[auth.generic_oauth]
groups_attribute_path = groups

If you use nested groups containing special characters such as quotes or colons, the JMESPath parser can perform a harmless reverse function so Grafana can properly evaluate nested groups. The following example shows a parent group named Global with nested group department that contains a list of groups:

[auth.generic_oauth]
groups_attribute_path = reverse("Global:department")

Enable Single Logout

To enable Single Logout, you need to add the following option to the configuration of Grafana:

[auth.generic_oauth]
signout_redirect_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/logout?post_logout_redirect_uri=https%3A%2F%2F<GRAFANA_DOMAIN>%2Flogin

As an example, <PROVIDER_DOMAIN> can be keycloak-demo.grafana.org, <REALM_NAME> can be grafana and <GRAFANA_DOMAIN> can be play.grafana.org.

Note
Grafana supports ID token hints for single logout. Grafana automatically adds the id_token_hint parameter to the logout request if it detects OAuth as the authentication method.

Allow assigning Grafana Admin

If the application role received by Grafana is GrafanaAdmin , Grafana grants the user server administrator privileges.

This is useful if you want to grant server administrator privileges to a subset of users. Grafana also assigns the user the Admin role of the default organization.

role_attribute_path = contains(roles[*], 'grafanaadmin') && 'GrafanaAdmin' || contains(roles[*], 'admin') && 'Admin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'
allow_assign_grafana_admin = true

Configure refresh token

To enable a refresh token for Keycloak, do the following:

Extend the scopes in [auth.generic_oauth] with offline_access.
Add use_refresh_token = true to [auth.generic_oauth] configuration.

Multiple providers with Keycloak in Grafana

Fri, 03 Apr 2026 19:43:06 +0000

Multiple providers with Keycloak in Grafana

While Grafana offers a variety of authentication providers, you can only configure one provider of one type at a time. However, you can configure multiple providers of the same type with the help of Keycloak.

This guide explains how to set up multiple providers of the same type with Keycloak as an authentication provider in Grafana.

The idea is to set up multiple OIDC providers in Keycloak with different tenants and configure Grafana to use the same Keycloak instance as the authentication provider.

Entra ID configuration

For Entra ID, repeat the following steps for each tenant you want to set up in Keycloak.

Overview

Register your application in Entra ID.
Give access to the application to the users in the tenant.
Create credentials for the application.
Configure the application in Keycloak.
Configure Grafana to use Keycloak.

Register your application in Entra ID

Registering an application in Entra ID is a one-time process. You can follow the steps in the Entra ID documentation to register your application.

Go to the Azure portal and ensure you are using the correct tenant also known as directory.
Search for App Registrations and click on New registration.
Fill in the details for the application and click Register. You’ll be redirected to the application’s overview page.

Give access to the application to the users in the tenant

Assigning the correct access to users ensures only intended users or groups have access to the application.

Search for Enterprise Applications and look for the application you just created in the previous step.
Under the Manage section, click on Users and groups.
Click on Add user/group and add the users or groups that should have access to the application.

Create credentials for the application

To authenticate with Entra ID, the Keycloak application needs a client ID and client secret.

Search for App Registrations and look for the application ypu just created.
Click on Certificates & Secrets.
Click on New client secret and fill in the details. Make sure to copy the secret value as it will not be shown again.

Configure the application in Keycloak

Go to the Keycloak admin console.
Go to the Realm where you want to configure the Entra ID tenant.
Go to the Identity Providers section and click on Add provider.
Select OpenID Connect v1.0.
1. Select a unique Alias and Display name.
2. Copy the Redirect URI.
3. Back in Azure Portal, go to the application’s Authentication section.
4. Add a new platform and select Web.
5. Paste the Redirect URI from Keycloak.
6. Save the changes.
7. Navigate to the Azure Application overview and look for the Endpoints tab.
8. Copy the OpenID Connect metadata document URL.
9. Head back to Keycloak and paste the URL in the Discovery endpoint field.
10. Navigate to the Azure application overview and look for the Application (client) ID.
11. Copy the Application ID and paste it in the Client ID field in Keycloak.
12. Paste the client secret you created in the previous step in the Client secret field.
13. Click Add.

Note
Up to this point, you have created an App Registration in Entra ID, assigned users to the application, created credentials for the application, and configured the application in Keycloak. In the Keycloak Client’s section, the client with ID account Home URL can be used to test the configuration. This will open a new tab where you can login into the correct Keycloak realm with the Entra ID tenant you just configured.

Repeat this steps, for every Entra ID tenant you want to configure in Keycloak.

Configure Grafana to use Keycloak

Now that the Entra ID tenants are configured in Keycloak, you can configure Grafana to use Keycloak as the authentication provider.

Refer to the Keycloak documentation to configure Grafana to use Keycloak as the authentication provider.

Configure Okta OIDC authentication

Fri, 03 Apr 2026 19:43:06 +0000

Configure Okta OIDC authentication

Note
If Users use the same email address in Okta that they use with other authentication providers (such as Grafana.com), you need to do additional configuration to ensure that the users are matched correctly. Please refer to the Using the same email address to login with different identity providers documentation for more information.

Before you begin

To follow this guide, ensure you have permissions in your Okta workspace to create an OIDC app.

Create an Okta app

From the Okta Admin Console, select Create App Integration from the Applications menu.
For Sign-in method, select OIDC - OpenID Connect.
For Application type, select Web Application and click Next.
Configure New Web App Integration Operations:
- App integration name: Choose a name for the app.
- Logo (optional): Add a logo.
- Grant type: Select Authorization Code and Refresh Token.
- Sign-in redirect URIs: Replace the default setting with the Grafana Cloud Okta path, replacing <YOUR_ORG> with the name of your Grafana organization: https://<YOUR_ORG>.grafana.net/login/okta. For on-premises installation, use the Grafana server URL: http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/okta.
- Sign-out redirect URIs (optional): Replace the default setting with the Grafana Cloud Okta path, replacing <YOUR_ORG> with the name of your Grafana organization: https://<YOUR_ORG>.grafana.net/logout. For on-premises installation, use the Grafana server URL: http://<my_grafana_server_name_or_ip>:<grafana_server_port>/logout.
- Base URIs (optional): Add any base URIs
- Controlled access: Select whether to assign the app integration to everyone in your organization, or only selected groups. You can assign this option after you create the app.
Make a note of the following:
- ClientID
- Client Secret
- Auth URL For example: https://<TENANT_ID>.okta.com/oauth2/v1/authorize
- Token URL For example: https://<TENANT_ID>.okta.com/oauth2/v1/token
- API URL For example: https://<TENANT_ID>.okta.com/oauth2/v1/userinfo

Configure Okta to Grafana role mapping

In the Okta Admin Console, select Directory > Profile Editor.
Select the Okta Application Profile you created previously (the default name for this is <App name> User).
Select Add Attribute and fill in the following fields:
- Data Type: string
- Display Name: Meaningful name. For example, Grafana Role.
- Variable Name: Meaningful name. For example, grafana_role.
- Description (optional): A description of the role.
- Enum: Select Define enumerated list of values and add the following:
  - Display Name: Admin Value: Admin
  - Display Name: Editor Value: Editor
  - Display Name: Viewer Value: Viewer
The remaining attributes are optional and can be set as needed.
Click Save.
(Optional) You can add the role attribute to the default User profile. To do this, please follow the steps in the Optional: Add the role attribute to the User (default) Okta profile section.

Configure Groups claim

In the Okta Admin Console, select Application > Applications.
Select the OpenID Connect application you created.
Go to the Sign On tab and click Edit in the OpenID Connect ID Token section.
In the Group claim type section, select Filter.
In the Group claim filter section, leave the default name groups (or add it if the box is empty), then select Matches regex and add the following regex: .*.
Click Save.
Click the Back to applications link at the top of the page.
From the More button dropdown menu, click Refresh Application Data.
Include the groups scope in the Scopes field in Grafana of the Okta integration. For Terraform or in the Grafana configuration file, include the groups scope in scopes field.

Note
If you configure the groups claim differently, ensure that the groups claim is a string array.

Optional: Add the role attribute to the User (default) Okta profile

If you want to configure the role for all users in the Okta directory, you can add the role attribute to the User (default) Okta profile.

Return to the Directory section and select Profile Editor.
Select the User (default) Okta profile, and click Add Attribute.
Set all of the attributes in the same way you did in Step 3.
Select Add Mapping to add your new attributes. For example, user.grafana_role -> grafana_role.
To add a role to a user, select the user from the Directory, and click Profile -> Edit.
Select an option from your new attribute and click Save.
Update the Okta integration by setting the Role attribute path (role_attribute_path in Terraform and config file) to <YOUR_ROLE_VARIABLE>. For example: role_attribute_path = grafana_role (using the configuration).

Configure Okta authentication client using the Grafana UI

As a Grafana Admin, you can configure Okta OAuth2 client from within Grafana using the Okta UI. To do this, navigate to Administration > Authentication > Okta page and fill in the form. If you have a current configuration in the Grafana configuration file then the form will be pre-populated with those values otherwise the form will contain default values.

After you have filled in the form, click Save. If the save was successful, Grafana will apply the new configurations.

Note
If you run Grafana in high availability mode, configuration changes may not get applied to all Grafana instances immediately. You may need to wait a few minutes for the configuration to propagate to all Grafana instances.

Refer to configuration options for more information.

Configure Okta authentication client using the Terraform provider

resource "grafana_sso_settings" "okta_sso_settings" {
  provider_name = "okta"
  oauth2_settings {
    name                  = "Okta"
    auth_url              = "https://<okta tenant id>.okta.com/oauth2/v1/authorize"
    token_url             = "https://<okta tenant id>.okta.com/oauth2/v1/token"
    api_url               = "https://<okta tenant id>.okta.com/oauth2/v1/userinfo"
    client_id             = "CLIENT_ID"
    client_secret         = "CLIENT_SECRET"
    allow_sign_up         = true
    auto_login            = false
    scopes                = "openid profile email offline_access"
    role_attribute_path   = "contains(groups[*], 'Example::DevOps') && 'Admin' || 'None'"
    role_attribute_strict = true
    allowed_groups        = "Example::DevOps,Example::Dev,Example::QA"
  }
}

Go to Terraform Registry for a complete reference on using the grafana_sso_settings resource.

Configure Okta authentication client using the Grafana configuration file

Ensure that you have access to the Grafana configuration file.

Steps

To integrate your Okta OIDC provider with Grafana using our Okta OIDC integration, follow these steps:

Follow the Create an Okta app steps to create an OIDC app in Okta.

Refer to the following table to update field values located in the [auth.okta] section of the Grafana configuration file:

Field	Description
`client_id`	These values must match the client ID from your Okta OIDC app.
`auth_url`	The authorization endpoint of your OIDC provider. `https://<okta-tenant-id>.okta.com/oauth2/v1/authorize`
`token_url`	The token endpoint of your Okta OIDC provider. `https://<okta-tenant-id>.okta.com/oauth2/v1/token`
`api_url`	The user information endpoint of your Okta OIDC provider. `https://<tenant-id>.okta.com/oauth2/v1/userinfo`
`enabled`	Enables Okta OIDC authentication. Set this value to `true`.

Review the list of other Okta OIDC configuration options and complete them as necessary.
Optional: Configure a refresh token.
Configure role mapping.
Optional: Configure team synchronization.
Restart Grafana.

You should now see a Okta OIDC login button on the login page and be able to log in or sign up with your OIDC provider.

The following is an example of a minimally functioning integration when configured with the instructions above:

[auth.okta]
name = Okta
icon = okta
enabled = true
allow_sign_up = true
client_id = <client id>
scopes = openid profile email offline_access
auth_url = https://<okta tenant id>.okta.com/oauth2/v1/authorize
token_url = https://<okta tenant id>.okta.com/oauth2/v1/token
api_url = https://<okta tenant id>.okta.com/oauth2/v1/userinfo
role_attribute_path = grafana_role
role_attribute_strict = true
allowed_groups = "Example::DevOps" "Example::Dev" "Example::QA"

Configure a refresh token

If a refresh token doesn’t exist, Grafana logs the user out of the system after the access token has expired.

To enable the Refresh Token head over the Okta application settings and:

Under General tab, find the General Settings section.
Within the Grant Type options, enable the Refresh Token checkbox.

At the configuration file, extend the scopes in [auth.okta] section with offline_access and set use_refresh_token to true.

Configure JWT ID token validation

To enable JWT ID token validation:

Set validate_id_token to true in the [auth.okta] section of the Grafana configuration file.
Configure jwk_set_url with the URL of your Okta tenant’s JSON Web Key Set (JWKS) endpoint. This endpoint provides the public keys used to verify JWT signatures.

For Okta, the JWKS endpoint is: https://<tenant-id>.okta.com/oauth2/v1/keys

Example configuration:

[auth.okta]
enabled = true
validate_id_token = true
jwk_set_url = https://<tenant-id>.okta.com/oauth2/v1/keys
client_id = <client id>
client_secret = <client secret>
scopes = openid profile email groups

Note
When JWT validation is enabled, Grafana caches the JWKS keys to improve performance. The cache respects the Cache-Control header from the JWKS endpoint response. If no cache expiration is specified, keys are cached for 5 minutes by default.

Caution
If validate_id_token is set to true, you must configure jwk_set_url. Authentication will fail if the JWK Set URL is not provided or if the ID token signature cannot be verified.

Configure role mapping

Note
Unless skip_org_role_sync option is enabled, the user’s role will be set to the role retrieved from the auth provider upon user login.

The user’s role is retrieved using a JMESPath expression from the role_attribute_path configuration option against the api_url (/userinfo OIDC endpoint) endpoint payload.

To allow mapping Grafana server administrator role, use the allow_assign_grafana_admin configuration option. Refer to configuration options for more information.

In Create an Okta app, you created a custom attribute in Okta to store the role. You can use this attribute to map the role to a Grafana role by setting the role_attribute_path configuration option to the custom attribute name: role_attribute_path = grafana_role.

If you want to map the role based on the user’s group, you can use the groups attribute from the user info endpoint. An example of this is role_attribute_path = contains(groups[*], 'Example::DevOps') && 'Admin' || 'None'. You can find more examples of JMESPath expressions on the Generic OAuth page for JMESPath examples.

To learn about adding custom claims to the user info in Okta, refer to add custom claims.

Org roles mapping example

Note
Available in self-managed Grafana installations.

In this example, the org_mapping uses the groups attribute as the source (org_attribute_path) to map the current user to different organizations and roles. The user has been granted the role of a Viewer in the org_foo org if they are a member of the Group 1 group, the role of an Editor in the org_bar org if they are a member of the Group 2 group, and the role of an Editor in the org_baz(OrgID=3) org.

Config:

org_attribute_path = groups
org_mapping = ["Group 1:org_foo:Viewer", "Group 2:org_bar:Editor", "*:3:Editor"]

Configure team synchronization

Note
Available in Grafana Enterprise and Grafana Cloud.

By using Team Sync, you can link your Okta groups to teams within Grafana. This will automatically assign users to the appropriate teams.

Map your Okta groups to teams in Grafana so that your users will automatically be added to the correct teams.

Okta groups can be referenced by group names, like Admins or Editors.

To learn more about Team Sync, refer to Configure Team Sync.

Configuration options

The following table outlines the various Okta OIDC configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana. For more information, refer to Override configuration with environment variables.

Note
If the configuration option requires a JMESPath expression that includes a colon, enclose the entire expression in quotes to prevent parsing errors. For example role_attribute_path: "role:view"

Setting	Required	Supported on Cloud	Description	Default
`enabled`	No	Yes	Enables Okta OIDC authentication.	`false`
`name`	No	Yes	Name that refers to the Okta OIDC authentication from the Grafana user interface.	`Okta`
`icon`	No	Yes	Icon used for the Okta OIDC authentication in the Grafana user interface.	`okta`
`client_id`	Yes	Yes	Client ID provided by your Okta OIDC app.
`client_secret`	Yes	Yes	Client secret provided by your Okta OIDC app.
`auth_url`	Yes	Yes	Authorization endpoint of your Okta OIDC provider.
`token_url`	Yes	Yes	Endpoint used to obtain the Okta OIDC access token.
`api_url`	Yes	Yes	Endpoint used to obtain user information.
`scopes`	No	Yes	List of comma- or space-separated Okta OIDC scopes.	`openid profile email groups`
`allow_sign_up`	No	Yes	Controls Grafana user creation through the Okta OIDC login. Only existing Grafana users can log in with Okta OIDC if set to `false`.	`true`
`auto_login`	No	Yes	Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login.	`false`
`role_attribute_path`	No	Yes	JMESPath expression to use for Grafana role lookup. Grafana will first evaluate the expression using the Okta OIDC ID token. If no role is found, the expression will be evaluated using the user information obtained from the UserInfo endpoint. The result of the evaluation should be a valid Grafana role (`None`, `Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to Configure role mapping.
`role_attribute_strict`	No	Yes	Set to `true` to deny user login if the Grafana org role cannot be extracted using `role_attribute_path` or `org_mapping`. For more information on user role mapping, refer to Configure role mapping.	`false`
`org_attribute_path`	No	No	JMESPath expression to use for Grafana org to role lookup. The result of the evaluation will be mapped to org roles based on `org_mapping`. For more information on org to role mapping, refer to Org roles mapping example.
`org_mapping`	No	No	List of comma- or space-separated `<ExternalOrgName>:<OrgIdOrName>:<Role>` mappings. Value can be `*` meaning “All users”. Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. For more information on external organization to role mapping, refer to Org roles mapping example.
`skip_org_role_sync`	No	Yes	Set to `true` to stop automatically syncing user roles. This will allow you to set organization roles for your users from within Grafana manually.	`false`
`allowed_groups`	No	Yes	List of comma- or space-separated groups. The user should be a member of at least one group to log in.
`allowed_domains`	No	Yes	List of comma- or space-separated domains. The user should belong to at least one domain to log in.
`use_pkce`	No	Yes	Set to `true` to use Proof Key for Code Exchange (PKCE). Grafana uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier.	`true`
`use_refresh_token`	No	Yes	Set to `true` to use refresh token and check access token expiration.	`false`
`validate_id_token`	No	Yes	If enabled, Grafana will validate the JWT signature of ID tokens using the JWKS endpoint. This enhances security by ensuring tokens are authentic and have not been tampered with.	`false`
`jwk_set_url`	No	Yes	URL of the JSON Web Key Set (JWKS) endpoint used to verify JWT ID token signatures. Required when ID token validation is enabled. For Okta, use `https://<tenant-id>.okta.com/oauth2/v1/keys`.
`signout_redirect_url`	No	Yes	URL to redirect to after the user logs out.

Configure auth proxy authentication

Fri, 03 Apr 2026 19:43:06 +0000

Configure auth proxy authentication

You can configure Grafana to let a HTTP reverse proxy handle authentication. Popular web servers have a very extensive list of pluggable authentication modules, and any of them can be used with the AuthProxy feature. Below we detail the configuration options for auth proxy.

[auth.proxy]
# Defaults to false, but set to true to enable this feature
enabled = true
# HTTP Header name that will contain the username or email
header_name = X-WEBAUTH-USER
# HTTP Header property, defaults to `username` but can also be `email`
header_property = username
# Set to `true` to enable auto sign up of users who do not exist in Grafana DB. Defaults to `true`.
auto_sign_up = true
# Define cache time to live in minutes
# If combined with Grafana LDAP integration it is also the sync interval
# Set to 0 to always fetch and sync the latest user data
sync_ttl = 15
# Limit where auth proxy requests come from by configuring a list of IP addresses.
# This can be used to prevent users spoofing the X-WEBAUTH-USER header.
# Example `whitelist = 192.168.1.1, 192.168.1.0/24, 2001::23, 2001::0/120`
whitelist =
# Optionally define more headers to sync other user attributes
# Example `headers = Name:X-WEBAUTH-NAME Role:X-WEBAUTH-ROLE Email:X-WEBAUTH-EMAIL Groups:X-WEBAUTH-GROUPS`
headers =
# Non-ASCII strings in header values are encoded using quoted-printable encoding
;headers_encoded = false
# Check out docs on this for more details on the below setting
enable_login_token = false

Interacting with Grafana’s AuthProxy via curl

curl -H "X-WEBAUTH-USER: admin"  http://localhost:3000/api/users
[
    {
        "id":1,
        "name":"",
        "login":"admin",
        "email":"admin@localhost",
        "isAdmin":true
    }
]

We can then send a second request to the /api/user method which will return the details of the logged in user. We will use this request to show how Grafana automatically adds the new user we specify to the system. Here we create a new user called “anthony”.

curl -H "X-WEBAUTH-USER: anthony" http://localhost:3000/api/user
{
    "email":"anthony",
    "name":"",
    "login":"anthony",
    "theme":"",
    "orgId":1,
    "isGrafanaAdmin":false
}

Making Apache’s auth work together with Grafana’s AuthProxy

I’ll demonstrate how to use Apache for authenticating users. In this example we use BasicAuth with Apache’s text file based authentication handler, i.e. htpasswd files. However, any available Apache authentication capabilities could be used.

Apache BasicAuth

In this example we use Apache as a reverse proxy in front of Grafana. Apache handles the Authentication of users before forwarding requests to the Grafana backend service.

Apache configuration

    <VirtualHost *:80>
        ServerAdmin webmaster@authproxy
        ServerName authproxy
        ErrorLog "logs/authproxy-error_log"
        CustomLog "logs/authproxy-access_log" common

        <Proxy *>
            AuthType Basic
            AuthName GrafanaAuthProxy
            AuthBasicProvider file
            AuthUserFile /etc/apache2/grafana_htpasswd
            Require valid-user

            RewriteEngine On
            RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS]
            RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e"
        </Proxy>

        RequestHeader unset Authorization

        ProxyRequests Off
        ProxyPass / http://localhost:3000/
        ProxyPassReverse / http://localhost:3000/
    </VirtualHost>

The first four lines of the virtualhost configuration are standard, so we won’t go into detail on what they do.
We use a <proxy> configuration block for applying our authentication rules to every proxied request. These rules include requiring basic authentication where user:password credentials are stored in the /etc/apache2/grafana_htpasswd file. This file can be created with the htpasswd command.
- The next part of the configuration is the tricky part. We use Apache’s rewrite engine to create our X-WEBAUTH-USER header, populated with the authenticated user.
  - RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER}, NS]: This line is a little bit of magic. What it does, is for every request use the rewriteEngines look-ahead (LA-U) feature to determine what the REMOTE_USER variable would be set to after processing the request. Then assign the result to the variable PROXY_USER. This is necessary as the REMOTE_USER variable is not available to the RequestHeader function.
  - RequestHeader set X-WEBAUTH-USER “%{PROXY_USER}e”: With the authenticated username now stored in the PROXY_USER variable, we create a new HTTP request header that will be sent to our backend Grafana containing the username.
The RequestHeader unset Authorization removes the Authorization header from the HTTP request before it is forwarded to Grafana. This ensures that Grafana does not try to authenticate the user using these credentials (BasicAuth is a supported authentication handler in Grafana).
The last 3 lines are then just standard reverse proxy configuration to direct all authenticated requests to our Grafana server running on port 3000.

Full walkthrough using Docker.

For this example, we use the official Grafana Docker image available at Docker Hub.

Create a file grafana.ini with the following contents

[users]
allow_sign_up = false
auto_assign_org = true
auto_assign_org_role = Editor

[auth.proxy]
enabled = true
header_name = X-WEBAUTH-USER
header_property = username
auto_sign_up = true

Launch the Grafana container, using our custom grafana.ini to replace /etc/grafana/grafana.ini. We don’t expose any ports for this container as it will only be connected to by our Apache container.

docker run -i -v $(pwd)/grafana.ini:/etc/grafana/grafana.ini --name grafana grafana/grafana

Apache Container

For this example we use the official Apache docker image available at Docker Hub

Create a file named httpd.conf with the following contents

ServerRoot "/usr/local/apache2"
Listen 80
LoadModule mpm_event_module modules/mod_mpm_event.so
LoadModule authn_file_module modules/mod_authn_file.so
LoadModule authn_core_module modules/mod_authn_core.so
LoadModule authz_host_module modules/mod_authz_host.so
LoadModule authz_user_module modules/mod_authz_user.so
LoadModule authz_core_module modules/mod_authz_core.so
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule log_config_module modules/mod_log_config.so
LoadModule env_module modules/mod_env.so
LoadModule headers_module modules/mod_headers.so
LoadModule unixd_module modules/mod_unixd.so
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
<IfModule unixd_module>
User daemon
Group daemon
</IfModule>
ServerAdmin you@example.com
<Directory />
    AllowOverride none
    Require all denied
</Directory>
DocumentRoot "/usr/local/apache2/htdocs"
ErrorLog /proc/self/fd/2
LogLevel error
<IfModule log_config_module>
    LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
    LogFormat "%h %l %u %t \"%r\" %>s %b" common
    <IfModule logio_module>
    LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combinedio
    </IfModule>
    CustomLog /proc/self/fd/1 common
</IfModule>
<Proxy *>
    AuthType Basic
    AuthName GrafanaAuthProxy
    AuthBasicProvider file
    AuthUserFile /tmp/htpasswd
    Require valid-user
    RewriteEngine On
    RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS]
    RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e"
</Proxy>
RequestHeader unset Authorization
ProxyRequests Off
ProxyPass / http://grafana:3000/
ProxyPassReverse / http://grafana:3000/

Create a htpasswd file. We create a new user anthony with the password password
Bash
```
htpasswd -bc htpasswd anthony password
```
Launch the Apache HTTP server container using our custom httpd.conf and our htpasswd file. The container will listen on port 80, and we create a link to the grafana container so that this container can resolve the hostname grafana to the Grafana container’s IP address.
Bash
```
docker run -i -p 80:80 --link grafana:grafana -v $(pwd)/httpd.conf:/usr/local/apache2/conf/httpd.conf -v $(pwd)/htpasswd:/tmp/htpasswd httpd:2.4
```

Use grafana.

With our Grafana and Apache containers running, you can now connect to http://localhost/ and log in using the username and password we created in the htpasswd file.

Note
If the user is deleted from Grafana, the user will be not be able to login and resync until after the sync_ttl has expired.

Team Sync

Note
Available in Grafana Enterprise and to customers on select Grafana Cloud plans. For pricing information, visit pricing or contact our sales team.

With Team Sync, it’s possible to set up synchronization between teams in your authentication provider and Grafana. You can send Grafana values as part of an HTTP header and have Grafana map them to your team structure. This allows you to put users into specific teams automatically.

To support the feature, auth proxy allows optional headers to map additional user attributes. The specific attribute to support team sync is Groups.

# Optionally define more headers to sync other user attributes
headers = "Groups:X-WEBAUTH-GROUPS"

You use the X-WEBAUTH-GROUPS header to send the team information for each user. Specifically, the set of Grafana’s group IDs that the user belongs to.

First, we need to set up the mapping between your authentication provider and Grafana. Follow these instructions to add groups to a team within Grafana.

Once that’s done. You can verify your mappings by querying the API.

# First, inspect your teams and obtain the corresponding ID of the team we want to inspect the groups for.
curl -H "X-WEBAUTH-USER: admin" -H "X-WEBAUTH-GROUPS: lokiteamOnExternalSystem" http://localhost:3000/api/teams/search
{
  "totalCount": 2,
  "teams": [
    {
      "id": 1,
      "orgId": 1,
      "name": "Core",
      "email": "core@grafana.com",
      "avatarUrl": "/avatar/327a5353552d2dc3966e2e646908f540",
      "memberCount": 1,
      "permission": 0
    },
    {
      "id": 2,
      "orgId": 1,
      "name": "Loki",
      "email": "loki@grafana.com",
      "avatarUrl": "/avatar/102f937d5344d33fdb37b65d430f36ef",
      "memberCount": 0,
      "permission": 0
    }
  ],
  "page": 1,
  "perPage": 1000
}

# Then, query the groups for that particular team. In our case, the Loki team which has an ID of "2".
curl -H "X-WEBAUTH-USER: admin" -H "X-WEBAUTH-GROUPS: lokiteamOnExternalSystem" http://localhost:3000/api/teams/2/groups
[
  {
    "orgId": 1,
    "teamId": 2,
    "groupId": "lokiTeamOnExternalSystem"
  }
]

Finally, whenever Grafana receives a request with a header of X-WEBAUTH-GROUPS: lokiTeamOnExternalSystem, the user under authentication will be placed into the specified team. Placement in multiple teams is supported by using comma-separated values e.g. lokiTeamOnExternalSystem,CoreTeamOnExternalSystem.

curl -H "X-WEBAUTH-USER: leonard" -H "X-WEBAUTH-GROUPS: lokiteamOnExternalSystem" http://localhost:3000/dashboards/home
{
  "meta": {
    "isHome": true,
    "canSave": false,
    ...
}

With this, the user leonard will be automatically placed into the Loki team as part of Grafana authentication.

Note
An empty X-WEBAUTH-GROUPS or the absence of a groups header will remove the user from all teams.

Learn more about Team Sync

With enable_login_token set to true Grafana will, after successful auth proxy header validation, assign the user a login token and cookie. You only have to configure your auth proxy to provide headers for the /login route. Requests via other routes will be authenticated using the cookie.

Use the settings login_maximum_inactive_lifetime_duration and login_maximum_lifetime_duration under [auth] to control session lifetime.

Configure JWT authentication

Fri, 03 Apr 2026 19:43:06 +0000

Configure JWT authentication

You can configure Grafana to accept a JWT token provided in the HTTP header. The token is verified using any of the following:

PEM-encoded key file
JSON Web Key Set (JWKS) in a local file
JWKS provided by the configured JWKS endpoint

This method of authentication is useful for integrating with other systems that use JWKS but can’t directly integrate with Grafana or if you want to use pass-through authentication in an app embedding Grafana.

Note
Grafana does not currently support refresh tokens.

Enable JWT

To use JWT authentication:

Enable JWT in the main config file.
Specify the header name that contains a token.

[auth.jwt]
# By default, auth.jwt is disabled.
enabled = true

# HTTP header to look into to get a JWT token.
header_name = X-JWT-Assertion

To identify the user, some of the claims needs to be selected as a login info. The subject claim called "sub" is mandatory and needs to identify the principal that is the subject of the JWT.

Typically, the subject claim called "sub" would be used as a login but it might also be set to some application specific claim.

# [auth.jwt]
# ...

# Specify a claim to use as a username to sign in.
username_claim = sub

# Specify a claim to use as an email to sign in.
email_claim = sub

# auto-create users if they are not already matched
# auto_sign_up = true

If auto_sign_up is enabled, then the sub claim is used as the “external Auth ID”. The name claim is used as the user’s full name if it is present.

Additionally, if the login username or the email claims are nested inside the JWT structure, you can specify the path to the attributes using the username_attribute_path and email_attribute_path configuration options using the JMESPath syntax.

JWT structure example.

{
  "user": {
    "UID": "1234567890",
    "name": "John Doe",
    "username": "johndoe",
    "emails": ["personal@email.com", "professional@email.com"]
  }
}

# [auth.jwt]
# ...

# Specify a nested attribute to use as a username to sign in.
username_attribute_path = user.username # user's login is johndoe

# Specify a nested attribute to use as an email to sign in.
email_attribute_path = user.emails[1] # user's email is professional@email.com

Iframe Embedding

If you want to embed Grafana in an iframe while maintaining user identity and role checks, you can use JWT authentication to authenticate the iframe.

Note
For Grafana Cloud, or scenarios where verifying viewer identity is not required, embed shared dashboards.

In this scenario, you will need to configure Grafana to accept a JWT provided in the HTTP header and a reverse proxy should rewrite requests to the Grafana instance to include the JWT in the request’s headers.

Note
For embedding to work, you must enable allow_embedding in the security section. This setting is not available in Grafana Cloud.

In a scenario where it is not possible to rewrite the request headers you can use URL login instead.

url_login allows grafana to search for a JWT in the URL query parameter auth_token and use it as the authentication token.

Note
You need to enable JWT before setting this setting. Refer to Enabled JWT.

Warning
This can lead to JWTs being exposed in logs and possible session hijacking if the server is not using HTTP over TLS.

# [auth.jwt]
# ...
url_login = true # enable JWT authentication in the URL

An example of an URL for accessing grafana with JWT URL authentication is:

http://env.grafana.local/d/RciOKLR4z/board-identifier?orgId=1&kiosk&auth_token=eyJhbxxxxxxxxxxxxx

A sample repository using this authentication method is available at grafana-iframe-oauth-sample.

Signature verification

JSON web token integrity needs to be verified so cryptographic signature is used for this purpose. So we expect that every token must be signed with some known cryptographic key.

You have a variety of options on how to specify where the keys are located.

Verify token using a JSON Web Key Set loaded from https endpoint

For more information on JWKS endpoints, refer to Auth0 docs.

# [auth.jwt]
# ...

jwk_set_url = https://your-auth-provider.example.com/.well-known/jwks.json

# When the JWKS url requires an 'Authorization: Bearer <TOKEN>' header
# jwk_set_bearer_token_file = /path/to/bearer_token

# Cache duration for https endpoint response.
cache_ttl = 60m

# Path to file containing one or more custom PEM-encoded CA certificates.
# Used with jwk_set_url when the JWKS endpoint uses a certificate that is not
# trusted by the default CA bundle (e.g. self-signed certificates).
# tls_client_ca = /path/to/ca.crt

# Skip CA Verification entirely
# tls_skip_verify_insecure = false

Note
If the JWKS endpoint includes cache control headers and the value is less than the configured cache_ttl, then the cache control header value is used instead. If the cache_ttl is not set, the default of 60m is used. no-store and no-cache cache control headers are ignored. To disable JWKS caching, set cache_ttl = 0s

Verify token using a JSON Web Key Set loaded from JSON file

Key set in the same format as in JWKS endpoint but located on disk.

jwk_set_file = /path/to/jwks.json

Verify token using a single key loaded from PEM-encoded file

PEM-encoded key file in PKIX, PKCS #1, PKCS #8 or SEC 1 format.

key_file = /path/to/key.pem

If the JWT token’s header specifies a kid (Key ID), then the Key ID must be set using the key_id configuration option.

key_id = my-key-id

Validate claims

By default, only "exp", "nbf" and "iat" claims are validated.

Consider validating that other claims match your expectations by using the expect_claims configuration option. Token claims must match exactly the values set here.

# This can be seen as a required "subset" of a JWT Claims Set.
expect_claims = {"iss": "https://your-token-issuer", "your-custom-claim": "foo"}

Roles

Grafana checks for the presence of a role using the JMESPath specified via the role_attribute_path configuration option. The JMESPath is applied to JWT token claims. The result after evaluation of the role_attribute_path JMESPath expression should be a valid Grafana role, for example, None, Viewer, Editor or Admin.

To assign the role to a specific organization include the X-Grafana-Org-Id header along with your JWT when making API requests to Grafana. To learn more about the header, please refer to the documentation.

Configure role mapping

Unless skip_org_role_sync option is enabled, the user’s role will be set to the role retrieved from the JWT.

To ease configuration of a proper JMESPath expression, go to JMESPath to test and evaluate expressions with custom payloads.

Basic example:

In the following example user will get Editor as role when authenticating. The value of the property role will be the resulting role if the role is a proper Grafana role, i.e. None, Viewer, Editor or Admin.

Payload:

{
    ...
    "role": "Editor",
    ...
}

Configuration:

role_attribute_path = role

Advanced example:

In the following example user will get Admin as role when authenticating since it has a role admin. If a user has a role editor it will get Editor as role, otherwise Viewer.

Payload:

{
    ...
    "info": {
        ...
        "roles": [
            "engineer",
            "admin",
        ],
        ...
    },
    ...
}

Configuration:

role_attribute_path = contains(info.roles[*], 'admin') && 'Admin' || contains(info.roles[*], 'editor') && 'Editor' || 'Viewer'

Org roles mapping example

In the following example, the , the user has been granted the role of a Viewer in the org_foo organization, and the role of an Editor in the org_bar and org_baz organizations.

Payload:

{
    ...
    "info": {
        ...
        "orgs": [
            "engineer",
            "admin",
        ],
        ...
    },
    ...
}

Configuration:

org_attribute_path = info.orgs
org_mapping = engineer:org_foo:Viewer admin:org_bar:Editor *:org_baz:Editor

Grafana Admin Role

If the role_attribute_path property returns a GrafanaAdmin role, Grafana Admin is not assigned by default, instead the Admin role is assigned. To allow Grafana Admin role to be assigned set allow_assign_grafana_admin = true.

Skip organization role mapping

To skip the assignment of roles and permissions upon login via JWT and handle them via other mechanisms like the user interface, we can skip the organization role synchronization with the following configuration.

[auth.jwt]
# ...

skip_org_role_sync = true

Configure authentication on Grafana Labs

Configure basic authentication

Configure basic authentication

Disable basic authentication

Password policy

Disable login form

Configure passwordless authentication with magic links

Configure passwordless authentication with magic links

Enable passwordless authentication

Code expiration

Enable SMTP server

Configure anonymous access

Anonymous authentication

Before you begin

Anonymous devices

Configuration

Licensing for anonymous access

How anonymous usage is counted

Configure LDAP authentication

Configure LDAP authentication

Supported LDAP Servers

Enable LDAP

Disable org role synchronization

Grafana LDAP Configuration

Using the Grafana user interface

Using environment variables

Bind and bind password

Single bind example

POSIX schema

Group mappings

Nested/recursive group membership

Configuration examples

OpenLDAP

Multiple LDAP servers

Active Directory

Port requirements

Troubleshooting

Configure LDAP authentication using the Grafana user interface

Configure LDAP authentication using the Grafana user interface

Before you begin

Steps to configure LDAP authentication

1. Complete mandatory fields

2. Complete optional fields

3. Advanced settings

1. Miscellaneous settings

2. Attributes

3. Group mapping

4. Extra security settings

4. Persisting the configuration

Configure enhanced LDAP integration

Configure enhanced LDAP integration

LDAP group synchronization for teams

Active LDAP synchronization

Configure SAML authentication in Grafana

SAML authentication in Grafana

Set up options for SAML authentication in Grafana

SAML bindings

Request initiation

Identity provider (IdP) registration

IdP metadata

Assertion mapping

Integrate with SCIM Provisioning

Advanced configuration

Configure Generic OAuth authentication

Configure Generic OAuth authentication

Before you begin

Configure generic OAuth authentication client using the Grafana UI

Configure generic OAuth authentication client using the Terraform provider

Configure generic OAuth authentication client using the Grafana configuration file

Steps

Configure login

Use the sub claim for login

Configure display name

Configure email address

Configure a refresh token

Configure JWT ID token validation

Configure role mapping

Role mapping examples

Map user organization role

Map server administrator role

Use the `sub` claim for login