Configure Generic OAuth authentication

{{< docs/shared lookup="auth/intro.md" source="grafana" version="<GRAFANA VERSION>" >}}

Grafana provides OAuth2 integrations for the following auth providers:

• Entra ID OAuth
• GitHub OAuth
• GitLab OAuth
• Google OAuth
• Grafana Com OAuth
• Keycloak OAuth
• Okta OAuth

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

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

Before you begin

To follow this guide:

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

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

Configure generic OAuth authentication client using the Grafana UI

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

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

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

{{< admonition type="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. {{< /admonition >}}

Refer to configuration options for more information.

Configure generic OAuth authentication client using the Terraform provider

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

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

Configure generic OAuth authentication client using the Grafana configuration file

Ensure that you have access to the Grafana configuration file.

Steps

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

1. Create an OAuth2 application in your chosen OAuth2 provider.

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

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

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

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

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

5. Configure role mapping.

6. Optional: Configure team synchronization.

7. Restart Grafana.

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

Configure login

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

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

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

Use the sub claim for login

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

Example configuration:

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

Configure display name

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

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

Configure email address

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

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

Configure a refresh token

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

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

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

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

{{< admonition type="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. {{< /admonition >}}

Configure JWT ID token validation

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

To enable JWT ID token validation:

1. Set validate_id_token to true in the [auth.generic_oauth] section of the Grafana configuration file.

2. Configure jwk_set_url with the URL of your OAuth2 provider's JSON Web Key Set (JWKS) endpoint. This endpoint provides the public keys used to verify JWT signatures.

   Common JWKS endpoint locations:

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

Example configuration:

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

{{< admonition type="note" >}} When JWT validation is enabled, Grafana caches the JWKS keys to improve performance. The cache respects the Cache-Control header from the JWKS endpoint response. If no cache expiration is specified, keys are cached for 5 minutes by default. {{< /admonition >}}

{{< admonition type="caution" >}} If validate_id_token is set to true, you must configure jwk_set_url. Authentication will fail if the JWK Set URL is not provided or if the ID token signature cannot be verified. {{< /admonition >}}

Configure role mapping

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

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

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

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

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

{{< admonition type="note" >}} When using org_attribute_path, the value returned by the JMESPath expression must be an array, not a string. {{< /admonition >}}

Role mapping examples

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

Map user organization role

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

Payload:

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

Config:

role_attribute_path = role

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

Payload:

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

Config:

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

Map server administrator role

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

Payload:

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

Config:

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

Map one role to all users

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

Config:

role_attribute_path = "'Viewer'"
skip_org_role_sync = false

Org roles mapping example

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

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

Payload:

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

Config:

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

Configure team synchronization

{{< admonition type="note" >}} Available in Grafana Enterprise and to customers on select Grafana Cloud plans. For pricing information, visit pricing or contact our sales team. {{< /admonition >}}

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

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

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

Team synchronization example

Configuration:

groups_attribute_path = groups

Payload:

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

Configuration options

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

{{< admonition type="note" >}} If the configuration option requires a JMESPath expression that includes a colon, enclose the entire expression in quotes to prevent parsing errors. For example role_attribute_path: "role:view" {{< /admonition >}}

Examples of setting up Generic OAuth

This section includes examples of setting up Generic OAuth integration.

Set up OAuth2 with Descope

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

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

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

3. Click Save.

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

   {{< admonition type="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. {{< /admonition >}}

   bashCopy

   [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

{{< admonition type="note" >}} Support for the Auth0 "audience" feature is not currently available in Grafana. For roles and permissions, the available options are described here. {{< /admonition >}}

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

1. Create an Auth0 application using the following parameters:

   • Name: Grafana
   • Type: Regular Web Application

2. Go to the Settings tab of the application and set Allowed Callback URLs to https://<grafana domain>/login/generic_oauth.

3. Click Save Changes.

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

   bashCopy

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

Set up OAuth2 with Bitbucket

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

1. Navigate to Settings > Workspace setting > OAuth consumers in BitBucket.

2. Create an application by selecting Add consumer and using the following parameters:

   • Allowed Callback URLs: https://<grafana domain>/login/generic_oauth

3. Click Save.

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

   bashCopy

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

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

Set up OAuth2 with OneLogin

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

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

2. Add an app to the Grafana Connector:

   • Display Name: Grafana

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

   bashCopy

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

Set up OAuth2 with Dex

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

1. Add Grafana as a client in the Dex config YAML file:

   yamlCopy

   staticClients:
     - id: <client id>
       name: Grafana
       secret: <client secret>
       redirectURIs:
         - 'https://<grafana domain>/login/generic_oauth'
   

   {{< admonition type="note" >}} Unlike many other OAuth2 providers, Dex doesn't provide <client secret>. Instead, a secret can be generated with for example openssl rand -hex 20. {{< /admonition >}}

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

   bashCopy

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

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