This is documentation for the next version of Grafana. For the latest stable release, go to the latest version.
Configure GitLab OAuth2 authentication
To enable GitLab OAuth2 you must register the application in GitLab. GitLab will generate a client ID and secret key for you to use.
Create GitLab OAuth keys
You need to create a GitLab OAuth application. Choose a descriptive Name, and use the following Redirect URI:
https://grafana.example.com is the URL you use to connect to Grafana.
Adjust it as needed if you don’t use HTTPS or if you use a different port; for
instance, if you access Grafana at
http://203.0.113.31:3000, you should use
read_api as the scope and submit the form. Note that if you’re
not going to use GitLab groups for authorization (i.e. not setting
allowed_groups, see below), you can select
read_user instead of
the scope, thus giving a more restricted access to your GitLab API.
You’ll get an Application Id and a Secret in return; we’ll call them
GITLAB_SECRET respectively for the rest of this
Enable GitLab in Grafana
Add the following to your Grafana configuration file to enable GitLab authentication:
[auth.gitlab] enabled = true allow_sign_up = true auto_login = false client_id = GITLAB_APPLICATION_ID client_secret = GITLAB_SECRET scopes = read_api auth_url = https://gitlab.com/oauth/authorize token_url = https://gitlab.com/oauth/token api_url = https://gitlab.com/api/v4 allowed_groups = role_attribute_path = role_attribute_strict = false allow_assign_grafana_admin = false tls_skip_verify_insecure = false tls_client_cert = tls_client_key = tls_client_ca = use_pkce = true
You may have to set the
root_url option of
[server] for the callback URL to be
correct. For example in case you are serving Grafana behind a proxy.
Restart the Grafana backend for your changes to take effect.
If you use your own instance of GitLab instead of
api_url accordingly by replacing the
hostname with your own.
allow_sign_up set to
false, only existing users will be able to login
using their GitLab account, but with
allow_sign_up set to
true, any user
who can authenticate on GitLab will be able to login on your Grafana instance;
if you use the public
gitlab.com, it means anyone in the world would be able
to login on your Grafana instance.
You can limit access to only members of a given group or list of
groups by setting the
You can also specify the SSL/TLS configuration used by the client.
tls_client_certto the path of the certificate.
tls_client_keyto the path containing the key.
tls_client_cato the path containing a trusted certificate authority list.
tls_skip_verify_insecure controls whether a client verifies the server’s certificate chain and host name. If it is true, then SSL/TLS 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.
Configure refresh token
Available in Grafana v9.3 and later versions.
Note: This feature is behind the
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.
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.
By default, GitLab provides a refresh token.
To limit access to authenticated users that are members of one or more GitLab
to a comma- or space-separated list of groups. For instance, if you want to
only give access to members of the
example group, set
allowed_groups = example
If you want to also give access to members of the subgroup
bar, which is in
allowed_groups = example, foo/bar
To put values containing spaces in the list, use the following JSON syntax:
allowed_groups = ["Admins", "Software Engineers"]
Note that in GitLab, the group or subgroup name doesn’t 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.
Here’s a complete example with
allow_sign_up enabled, with access limited to
foo/bar groups. The example also promotes all GitLab Admins to Grafana organization admins:
[auth.gitlab] enabled = true allow_sign_up = true auto_login = false client_id = GITLAB_APPLICATION_ID client_secret = GITLAB_SECRET scopes = read_api auth_url = https://gitlab.com/oauth/authorize token_url = https://gitlab.com/oauth/token api_url = https://gitlab.com/api/v4 allowed_groups = example, foo/bar role_attribute_path = is_admin && 'Admin' || 'Viewer' role_attribute_strict = true allow_assign_grafana_admin = false tls_skip_verify_insecure = false tls_client_cert = tls_client_key = tls_client_ca = use_pkce = true
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 = true
Grafana always uses the SHA256 based
S256 challenge method and a 128 bytes (base64url encoded) code verifier.
Configure automatic login
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
You can use GitLab OAuth to map roles. During mapping, Grafana checks for the presence of a role using the JMESPath specified via the
role_attribute_path configuration option.
For the path lookup, Grafana uses JSON obtained from querying GitLab’s API
/api/v4/user endpoint and a
groups key containing all of the user’s teams. The result of evaluating the
role_attribute_path JMESPath expression must be a valid Grafana role, for example,
Admin. For more information about roles and permissions in Grafana, refer to Roles and permissions.
Warning: Currently if no organization role mapping is found for a user, Grafana doesn’t update the user’s organization role. This is going to change in Grafana 10. To avoid overriding manually set roles, enable the
skip_org_role_syncoption. See Configure Grafana for more information.
On first login, if the
role_attribute_path property does not return a role, then the user is assigned the role
specified by the
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.
Warning: With Grafana 10, on every login, if the
role_attribute_pathproperty does not return a role, then the user is assigned the role specified by the
An example Query could look like the following:
role_attribute_path = is_admin && 'Admin' || 'Viewer'
This allows every GitLab Admin to be an Admin in Grafana.
Map roles using groups
Groups can also be used to map roles. Group name (lowercased and unique) is used instead of display name for identifying groups
For instance, if you have a group with display name ‘Example-Group’ you can use the following snippet to ensure those members inherit the role ‘Editor’.
role_attribute_path = contains(groups[*], 'example-group') && 'Editor' || 'Viewer'
Note: If a match is found in other fields, groups will be ignored.
Map 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.
[auth.gitlab] 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.
allow_assign_grafana_admin = true
role_attribute_path = is_admin && 'GrafanaAdmin' || 'Viewer'
Team Sync (Enterprise only)
Only available in Grafana Enterprise v6.4+
With Team Sync you can map your GitLab groups to teams in Grafana so that your users will automatically be added to the correct teams.
Your GitLab groups can be referenced in the same way as
Skip organization role sync
To prevent the sync of organization roles from GitLab, set
true. This is useful if you want to manage the organization roles for your users from within Grafana.
This also impacts the
allow_assign_grafana_admin setting by not syncing the Grafana admin role from GitLab.
[auth.gitlab] # .. # prevents the sync of org roles from Github skip_org_role_sync = true ``