Configure GitHub OAuth authentication

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

This topic describes how to configure GitHub OAuth authentication.

{{< admonition type="note" >}} If Users use the same email address in GitHub 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 >}}

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.

Create a GitHub OAuth App

1. Log in to your GitHub account. In Profile > Settings > Developer settings, select OAuth Apps.
2. Click New OAuth App.
3. Fill out the fields, using your Grafana homepage URL when appropriate. In the Authorization callback URL field, enter the following: https://<YOUR-GRAFANA-URL>/login/github .
4. Note your client ID.
5. Generate, then note, your client secret.

Configure GitHub authentication client using the Grafana UI

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

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 GitHub authentication client using the Terraform provider

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:

1. Create an OAuth application in GitHub.

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

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

4. Configure role mapping.

5. Optional: Configure team synchronization.

6. 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 the skip_org_role_sync option is enabled, the user's role will be set to the role retrieved from GitHub 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 after evaluating the role_attribute_path and the org_mapping expressions.

You can use the org_mapping configuration options to assign the user to organizations and specify their role based on their GitHub team membership. 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.

Role mapping examples

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

Org roles mapping example

The GitHub integration uses the external users' teams in the org_mapping configuration to map organizations and roles based on their GitHub team membership.

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

The external user is part of the following GitHub teams: @my-github-organization/my-github-team-1 and @my-github-organization/my-github-team-2.

Config:

org_mapping = @my-github-organization/my-github-team-1:org_foo:Viewer @my-github-organization/my-github-team-2:org_bar:Editor *:org_baz:Editor

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 roles using multiple GitHub teams

In this example, the users from GitHub teams admins and devops have been granted the Admin role, the users from GitHub teams engineers and managers have been granted the Editor role, the users from GitHub team qa have been granted the Viewer role and all other users are granted the None role.

role_attribute_path = contains(groups[*], '@my-github-organization/admins') && 'Admin' || contains(groups[*], '@my-github-organization/devops') && 'Admin' || contains(groups[*], '@my-github-organization/engineers') && 'Editor' || contains(groups[*], '@my-github-organization/managers') && 'Editor' || contains(groups[*], '@my-github-organization/qa') && 'Viewer' || 'None'

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

{{< admonition type="note" >}} Available in Grafana Enterprise and Grafana Cloud {{< /admonition >}}

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