Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentation Grafana documentation Set up Configure security Configure authentication GitLab OAuth2

Configure GitLab 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.

This topic describes how to configure GitLab OAuth2 authentication.

Before you begin

To follow this guide:

• Ensure that you have access to the Grafana configuration file.
• Ensure you know how to create a GitLab OAuth application. Consult GitLab’s documentation on creating a GitLab OAuth application for more information.

Steps

To configure GitLab authentication with Grafana, follow these steps:

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

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

3. Optional: Configure a refresh token:

   a. Enable accessTokenExpirationCheck feature toggle.

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

4. Configure role mapping.

5. Optional: Configure team synchronization.

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

Configuration options

The table below describes all GitLab OAuth configuration options. Like any other Grafana configuration, you can apply these options as environment variables.

Configure a refresh token

Available in Grafana v9.3 and later versions.

Note: This feature is behind the accessTokenExpirationCheck feature toggle.

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.

Refresh token fetching and access token expiration check is enabled by default for the GitLab provider since Grafana v10.1.0 if the accessTokenExpirationCheck feature toggle is enabled. 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 will be removed in Grafana v10.2.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.

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

ini Copy

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.

ini Copy

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.

bash Copy

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

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.

Example of GitLab configuration in Grafana

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

bash Copy

[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