mirror of
https://github.com/grafana/grafana.git
synced 2025-09-22 01:37:55 +08:00
Docs/restructures setup (#57125)
* builds out configure grafana directory to align with hugo * restructures configure authentication, corrects relrefs * correct alias * corrects final relrefs
This commit is contained in:
Christopher Moyer
committed by
GitHub
GitHub
parent
6ad405e256
commit
d09d39ddd4
@ -0,0 +1,184 @@
|
||||
---
|
||||
aliases:
|
||||
- /docs/grafana/latest/auth/github/
|
||||
- /docs/grafana/latest/setup-grafana/configure-security/configure-authentication/github/
|
||||
description: Grafana OAuthentication Guide
|
||||
keywords:
|
||||
- grafana
|
||||
- configuration
|
||||
- documentation
|
||||
- oauth
|
||||
title: Configure GitHub OAuth2 Authentication
|
||||
weight: 1400
|
||||
---
|
||||
|
||||
# Configure GitHub OAuth2 authentication
|
||||
|
||||
To enable the GitHub OAuth2 you must register your application with GitHub. GitHub will generate a client ID and secret key for you to use.
|
||||
|
||||
## Configure GitHub OAuth application
|
||||
|
||||
You need to create a GitHub OAuth application (you will find this under the GitHub
|
||||
settings page). When you create the application you will need to specify
|
||||
a callback URL. Specify this as callback:
|
||||
|
||||
```bash
|
||||
http://<my_grafana_server_name_or_ip>:<grafana_server_port>/grafana/login/github
|
||||
```
|
||||
|
||||
This callback URL must match the full HTTP address that you use in your
|
||||
browser to access Grafana, but with the suffix path of `/login/github`.
|
||||
When the GitHub OAuth application is created you will get a Client ID and a
|
||||
Client Secret. Specify these in the Grafana configuration file. For
|
||||
example:
|
||||
|
||||
## Enable GitHub in Grafana
|
||||
|
||||
```bash
|
||||
[auth.github]
|
||||
enabled = true
|
||||
allow_sign_up = 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
|
||||
team_ids =
|
||||
allowed_organizations =
|
||||
```
|
||||
|
||||
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 back-end. You should now see a GitHub login button
|
||||
on the login page. You can now login or sign up with your GitHub
|
||||
accounts.
|
||||
|
||||
You may allow users to sign-up via GitHub authentication by setting the
|
||||
`allow_sign_up` option to `true`. When this option is set to `true`, any
|
||||
user successfully authenticating via GitHub authentication will be
|
||||
automatically signed up.
|
||||
|
||||
You can also use [variable expansion]({{< relref "../../../configure-grafana/#variable-expansion" >}}) to reference environment variables and local files in your GitHub auth configuration.
|
||||
|
||||
### team_ids
|
||||
|
||||
Require an active team membership for at least one of the given teams on
|
||||
GitHub. If the authenticated user isn't a member of at least one of the
|
||||
teams they will not be able to register or authenticate with your
|
||||
Grafana instance. For example:
|
||||
|
||||
```bash
|
||||
[auth.github]
|
||||
enabled = true
|
||||
client_id = YOUR_GITHUB_APP_CLIENT_ID
|
||||
client_secret = YOUR_GITHUB_APP_CLIENT_SECRET
|
||||
scopes = user:email,read:org
|
||||
team_ids = 150,300
|
||||
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
|
||||
```
|
||||
|
||||
### allowed_organizations
|
||||
|
||||
Require an active organization membership for at least one of the given
|
||||
organizations on GitHub. If the authenticated user isn't a member of at least
|
||||
one of the organizations they will not be able to register or authenticate with
|
||||
your Grafana instance. For example
|
||||
|
||||
```bash
|
||||
[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
|
||||
# space-delimited organization names
|
||||
allowed_organizations = github google
|
||||
```
|
||||
|
||||
### Map roles
|
||||
|
||||
You can use GitHub OAuth to map roles. During mapping, Grafana checks for the presence of a role using the [JMESPath](http://jmespath.org/examples.html) specified via the `role_attribute_path` configuration option.
|
||||
|
||||
For the path lookup, Grafana uses JSON obtained from querying GitHub's API [`/api/user`](https://docs.github.com/en/rest/users/users#get-the-authenticated-user=) endpoint and a `groups` key containing all of the user's teams (retrieved from `/api/user/teams`).
|
||||
|
||||
The result of evaluating the `role_attribute_path` JMESPath expression must be a valid Grafana role, for example, `Viewer`, `Editor` or `Admin`. For more information about roles and permissions in Grafana, refer to [Roles and permissions]({{< relref "../../../../administration/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 `oauth_skip_org_role_update_sync` option.
|
||||
> See [configure-grafana]({{< relref "../../../configure-grafana#oauth_skip_org_role_update_sync" >}}) 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 `auto_assign_org_role` option]({{< relref "../../../configure-grafana#auto_assign_org_role" >}}).
|
||||
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_path` property does not return a role,
|
||||
> then the user is assigned the role specified by
|
||||
> [the `auto_assign_org_role` option]({{< relref "../../../configure-grafana#auto_assign_org_role" >}}).
|
||||
|
||||
An example Query could look like the following:
|
||||
|
||||
```bash
|
||||
role_attribute_path = [login==octocat] && 'Admin' || 'Viewer'
|
||||
```
|
||||
|
||||
This allows the user with login "octocat" to be mapped to the `Admin` role,
|
||||
but all other users to be mapped to the `Viewer` role.
|
||||
|
||||
#### Map roles using teams
|
||||
|
||||
Teams can also be used to map roles. For instance,
|
||||
if you have a team called 'example-group' you can use the following snippet to
|
||||
ensure those members inherit the role 'Editor'.
|
||||
|
||||
```bash
|
||||
role_attribute_path = contains(groups[*], '@github/example-group') && 'Editor' || 'Viewer'
|
||||
```
|
||||
|
||||
Note: If a match is found in other fields, teams 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.
|
||||
|
||||
The setting `allow_assign_grafana_admin` under `[auth.github]` 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.
|
||||
|
||||
```ini
|
||||
allow_assign_grafana_admin = true
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```ini
|
||||
role_attribute_path = [login==octocat] && 'GrafanaAdmin' || 'Viewer'
|
||||
```
|
||||
|
||||
### Team Sync (Enterprise only)
|
||||
|
||||
> Only available in Grafana Enterprise v6.3+
|
||||
|
||||
With Team Sync you can map your GitHub org teams to teams in Grafana so that your users will automatically be added to
|
||||
the correct teams.
|
||||
|
||||
Your GitHub teams can be referenced in two ways:
|
||||
|
||||
- `https://github.com/orgs/<org>/teams/<slug>`
|
||||
- `@<org>/<slug>`
|
||||
|
||||
Example: `@grafana/developers`
|
||||
|
||||
[Learn more about Team Sync]({{< relref "../../configure-team-sync/" >}})
|
||||
Reference in New Issue
Block a user