Grafana - Configure generic OAuth2 authentication

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:

• Azure AD 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 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.

terraform

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:

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 yo