Configure authentication on Grafana Labs

Configure Grafana authentication

Fri, 07 Mar 2025 09:39:42 +0000

Configure Grafana authentication

Grafana of course has a built in user authentication system with password authentication enabled by default. You can disable authentication by enabling anonymous access. You can also hide login form and only allow login through an auth provider (listed above). There is also options for allowing self sign up.

The following applies when using Grafana’s built in user authentication, LDAP (without Auth proxy) or OAuth integration.

Grafana uses short-lived tokens as a mechanism for verifying authenticated users. These short-lived tokens are rotated each token_rotation_interval_minutes for an active authenticated user.

An active authenticated user that gets it token rotated will extend the login_maximum_inactive_lifetime_duration time from “now” that Grafana will remember the user. This means that a user can close its browser and come back before now + login_maximum_inactive_lifetime_duration and still being authenticated. This is true as long as the time since user login is less than login_maximum_lifetime_duration.

Remote logout

You can logout from other devices by removing login sessions from the bottom of your profile page. If you are a Grafana admin user you can also do the same for any user from the Server Admin / Edit User view.

Settings

Example:

[auth]

# Login cookie name
login_cookie_name = grafana_session

# The lifetime (days) an authenticated user can be inactive before being required to login at next visit. Default is 7 days.
login_maximum_inactive_lifetime_duration = 7d

# The maximum lifetime (days) an authenticated user can be logged in since login time before being required to login. Default is 30 days.
login_maximum_lifetime_duration = 30d

# How often should auth tokens be rotated for authenticated users when being active. The default is each 10 minutes.
token_rotation_interval_minutes = 10

# The maximum lifetime (seconds) an api key can be used. If it is set all the api keys should have limited lifetime that is lower than this value.
api_key_max_seconds_to_live = -1

Anonymous authentication

You can make Grafana accessible without any login required by enabling anonymous access in the configuration file. For more information, refer to Anonymous authentication.

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.

Anonymous users

Note
Anonymous users are charged as active users in Grafana Enterprise

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.

Basic authentication

Basic auth is enabled by default and works with the built in Grafana user password authentication system and LDAP authentication integration.

To disable basic auth:

[auth.basic]
enabled = false

You can hide the Grafana login form using the below configuration settings.

[auth]
disable_login_form = true

Set to true to attempt login with specific OAuth provider automatically, skipping the login screen. This setting is ignored if multiple auth providers are configured to use auto login. Defaults to false.

[auth.generic_oauth]
auto_login = true

Set the option detailed below to true to hide sign-out menu link. Useful if you use an auth proxy or JWT authentication.

[auth]
disable_signout_menu = true

URL redirect after signing out

The URL to redirect the user to after signing out from Grafana can be configured under [auth] or under a specific OAuth provider section (for example, [auth.generic_oauth]). The URL configured under a specific OAuth provider section takes precedence over the URL configured in [auth] section. This can, for example, enable signout from the OAuth provider.

[auth.generic_oauth]
signout_redirect_url =

[auth]
signout_redirect_url =

Protected roles

Note
Available in Grafana Enterprise and Grafana Cloud.

By default, after you configure an authorization provider, Grafana will adopt existing users into the new authentication scheme. For example, if you have created a user with basic authentication having the login jsmith@example.com, then set up SAML authentication where jsmith@example.com is an account, the user’s authentication type will be changed to SAML if they perform a SAML sign-in.

You can disable this user adoption for certain roles using the protected_roles property:

[auth.security]
protected_roles = server_admins org_admins

The value of protected_roles should be a list of roles to protect, separated by spaces. Valid roles are viewers, editors, org_admins, server_admins, and all (a superset of the other roles).

Configure LDAP authentication

Fri, 07 Mar 2025 09:39:42 +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_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
tls_ciphers = []
# This is the minimum TLS version allowed. By default, this value is empty. Accepted values are: TLS1.1, 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 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}"

LDAP debug view

Note
Available in Grafana v6.4+

Grafana has an LDAP debug view built-in which allows you to test your LDAP configuration directly within Grafana. Only Grafana admins can use the LDAP debug view.

Within this view, you’ll be able to see which LDAP servers are currently reachable and test your current configuration.

To use the debug view, complete the following steps:

Type the username of a user that exists within any of your LDAP server(s)
Then, press “Run”
If the user is found within any of your LDAP instances, the mapping information is displayed.

Grafana Enterprise users with enhanced LDAP integration enabled can also see sync status in the debug view. This requires the ldap.status:read permission.

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 # Available in Grafana v5.3 and above

[[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. Available in Grafana v5.3 and above	`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 # Available in Grafana v5.3 and above

# [[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 will need 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 see 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 above example SSL is enabled and an encrypted port have been configured. If your Active Directory don’t support SSL please change enable_ssl = false and port = 389. Please inspect your Active Directory configuration and documentation to find the correct settings. For more information about Active Directory and port requirements see link.

Troubleshooting

To troubleshoot and get more log info enable LDAP debug logging in the main config file.

[log]
filters = ldap:debug

Configure enhanced LDAP integration

Fri, 07 Mar 2025 09:39:42 +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, available in Grafana Enterprise version 6.3 and later, 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 config 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 using the configuration file

Fri, 07 Mar 2025 09:39:42 +0000

Configure SAML authentication using the configuration file

Note
Available in Grafana Enterprise and Grafana Cloud.

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.

You can configure SAML authentication in Grafana through the user interface (UI) or the Grafana configuration file. For instructions on how to set up SAML through Grafana’s UI, refer to Configure SAML authentication using the Grafana user interface. Both methods offer the same configuration options, but you might prefer using the Grafana configuration file if you want to keep all of Grafana’s authentication settings in one place. Grafana Cloud users do not have access to Grafana configuration file, so they should configure SAML through Grafana’s UI.

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

Supported SAML

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

In terms of security:

Grafana supports signed and encrypted assertions.
Grafana does not support signed or encrypted requests.

In terms of 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).

Edit SAML options in the Grafana config file

In the [auth.saml] section in the Grafana configuration file, set enabled to true.
Configure the certificate and private key.
On the Okta application page where you have been redirected after application created, navigate to the Sign On tab and find Identity Provider metadata link in the Settings section.
Set the idp_metadata_url to the URL obtained from the previous step. The URL should look like https://<your-org-id>.okta.com/app/<application-id>/sso/saml/metadata.
Set the following options to the attribute names configured at the step 10 of the SAML integration setup. You can find this attributes on the General tab of the application page (ATTRIBUTE STATEMENTS and GROUP ATTRIBUTE STATEMENTS in the SAML Settings section).
Save the configuration file and and then restart the Grafana server.

When you are finished, the Grafana configuration might look like this example:

[server]
root_url = https://grafana.example.com

[auth.saml]
enabled = true
auto_login = false
private_key_path = "/path/to/private_key.pem"
certificate_path = "/path/to/certificate.cert"
idp_metadata_url = "https://my-org.okta.com/app/my-application/sso/saml/metadata"
assertion_attribute_name = DisplayName
assertion_attribute_login = Login
assertion_attribute_email = Email
assertion_attribute_groups = Group

Enable SAML authentication in Grafana

To use the SAML integration, in the auth.saml section of in the Grafana custom configuration file, set enabled to true.

Refer to Configuration for more information about configuring Grafana.

Certificate and private key

The SAML SSO standard uses asymmetric encryption to exchange information between the SP (Grafana) and the IdP. To perform such encryption, you need a public part and a private part. In this case, the X.509 certificate provides the public part, while the private key provides the private part. The private key needs to be issued in a PKCS#8 format.

Grafana supports two ways of specifying both the certificate and private_key.

Without a suffix (certificate or private_key), the configuration assumes you’ve supplied the base64-encoded file contents.
With the _path suffix (certificate_path or private_key_path), then Grafana treats the value entered as a file path and attempts to read the file from the file system.

Note
You can only use one form of each configuration option. Using multiple forms, such as both certificate and certificate_path, results in an error.

Example of how to generate SAML credentials:

An example of how to generate a self-signed certificate and private key that’s valid for one year:

$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

The generated key.pem and cert.pem files are then used for certificate and private_key.

The key you provide should look like:

-----BEGIN PRIVATE KEY-----
...
...
-----END PRIVATE KEY-----

Set up SAML with Okta

Grafana supports user authentication through Okta, which is useful when you want your users to access Grafana using single sign on. This guide will follow you through the steps of configuring SAML authentication in Grafana with Okta. You need to be an admin in your Okta organization to access Admin Console and create SAML integration. You also need permissions to edit Grafana config file and restart Grafana server.

Before you begin:

To configure SAML integration with Okta, create an app integration inside the Okta organization first. Add app integration in Okta
Ensure you have permission to administer SAML authentication. For more information about roles and permissions in Grafana, refer to Roles and permissions.

To set up SAML with Okta:

Log in to the Okta portal.
Go to the Admin Console in your Okta organization by clicking Admin in the upper-right corner. If you are in the Developer Console, then click Developer Console in the upper-left corner and then click Classic UI to switch over to the Admin Console.
In the Admin Console, navigate to Applications > Applications.
Click Add Application.
Click Create New App to start the Application Integration Wizard.
Choose Web as a platform.
Select SAML 2.0 in the Sign on method section.
Click Create.
On the General Settings tab, enter a name for your Grafana integration. You can also upload a logo.

On the Configure SAML tab, enter the SAML information related to your Grafana instance:

In the Single sign on URL field, use the /saml/acs endpoint URL of your Grafana instance, for example, https://grafana.example.com/saml/acs.
In the Audience URI (SP Entity ID) field, use the /saml/metadata endpoint URL, for example, https://grafana.example.com/saml/metadata.
Leave the default values for Name ID format and Application username.

In the ATTRIBUTE STATEMENTS (OPTIONAL) section, enter the SAML attributes to be shared with Grafana, for example:

Attribute name (in Grafana)	Value (in Okta profile)
Login	`user.login`
Email	`user.email`
DisplayName	`user.firstName + " " + user.lastName`

In the GROUP ATTRIBUTE STATEMENTS (OPTIONAL) section, enter a group attribute name (for example, Group) and set filter to Matches regex .* to return all user groups.

Click Next.
On the final Feedback tab, fill out the form and then click Finish.

Configure SAML authentication in Grafana

The table below describes all SAML configuration options. Continue reading below for details on specific options. Like any other Grafana configuration, you can apply these options as environment variables.

Setting	Required	Description	Default
`enabled`	No	Whether SAML authentication is allowed	`false`
`name`	No	Name used to refer to the SAML authentication in the Grafana user interface.	`SAML`
`single_logout`	No	Whether SAML Single Logout enabled	`false`
`allow_sign_up`	No	Whether to allow new Grafana user creation through SAML login. If set to `false`, then only existing Grafana users can log in with SAML.	`true`
`auto_login`	No	Whether SAML auto login is enabled	`false`
`allow_idp_initiated`	No	Whether SAML IdP-initiated login is allowed	`false`
`certificate` or `certificate_path`	Yes	Base64-encoded string or Path for the SP X.509 certificate
`private_key` or `private_key_path`	Yes	Base64-encoded string or Path for the SP private key
`signature_algorithm`	No	Signature algorithm used for signing requests to the IdP. Supported values are rsa-sha1, rsa-sha256, rsa-sha512.
`idp_metadata`, `idp_metadata_path`, or `idp_metadata_url`	Yes	Base64-encoded string, Path or URL for the IdP SAML metadata XML
`max_issue_delay`	No	Duration, since the IdP issued a response and the SP is allowed to process it	`90s`
`metadata_valid_duration`	No	Duration, for how long the SP metadata is valid	`48h`
`relay_state`	No	Relay state for IdP-initiated login. Should match relay state configured in IdP
`assertion_attribute_name`	No	Friendly name or name of the attribute within the SAML assertion to use as the user name. Alternatively, this can be a template with variables that match the names of attributes within the SAML assertion.	`displayName`
`assertion_attribute_login`	No	Friendly name or name of the attribute within the SAML assertion to use as the user login handle	`mail`
`assertion_attribute_email`	No	Friendly name or name of the attribute within the SAML assertion to use as the user email	`mail`
`assertion_attribute_groups`	No	Friendly name or name of the attribute within the SAML assertion to use as the user groups
`assertion_attribute_role`	No	Friendly name or name of the attribute within the SAML assertion to use as the user roles
`assertion_attribute_org`	No	Friendly name or name of the attribute within the SAML assertion to use as the user organization
`allowed_organizations`	No	List of comma- or space-separated organizations. User should be a member of at least one organization to log in.
`org_mapping`	No	List of comma- or space-separated Organization:OrgId:Role mappings. Organization can be `*` meaning “All users”. Role is optional and can have the following values: `Viewer`, `Editor` or `Admin`.
`role_values_none`	No	List of comma- or space-separated roles which will be mapped into the None role
`role_values_editor`	No	List of comma- or space-separated roles which will be mapped into the Editor role
`role_values_admin`	No	List of comma- or space-separated roles which will be mapped into the Admin role
`role_values_grafana_admin`	No	List of comma- or space-separated roles which will be mapped into the Grafana Admin (Super Admin) role
`name_id_format`	No	The Name ID Format to request within the SAML assertion	`urn:oasis:names:tc:SAML:2.0:nameid-format:transient`

Signature algorithm

Note
Available in Grafana version 7.3 and later.

The SAML standard recommends using a digital signature for some types of messages, like authentication or logout requests. If the signature_algorithm option is configured, Grafana will put a digital signature into SAML requests. Supported signature types are rsa-sha1, rsa-sha256, rsa-sha512. This option should match your IdP configuration, otherwise, signature validation will fail. Grafana uses key and certificate configured with private_key and certificate options for signing SAML requests.

Specify user’s Name ID

The name_id_format configuration field specifies the format of the NameID element in the SAML assertion.

By default, this is set to urn:oasis:names:tc:SAML:2.0:nameid-format:transient and does not need to be specified in the configuration file.

The following list includes valid configuration field values:

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

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 file 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.

Maximum issue delay

Prevents SAML response replay attacks and internal clock skews between the SP (Grafana) and the IdP. You can set a maximum amount of time between the IdP issuing a response and the SP (Grafana) processing it.

The configuration options is specified as a duration, such as max_issue_delay = 90s or max_issue_delay = 1h.

Metadata valid duration

SP metadata is likely to expire at some point, perhaps due to a certificate rotation or change of location binding. Grafana allows you to specify for how long the metadata should be valid. Leveraging the validUntil field, you can tell consumers until when your metadata is going to be valid. The duration is computed by adding the duration to the current time.

The configuration option is specified as a duration, such as metadata_valid_duration = 48h.

Identity provider (IdP) registration

For the SAML integration to work correctly, you need to make the IdP aware of 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-initiated Single Sign-On (SSO)

Note
Available in Grafana version 7.3 and later.

By default, Grafana allows only service provider (SP) initiated logins (when the user logs in with SAML via Grafana’s login page). If you want users to log in into Grafana directly from your identity provider (IdP), set the allow_idp_initiated configuration option to true and configure relay_state with the same value specified in the IdP configuration.

IdP-initiated SSO has some security risks, so make sure you understand the risks before enabling this feature. When using IdP-initiated SSO, Grafana receives unsolicited SAML requests and can’t verify that login flow was started by the user. This makes it hard to detect whether SAML message has been stolen or replaced. Because of this, IdP-initiated SSO is vulnerable to login cross-site request forgery (CSRF) and man in the middle (MITM) attacks. We do not recommend using IdP-initiated SSO and keeping it disabled whenever possible.

Single logout

Note
Available in Grafana version 7.3 and later.

SAML’s single logout feature allows users to log out from all applications associated with the current IdP session established via SAML SSO. If the single_logout option is set to true and a user logs out, Grafana requests IdP to end the user session which in turn triggers logout from all other applications the user is logged into using the same IdP session (applications should support single logout). Conversely, if another application connected to the same IdP logs out using single logout, Grafana receives a logout request from IdP and ends the user session.

HTTP-Redirect and HTTP-POST bindings are supported for single logout. When using HTTP-Redirect bindings the query should include a request signature.

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.

The `assertion_attribute_name` option

assertion_attribute_name is a special assertion mapping that can either be a simple key, indicating a mapping to a single assertion attribute on the SAML response, or a complex template with variables using the $__saml{<attribute>} syntax. If this property is misconfigured, Grafana will log an error message on startup and disallow SAML sign-ins. Grafana will also log errors after a login attempt if a variable in the template is missing from the SAML response.

Examples

#plain string mapping
assertion_attribute_name = displayName

#template mapping
assertion_attribute_name = $__saml{firstName} $__saml{lastName}

Allow new user signups

By default, new Grafana users using SAML authentication will have an account created for them automatically. To decouple authentication and account creation and ensure only users with existing accounts can log in with SAML, set the allow_sign_up option to false.

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

Configure team sync

Note
Team sync support for SAML is available in Grafana version 7.0 and later.

To use SAML Team sync, set assertion_attribute_groups to the attribute name where you store user groups. Then Grafana will use attribute values extracted from SAML assertion to add user into the groups with the same name configured on the External group sync tab.

Note
Teamsync allows you sync users from SAML to Grafana teams. It does not automatically create teams in Grafana. You need to create teams in Grafana before you can use this feature.

Given the following partial SAML assertion:

<saml2:Attribute
    Name="groups"
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
    <saml2:AttributeValue
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="xs:string">admins_group
    </saml2:AttributeValue>
    <saml2:AttributeValue
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="xs:string">division_1
    </saml2:AttributeValue>
</saml2:Attribute>

The configuration would look like this:

[auth.saml]
# ...
assertion_attribute_groups = groups

The following External Group IDs would be valid for input in the desired team’s External group sync tab:

admins_group
division_1

Learn more about Team Sync

Configure role sync

Note
Available in Grafana version 7.0 and later.

Role sync allows you to map user roles from an identity provider to Grafana. To enable role sync, configure role attribute and possible values for the Editor, Admin, and Grafana Admin roles. For more information about user roles, refer to Roles and permissions.

In the configuration file, set assertion_attribute_role option to the attribute name where the role information will be extracted from.
Set the role_values_none option to the values mapped to the None role.
Set the role_values_editor option to the values mapped to the Editor role.
Set the role_values_admin option to the values mapped to the organization Admin role.
Set the role_values_grafana_admin option to the values mapped to the Grafana Admin role.

If a user role doesn’t match any of configured values, then the Viewer role will be assigned.

For more information about roles and permissions in Grafana, refer to Roles and permissions.

Example configuration:

[auth.saml]
assertion_attribute_role = role
role_values_none = none, external
role_values_editor = editor, developer
role_values_admin = admin, operator
role_values_grafana_admin = superadmin

Important: When role sync is configured, any changes of user roles and organization membership made manually in Grafana will be overwritten on next user login. Assign user organizations and roles in the IdP instead.

Note
Available in Grafana version 9.2 and later.

If you don’t want user organizations and roles to be synchronized with the IdP, you can use the skip_org_role_sync configuration option.

Example configuration:

[auth.saml]
skip_org_role_sync = true

Configure organization mapping

Note
Available in Grafana version 7.0 and later.

Organization mapping allows you to assign users to particular organization in Grafana depending on attribute value obtained from identity provider.

In configuration file, set assertion_attribute_org to the attribute name you store organization info in. This attribute can be an array if you want a user to be in multiple organizations.
Set org_mapping option to the comma-separated list of Organization:OrgId pairs to map organization from IdP to Grafana organization specified by id. If you want users to have different roles in multiple organizations, you can set this option to a comma-separated list of Organization:OrgId:Role mappings.

For example, use following configuration to assign users from Engineering organization to the Grafana organization with id 2 as Editor and users from Sales - to the org with id 3 as Admin, based on Org assertion attribute value:

[auth.saml]
assertion_attribute_org = Org
org_mapping = Engineering:2:Editor, Sales:3:Admin

You can specify multiple organizations both for the IdP and Grafana:

org_mapping = Engineering:2, Sales:2 to map users from Engineering and Sales to 2 in Grafana.
org_mapping = Engineering:2, Engineering:3 to assign Engineering to both 2 and 3 in Grafana.

You can use * as the SAML Organization if you want all your users to be in some Grafana organizations with a default role:

org_mapping = *:2:Editor to map all users to 2 in Grafana as Editors.

Note
Available in Grafana version 9.2 and later.

You can use * as the Grafana organization in the mapping if you want all users from a given SAML Organization to be added to all existing Grafana organizations.

org_mapping = Engineering:* to map users from Engineering to all existing Grafana organizations.
org_mapping = Administration:*:Admin to map users from Administration to all existing Grafana organizations as Admins.

Configure allowed organizations

Note
Available in Grafana version 7.0 and later.

With the allowed_organizations option you can specify a list of organizations where the user must be a member of at least one of them to be able to log in to Grafana.

To put values containing spaces in the list, use the following JSON syntax:

allowed_organizations = ["org 1", "second org"]

Example SAML configuration

[auth.saml]
enabled = true
auto_login = false
certificate_path = "/path/to/certificate.cert"
private_key_path = "/path/to/private_key.pem"
idp_metadata_path = "/my/metadata.xml"
max_issue_delay = 90s
metadata_valid_duration = 48h
assertion_attribute_name = displayName
assertion_attribute_login = mail
assertion_attribute_email = mail

assertion_attribute_groups = Group
assertion_attribute_role = Role
assertion_attribute_org = Org
role_values_editor = editor, developer
role_values_admin = admin, operator
role_values_grafana_admin = superadmin
org_mapping = Engineering:2:Editor, Engineering:3:Viewer, Sales:3:Editor, *:1:Editor
allowed_organizations = Engineering, Sales

Troubleshoot SAML authentication in Grafana

To troubleshoot and get more log information, enable SAML debug logging in the configuration file. Refer to Configuration for more information.

[log]
filters = saml.auth:debug

Troubleshooting

Following are common issues found in configuring SAML authentication in Grafana and how to resolve them.

If you experience an infinite redirect loop when auto_login = true or redirected to the login page after successful login, it is likely that the grafana_session cookie’s SameSite setting is set to Strict. This setting prevents the grafana_session cookie from being sent to Grafana during cross-site requests. To resolve this issue, set the security.cookie_samesite option to Lax in the Grafana configuration file.

SAML authentication fails with error:

asn1: structure error: tags don't match

We only support one private key format: PKCS#8.

The keys may be in a different format (PKCS#1 or PKCS#12); in that case, it may be necessary to convert the private key format.

The following command creates a pkcs8 key file.

$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Convert the private key format to base64

The following command converts keys to base64 format.

Base64-encode the cert.pem and key.pem files: (-w0 switch is not needed on Mac, only for Linux)

$ base64 -w0 key.pem > key.pem.base64
$ base64 -w0 cert.pem > cert.pem.base64

The base64-encoded values (key.pem.base64, cert.pem.base64 files) are then used for certificate and private_key.

The keys you provide should look like:

-----BEGIN PRIVATE KEY-----
...
...
-----END PRIVATE KEY-----

When the user logs in using SAML and gets presented with “origin not allowed”, the user might be issuing the login from an IdP (identity provider) service or the user is behind a reverse proxy. This potentially happens as Grafana’s CSRF checks deem the requests to be invalid. For more information CSRF.

To solve this issue, you can configure either the csrf_trusted_origins or csrf_additional_headers option in the SAML configuration.

Example of a configuration file:

# config.ini
...
[security]
csrf_trusted_origins = https://grafana.example.com
csrf_additional_headers = X-Forwarded-Host
...

Accessing the Grafana login page from a URL that is not the root URL of the Grafana server can cause the instance to return the following error: “login session has expired”.

If you are accessing grafana through a proxy server, ensure that cookies are correctly rewritten to the root URL of Grafana. Cookies must be set on the same url as the root_url of Grafana. This is normally the reverse proxy’s domain/address.

Review the cookie settings in your proxy server configuration to ensure that cookies are not being discarded

Review the following settings in your grafana config:

[security]
cookie_samesite = none

This setting should be set to none to allow grafana session cookies to work correctly with redirects.

[security]
cookie_secure = true

Ensure cookie_secure is set to true to ensure that cookies are only sent over HTTPS.

Configure SAML authentication using the Grafana user interface

Fri, 07 Mar 2025 09:39:42 +0000

Configure SAML authentication using the Grafana user interface

Note
Available in Grafana Enterprise version 10.0 and later, and Grafana Cloud Pro and Advanced.

You can configure SAML authentication in Grafana through the user interface (UI) or the Grafana configuration file. For instructions on how to set up SAML using the Grafana configuration file, refer to Configure SAML authentication using the configuration file.

The Grafana SAML UI provides the following advantages over configuring SAML in the Grafana configuration file:

It is accessible by Grafana Cloud users
SAML UI carries out input validation and provides useful feedback on the correctness of the configuration, making SAML setup easier
It doesn’t require Grafana to be restarted after a configuration update
Access to the SAML UI only requires access to authentication settings, so it can be used by users with limited access to Grafana’s configuration

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. This means that 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. For more information on how Grafana determines the order of precedence for its settings, please refer to the Settings update at runtime.

Note
Disabling the UI does not affect any configuration settings that were previously set up through the UI. Those settings will continue to function as intended even with the UI disabled.

Before you begin

To follow this guide, you need:

Knowledge of SAML authentication. Refer to SAML authentication in Grafana for an overview of Grafana’s SAML integration.
Permissions settings:read and settings:write with scope settings:auth.saml:* that allow you to read and update SAML authentication settings.

These permissions are granted by fixed:authentication.config:writer role. By default, this role is granted to Grafana server administrator in self-hosted instances and to Organization admins in Grafana Cloud instances.
Grafana instance running Grafana version 10.0 or later with Grafana Enterprise or Grafana Cloud Pro or Advanced license.

Steps

Follow these steps to configure and enable SAML integration:

Sign in to Grafana and navigate to Administration > Authentication > Configure SAML.
Complete the General settings fields.

For assistance, consult the following table for additional guidance about certain fields:

Field	Description
Allow signup	If enabled, you can create new users through the SAML login. If disabled, then only existing Grafana users can log in with SAML.
Auto login	If enabled, Grafana will attempt to automatically log in with SAML skipping the login screen.
Single logout	The SAML single logout feature enables users to log out from all applications associated with the current IdP session established using SAML SSO. For more information, refer to [SAML single logout documentation]](../saml/#single-logout).
Identity provider initiated login	Enables users to log in to Grafana directly from the SAML IdP. For more information, refer to IdP initiated login documentation.

Click Next: Key and certificate.
Provide a certificate and a private key that will be used by the service provider (Grafana) and the SAML IdP.

Use the PKCS #8 format to issue the private key.

For more information, refer to an example on how to generate SAML credentials.
In the Sign requests field, specify whether you want the outgoing requests to be signed, and, if so, which signature algorithm should be used.

The SAML standard recommends using a digital signature for some types of messages, like authentication or logout requests to avoid man-in-the-middle attacks.
Click Next: Connect Grafana with Identity Provider and complete the section.
Click Next: User mapping.
If you wish to map user information from SAML assertions, complete the Assertion attributes mappings section.

You also need to configure the Groups attribute field if you want to use team sync. Team sync automatically maps users to Grafana teams based on their SAML group membership. Learn more about team sync and configuring team sync for SAML.
If you want to automatically assign users’ roles based on their SAML roles, complete the Role mapping section.

First, you need to configure the Role attribute field to specify which SAML attribute should be used to retrieve SAML role information. Then enter the SAML roles that you want to map to Grafana roles in Role mapping section. If you want to map multiple SAML roles to a Grafana role, separate them by a comma and a space. For example, Editor: editor, developer.

Role mapping will automatically update user’s basic role based on their SAML roles every time the user logs in to Grafana. Learn more about SAML role synchronization.
If you have multiple organizations and want to automatically add users to organizations, complete the Org mapping section.

First, you need to configure the Org attribute field to specify which SAML attribute should be used to retrieve SAML organization information. Now fill in the Org mapping field with mappings from SAML organization to Grafana organization. For example, Org mapping: Engineering:2, Sales:2 will map users who belong to Engineering or Sales organizations in SAML to Grafana organization with ID 2. If you want users to have different roles in different organizations, you can additionally specify a role. For example, Org mapping: Engineering:2:Editor will map users who belong to Engineering organizations in SAML to Grafana organization with ID 2 and assign them Editor role.

Organization mapping will automatically update user’s organization memberships (and roles, if they have been configured) based on their SAML organization every time the user logs in to Grafana. Learn more about SAML organization mapping.
If you want to limit the access to Grafana based on user’s SAML organization membership, fill in the Allowed organizations field.
Click Next: Test and enable and then click Save and enable.
1. If there are issues with your configuration, an error message will appear. Refer back to the previous steps to correct the issues and click on Save and apply on the top right corner once you are done.
If there are no configuration issues, SAML integration status will change to Enabled. Your SAML configuration is now enabled.
To disable SAML integration, click Disable in the top right corner.

Configure generic OAuth2 authentication

Fri, 07 Mar 2025 09:39:42 +0000

Configure generic OAuth2 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 OAuth2 authentication.

This topic describes how to configure generic OAuth2 authentication using different methods and includes examples of setting up generic OAuth2 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.

Configure generic OAuth authentication client using the Grafana UI

Note
Available in Public Preview in Grafana 10.4 behind the ssoSettingsApi feature toggle.

As a Grafana Admin, you can configure Generic OAuth2 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

Note
Available in Public Preview in Grafana 10.4 behind the ssoSettingsApi feature toggle. Supported in the Terraform provider since v2.12.0.

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 OAuth2 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 OAuth2 authentication. Set this value to `true`.

Review the list of other generic OAuth2 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 OAuth2 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 or user information retrieved from the OAuth2 UserInfo endpoint. 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.

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.

Configure display name

Grafana can resolve a user’s display name from the OAuth2 ID token or user information retrieved from the OAuth2 UserInfo endpoint. 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.

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, 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 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

Note: This feature is behind the accessTokenExpirationCheck feature toggle.

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 OAuth2 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 will be 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 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. 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.

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.

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:

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

Config:

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

Map server administrator role

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

Payload:

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

Config:

role_attribute_path = contains(info.roles[*], 'admin') && 'GrafanaAdmin' || contains(info.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

Configure team synchronization

Note: Available in Grafana Enterprise and Grafana Cloud.

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 OAuth2 groups can be referenced by group ID, such as 8bab1c86-8fba-33e5-2089-1d1c80ec267d or myteam. 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 = info.groups

Payload:

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

Configuration options

The following table outlines the various generic OAuth2 configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana.

Setting	Required	Description	Default
`enabled`	No	Enables generic OAuth2 authentication.	`false`
`name`	No	Name that refers to the generic OAuth2 authentication from the Grafana user interface.	`OAuth`
`icon`	No	Icon used for the generic OAuth2 authentication in the Grafana user interface.	`signin`
`client_id`	Yes	Client ID provided by your OAuth2 app.
`client_secret`	Yes	Client secret provided by your OAuth2 app.
`auth_url`	Yes	Authorization endpoint of your OAuth2 provider.
`token_url`	Yes	Endpoint used to obtain the OAuth2 access token.
`api_url`	Yes	Endpoint used to obtain user information compatible with OpenID UserInfo.
`auth_style`	No	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	List of comma- or space-separated OAuth2 scopes.	`user:email`
`empty_scopes`	No	Set to `true` to use an empty scope during authentication.	`false`
`allow_sign_up`	No	Controls Grafana user creation through the generic OAuth2 login. Only existing Grafana users can log in with generic OAuth if set to `false`.	`true`
`auto_login`	No	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`
`id_token_attribute_name`	No	The name of the key used to extract the ID token from the returned OAuth2 token.	`id_token`
`login_attribute_path`	No	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	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	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	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	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. The result of the evaluation should be a valid Grafana role (`Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to Configure role mapping.
`role_attribute_strict`	No	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`
`allow_assign_grafana_admin`	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`
`skip_org_role_sync`	No	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`
`groups_attribute_path`	No	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. The result of the evaluation should be a string array of groups.
`allowed_groups`	No	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	List of comma- or space-separated organizations. The user should be a member of at least one organization to log in.
`allowed_domains`	No	List comma- or space-separated domains. The user should belong to at least one domain to log in.
`team_ids`	No	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	The JMESPath expression to use for Grafana team ID lookup within the results returned by the `teams_url` endpoint.
`teams_url`	No	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	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	The path to the certificate.
`tls_client_key`	No	The path to the key.
`tls_client_ca`	No	The path to the trusted certificate authority list.
`use_pkce`	No	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	Set to `true` to use refresh token and check access token expiration.	`false`

Examples of setting up generic OAuth2

This section includes examples of setting up generic OAuth2 integration.

Set up OAuth2 with Descope

To set up generic OAuth2 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

To set up generic OAuth2 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 OAuth2 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 OAuth2 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 =

Configure Azure AD OAuth2 authentication

Fri, 07 Mar 2025 09:39:42 +0000

Configure Azure AD OAuth2 authentication

The Azure AD authentication allows you to use an Azure Active Directory tenant as an identity provider for Grafana. You can use Azure AD application roles to assign users and groups to Grafana roles from the Azure Portal.

Note
If Users use the same email address in Azure AD 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 Using the same email address to login with different identity providers for more information.

Create the Azure AD application

To enable the Azure AD OAuth2, register your application with Azure AD.

Log in to Azure Portal, then click Azure Active Directory 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 Azure AD 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 following 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, then add a new entry under Client secrets with the following configuration.
- Description: Grafana OAuth
- Expires: Never
Click Add then copy the key value. This is the OAuth client secret.
Define the required application roles for Grafana using the Azure Portal or using the manifest file.
Go to Azure Active Directory and then to Enterprise Applications.
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.

Configure application roles for Grafana in the Azure Portal

This section describes setting up basic application roles for Grafana within the Azure 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 and then click Edit.
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

Available in Grafana v9.2 and later versions.

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.

The setting allow_assign_grafana_admin under [auth.azuread] must be set 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"
}

Before you begin

Ensure that you have followed the steps in Create the Azure AD application before you begin.

Configure Azure AD authentication client using the Grafana UI

Note
Available in Public Preview in Grafana 10.4 behind the ssoSettingsApi feature toggle.

As a Grafana Admin, you can configure your Azure AD OAuth2 client from within Grafana using the Grafana UI. To do this, navigate to the Administration > Authentication > Azure AD 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 Azure AD authentication client using the Terraform provider

Note
Available in Public Preview in Grafana 10.4 behind the ssoSettingsApi feature toggle. Supported in the Terraform provider since v2.12.0.

resource "grafana_sso_settings" "azuread_sso_settings" {
  provider_name = "azuread"
  oauth2_settings {
    name                       = "Azure AD"
    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_id                  = "APPLICATION_ID"
    client_secret              = "CLIENT_SECRET"
    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
  }
}

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

Configure Azure AD authentication client using the Grafana configuration file

Ensure that you have access to the Grafana configuration file.

Enable Azure AD OAuth in Grafana

Add the following to the Grafana configuration file:

[auth.azuread]
name = Azure AD
enabled = true
allow_sign_up = true
auto_login = false
client_id = APPLICATION_ID
client_secret = CLIENT_SECRET
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_id and client_secret:

GF_AUTH_AZUREAD_CLIENT_ID
GF_AUTH_AZUREAD_CLIENT_SECRET

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

Configure refresh token

Available in Grafana v9.3 and later versions.

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 AzureAD 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 Azure Active Directory -> Overview.

Make sure to include the tenant IDs of all the federated Users’ root directory if your Azure AD 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

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

To limit access to authenticated users who are members of one or more AzureAD 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 Azure Active Directory > 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 Azure AD 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.
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, Azure AD 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 and then click Edit.

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 (Enterprise only)

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

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

To learn more, refer to the Team Sync documentation.

Common troubleshooting

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

Users with over 200 Group assignments

Supported in Grafana v8.5 and later versions.

To ensure that the token size doesn’t exceed HTTP header size limits, Azure AD limits the number of object IDs that it includes in the groups claim. If a user is member of more groups than the overage limit (200), then Azure AD 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.

Note
The ‘App registration’ must include the GroupMember.Read.All API permission for group overage claim calls to succeed.

Admin consent might be required for this permission.

Configure the required Graph API permissions

Navigate to Azure Active Directory > 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.

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 config option.

force_use_graph_api = true

Map roles

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

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. It denies user access if no role or an invalid role is returned.

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

Skip organization role sync

If Azure AD authentication is not intended to sync user roles and organization membership and prevent the sync of org roles from AzureAD, set skip_org_role_sync to true. This is useful 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 AzureAD
skip_org_role_sync = true

Configure GitHub OAuth2 authentication

Fri, 07 Mar 2025 09:39:42 +0000

Configure GitHub OAuth2 authentication

This topic describes how to configure GitHub OAuth2 authentication.

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.

Configure GitHub authentication client using the Grafana UI

Note
Available in Public Preview in Grafana 10.4 behind the ssoSettingsApi feature toggle.

As a Grafana Admin, you can configure GitHub OAuth2 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

Note
Available in Public Preview in Grafana 10.4 behind the ssoSettingsApi feature toggle. Supported in the Terraform provider since v2.12.0.

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 skip_org_role_sync option is enabled, the user’s role will be set to the role retrieved from GitHub upon user login.

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.

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 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. Like any other Grafana configuration, you can apply these options as environment variables.

Setting	Required	Description	Default
`enabled`	No	Whether GitHub OAuth authentication is allowed.	`false`
`name`	No	Name used to refer to the GitHub authentication in the Grafana user interface.	`GitHub`
`icon`	No	Icon used for GitHub authentication in the Grafana user interface.	`github`
`client_id`	Yes	Client ID provided by your GitHub OAuth app.
`client_secret`	Yes	Client secret provided by your GitHub OAuth app.
`auth_url`	Yes	Authorization endpoint of your GitHub OAuth provider.	`https://github.com/login/oauth/authorize`
`token_url`	Yes	Endpoint used to obtain GitHub OAuth access token.	`https://github.com/login/oauth/access_token`
`api_url`	Yes	Endpoint used to obtain GitHub user information compatible with OpenID UserInfo.	`https://api.github.com/user`
`scopes`	No	List of comma- or space-separated GitHub OAuth scopes.	`user:email,read:org`
`allow_sign_up`	No	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	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	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 (`Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to Configure role mapping.
`role_attribute_strict`	No	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`
`allow_assign_grafana_admin`	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`
`skip_org_role_sync`	No	Set to `true` to stop automatically syncing user roles.	`false`
`allowed_organizations`	No	List of comma- or space-separated organizations. User must be a member of at least one organization to log in.
`allowed_domains`	No	List of comma- or space-separated domains. User must belong to at least one domain to log in.
`team_ids`	No	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	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	The path to the certificate.
`tls_client_key`	No	The path to the key.
`tls_client_ca`	No	The path to the trusted certificate authority list.

Configure GitLab OAuth2 authentication

Fri, 07 Mar 2025 09:39:42 +0000

Configure GitLab OAuth2 authentication

This topic describes how to configure GitLab OAuth2 authentication.

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.

Configure GitLab authentication client using the Grafana UI

Note
Available in Public Preview in Grafana 10.4 behind the ssoSettingsApi feature toggle.

As a Grafana Admin, you can configure GitLab OAuth2 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

Note
Available in Public Preview in Grafana 10.4 behind the ssoSettingsApi feature toggle. Supported in the Terraform provider since v2.12.0.

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 client ID and client secret from your GitLab OAuth2 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

Available in Grafana v9.3 and later versions.

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 and the use_refresh_token configuration value will be used instead for configuring refresh token fetching and access token expiration check.

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.

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.

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 table below describes all GitLab OAuth configuration options. Like any other Grafana configuration, you can apply these options as environment variables.

Setting	Required	Description	Default
`enabled`	Yes	Whether GitLab OAuth authentication is allowed.	`false`
`client_id`	Yes	Client ID provided by your GitLab OAuth app.
`client_secret`	Yes	Client secret provided by your GitLab OAuth app.
`auth_url`	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	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	Grafana uses `<api_url>/user` endpoint to obtain GitLab user information compatible with OpenID UserInfo.	`https://gitlab.com/api/v4`
`name`	No	Name used to refer to the GitLab authentication in the Grafana user interface.	`GitLab`
`icon`	No	Icon used for GitLab authentication in the Grafana user interface.	`gitlab`
`scopes`	No	List of comma or space-separated GitLab OAuth scopes.	`openid email profile`
`allow_sign_up`	No	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	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	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 (`Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to Configure role mapping.
`role_attribute_strict`	No	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`
`allow_assign_grafana_admin`	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`
`skip_org_role_sync`	No	Set to `true` to stop automatically syncing user roles.	`false`
`allowed_domains`	No	List of comma or space-separated domains. User must belong to at least one domain to log in.
`allowed_groups`	No	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	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	The path to the certificate.
`tls_client_key`	No	The path to the key.
`tls_client_ca`	No	The path to the trusted certificate authority list.
`use_pkce`	No	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	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`

Configure Google OAuth2 authentication

Fri, 07 Mar 2025 09:39:42 +0000

Configure Google OAuth2 authentication

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

Create Google OAuth keys

First, you need to create a Google OAuth Client:

Go to https://console.developers.google.com/apis/credentials.
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://grafana.mycompany.com
- Authorized Redirect URLs: https://grafana.mycompany.com/login/google
- Replace https://grafana.mycompany.com with the URL of your Grafana instance.
Click Create
Copy the Client ID and Client Secret from the ‘OAuth Client’ modal

Configure Google authentication client using the Grafana UI

Note
Available in Public Preview in Grafana 10.4 behind the ssoSettingsApi feature toggle.

As a Grafana Admin, you can configure Google OAuth2 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

Note
Available in Public Preview in Grafana 10.4 behind the ssoSettingsApi feature toggle. Supported in the Terraform provider since v2.12.0.

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 back-end. 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
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 is not be available.

This validation will be enabled by default with Grafana 11.0. 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

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

Configure refresh token

Available in Grafana v9.3 and later versions.

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.

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

Configure team sync for Google OAuth

Available in Grafana v10.1.0 and later versions.

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.

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

Available in Grafana v10.2.0 and later versions.

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

Available in Grafana v10.2.0 and later versions.

Unless 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.

By default skip_org_role_sync is enabled. skip_org_role_sync will default to false in Grafana v10.3.0 and later versions.

Role mapping examples

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

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 has been 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 will be assigned Viewer role regardless of the user information received from the identity provider.

role_attribute_path = "'Viewer'"
skip_org_role_sync = false

Configure Grafana Com authentication

Wed, 06 Mar 2024 15:13:49 +0000

Configure Grafana Com authentication

To enable GrafanaCom as your authentication provider, you configure it to generate a client ID and a secret key.

Create GrafanaCom OAuth keys

To use GrafanaCom authentication:

Log in to GrafanaCom.
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 secret key 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.com credentials, their assigned org role overrides the role defined in the Grafana instance. To prevent Grafana.com 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, 07 Mar 2025 09:39:42 +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.

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.

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

Teamsync

Note
Available in Grafana Enterprise and Grafana Cloud.

Teamsync 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>/auth/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

Available in Grafana v9.2 and later versions.

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

Available in Grafana v9.3 and later versions.

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.

Configure Okta OIDC authentication

Fri, 07 Mar 2025 09:39:42 +0000

Configure Okta OIDC authentication

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 Cloud 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.

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

Note
Available in Public Preview in Grafana 10.4 behind the ssoSettingsApi feature toggle.

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

Note
Available in Public Preview in Grafana 10.4 behind the ssoSettingsApi feature toggle. Supported in the Terraform provider since v2.12.0.

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:

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

b. Enable the refresh token at the Okta application settings.
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 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.

Configure team synchronization (Enterprise only)

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.

Setting	Required	Description	Default
`enabled`	No	Enables Okta OIDC authentication.	`false`
`name`	No	Name that refers to the Okta OIDC authentication from the Grafana user interface.	`Okta`
`icon`	No	Icon used for the Okta OIDC authentication in the Grafana user interface.	`okta`
`client_id`	Yes	Client ID provided by your Okta OIDC app.
`client_secret`	Yes	Client secret provided by your Okta OIDC app.
`auth_url`	Yes	Authorization endpoint of your Okta OIDC provider.
`token_url`	Yes	Endpoint used to obtain the Okta OIDC access token.
`api_url`	Yes	Endpoint used to obtain user information.
`scopes`	No	List of comma- or space-separated Okta OIDC scopes.	`openid profile email groups`
`allow_sign_up`	No	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	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	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 (`Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to Configure role mapping.
`role_attribute_strict`	No	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`
`skip_org_role_sync`	No	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	List of comma- or space-separated groups. The user should be a member of at least one group to log in.
`allowed_domains`	No	List comma- or space-separated domains. The user should belong to at least one domain to log in.
`use_pkce`	No	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	Set to `true` to use refresh token and check access token expiration.	`false`

Configure auth proxy authentication

Fri, 07 Mar 2025 09:39:42 +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
sync_ttl = 60
# 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 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 httpd 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/password we created in the htpasswd file.

Team Sync (Enterprise only)

Only available in Grafana Enterprise v6.3+

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 settings login_maximum_inactive_lifetime_duration and login_maximum_lifetime_duration under [auth] to control session lifetime.

Configure JWT authentication

Fri, 07 Mar 2025 09:39:42 +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.

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.

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 public 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 have enabled JWT before setting this setting see section 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

# Cache TTL for data loaded from http endpoint.
cache_ttl = 60m

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, no caching is performed. no-store and no-cache cache control headers are ignored.

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.

You might also want to validate that other claims are really what you expect them to be.

# 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, Viewer, Editor or Admin.

The organization that the role is assigned to can be configured using the X-Grafana-Org-Id header.

JMESPath examples

To ease configuration of a proper JMESPath expression, you can test/evaluate expressions with custom payloads at http://jmespath.org/.

Role mapping

If the role_attribute_path property does not return a role, then the user is assigned the Viewer role by default. You can disable the role assignment by setting role_attribute_strict = true. It denies user access if no role or an invalid role is returned.

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. Viewer, Editor or Admin.

Payload:

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

Config:

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",
        ],
        ...
    },
    ...
}

Config:

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

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 Grafana authentication

Configure Grafana authentication

Login and short-lived tokens

Remote logout

Settings

Anonymous authentication

Anonymous devices

Anonymous users

Configuration

Basic authentication

Disable login form

Automatic OAuth login

Hide sign-out menu

URL redirect after signing out

Protected roles

Configure LDAP authentication

Configure LDAP authentication

Supported LDAP Servers

Enable LDAP

Disable org role synchronization

Grafana LDAP Configuration

Using environment variables

LDAP debug view

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 enhanced LDAP integration

Configure enhanced LDAP integration

LDAP group synchronization for teams

Active LDAP synchronization

Configure SAML authentication using the configuration file

Configure SAML authentication using the configuration file

Supported SAML

Edit SAML options in the Grafana config file

Enable SAML authentication in Grafana

Certificate and private key

Example of how to generate SAML credentials:

Set up SAML with Okta

Configure SAML authentication in Grafana

Signature algorithm

Specify user’s Name ID

IdP metadata

Maximum issue delay

Metadata valid duration

Identity provider (IdP) registration

IdP-initiated Single Sign-On (SSO)

Single logout

Assertion mapping

The assertion_attribute_name option

Allow new user signups

Configure automatic login

Configure team sync

Configure role sync

Configure organization mapping

Configure allowed organizations

Example SAML configuration

Troubleshoot SAML authentication in Grafana

Troubleshooting

Infinite redirect loop / User gets redirected to the login page after successful login on the IdP side

SAML authentication fails with error:

Convert the private key format to base64

SAML login attempts fail with request response “origin not allowed”

SAML login attempts fail with request response “login session has expired”

Configure SAML authentication using the Grafana user interface

Configure SAML authentication using the Grafana user interface

Before you begin

Steps

Configure generic OAuth2 authentication

Configure generic OAuth2 authentication

Before you begin

Configure generic OAuth authentication client using the Grafana UI

The `assertion_attribute_name` option