mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Auth: update generic OAuth documentation (#70330)
* update generic OAuth docs * some more fixes and corrections * update examples and sync sections * fix a link * linting * formatting and adding more links to OAuth integrations * add a section with config walkthrough * fix link * move examples to the end of the doc * extend role mapping * small improvements * add a before you begin section, clean up steps, remove some text * remove unnecessary section * merge main 2 * OAuth -> OAuth2 * remove Centrify example because it's likely outdated * add shared intro content * indentation * add refresh token to tasks, clean up more sections * linting * linting * Apply suggestions from code review Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * Update docs/sources/setup-grafana/configure-security/configure-authentication/generic-oauth/index.md Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * indentation and small descriptions under headings * add a table for config options * clean up more sections * rewrite email address section * rewriting login and display name sections, plus adding line breaks * clean up more sections * update role mapping section * indentation again * update section names * incorporates final edits * Apply suggestions from code review Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * pr feedback * Apply suggestions from code review Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> * PR feedback: rewording --------- Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> Co-authored-by: Chris Moyer <chris.moyer@grafana.com>
This commit is contained in:
Ieva
GitHub
parent
c191a20591
commit
276c63a656
@ -1,7 +1,7 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../auth/generic-oauth/
|
||||
description: Grafana OAuthentication Guide
|
||||
description: Configure generic OAuth2 authentication
|
||||
keywords:
|
||||
- grafana
|
||||
- configuration
|
||||
@ -14,305 +14,189 @@ weight: 700
|
||||
|
||||
# Configure generic OAuth2 authentication
|
||||
|
||||
You can configure many different OAuth2 authentication services with Grafana using the generic OAuth2 feature. Examples:
|
||||
{{< docs/shared "auth/intro.md" >}}
|
||||
|
||||
- [Configure generic OAuth authentication](#configure-generic-oauth2-authentication)
|
||||
- [Email address](#email-address)
|
||||
- [Groups / Teams](#groups--teams)
|
||||
- [Login](#login)
|
||||
- [PKCE](#pkce)
|
||||
- [Configure refresh token](#configure-refresh-token)
|
||||
- [Configure automatic login](#configure-automatic-login)
|
||||
- [Set up OAuth2 with Auth0](#set-up-oauth2-with-auth0)
|
||||
- [Set up OAuth2 with Bitbucket](#set-up-oauth2-with-bitbucket)
|
||||
- [Set up OAuth2 with Centrify](#set-up-oauth2-with-centrify)
|
||||
- [Set up OAuth2 with OneLogin](#set-up-oauth2-with-onelogin)
|
||||
- [Role Mapping](#role-mapping)
|
||||
- [JMESPath examples](#jmespath-examples)
|
||||
- [Map user organization role](#map-user-organization-role)
|
||||
- [Map server administrator privileges](#map-server-administrator-privileges)
|
||||
- [Team synchronization](#team-synchronization)
|
||||
- [Skip organization role sync](#skip-organization-role-sync)
|
||||
Grafana provides OAuth2 integrations for the following auth providers:
|
||||
|
||||
This callback URL must match the full HTTP address that you use in your browser to access Grafana, but with the suffixed path of `/login/generic_oauth`.
|
||||
- [Azure AD OAuth]({{< relref "../azuread" >}})
|
||||
- [GitHub OAuth]({{< relref "../github" >}})
|
||||
- [GitLab OAuth]({{< relref "../gitlab" >}})
|
||||
- [Google OAuth]({{< relref "../google" >}})
|
||||
- [Grafana Com OAuth]({{< relref "../grafana-com" >}})
|
||||
- [Okta OAuth]({{< relref "../okta" >}})
|
||||
|
||||
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.
|
||||
If your OAuth2 provider is not listed, you can use generic OAuth2 authentication.
|
||||
|
||||
Example config:
|
||||
This topic describes how to configure generic OAuth2 authentication and includes [examples of setting up generic OAuth2]({{< relref "#examples-of-setting-up-generic-oauth2" >}}) with specific OAuth2 providers.
|
||||
|
||||
```bash
|
||||
[auth.generic_oauth]
|
||||
name = OAuth
|
||||
icon = signin
|
||||
enabled = true
|
||||
allow_sign_up = true
|
||||
auto_login = false
|
||||
client_id = YOUR_APP_CLIENT_ID
|
||||
client_secret = YOUR_APP_CLIENT_SECRET
|
||||
scopes =
|
||||
empty_scopes = false
|
||||
auth_url =
|
||||
token_url =
|
||||
api_url =
|
||||
allowed_domains = mycompany.com mycompany.org
|
||||
allowed_groups = ["Admins", "Software Engineers"]
|
||||
tls_skip_verify_insecure = false
|
||||
tls_client_cert =
|
||||
tls_client_key =
|
||||
tls_client_ca =
|
||||
use_pkce = true
|
||||
auth_style =
|
||||
```
|
||||
## Before you begin
|
||||
|
||||
Set `api_url` to the resource that returns [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo) compatible information.
|
||||
To follow this guide:
|
||||
|
||||
You can also specify the SSL/TLS configuration used by the client.
|
||||
- Ensure that you have access to the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}).
|
||||
- Ensure you know how to create an OAuth2 application with your OAuth2 provider. Consult the documentation of your OAuth2 provider for more information.
|
||||
- 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.
|
||||
|
||||
- Set `tls_client_cert` to the path of the certificate.
|
||||
- Set `tls_client_key` to the path containing the key.
|
||||
- Set `tls_client_ca` to the path containing a trusted certificate authority list.
|
||||
## Integrate an OAuth2 provider with Grafana
|
||||
|
||||
`tls_skip_verify_insecure` controls whether a client verifies the server's certificate chain and host name. If it is true, then SSL/TLS accepts any certificate presented by the server and any host name in that certificate. _You should only use this for testing_, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks.
|
||||
To integrate your OAuth2 provider with Grafana using our generic OAuth2 authentication, follow these steps:
|
||||
|
||||
`auth_style` controls which [OAuth2 AuthStyle](https://pkg.go.dev/golang.org/x/oauth2#AuthStyle) is used when token is requested from OAuth provider. It determines how `client_id` and `client_secret` are sent to Oauth provider.
|
||||
Available values are `AutoDetect`, `InParams` and `InHeader`. By default, `AutoDetect` is used.
|
||||
1. Create an OAuth2 application in your chosen OAuth2 provider.
|
||||
1. Set the callback URL for your OAuth2 app to `http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/generic_oauth`.
|
||||
|
||||
Set `empty_scopes` to true to use an empty scope during authentication. By default, Grafana uses `user:email` as scope.
|
||||
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`.
|
||||
|
||||
### Email address
|
||||
For the callback URL to be correct, it might be necessary to set the `root_url` option to `[server]`, for example, if you are serving Grafana behind a proxy.
|
||||
|
||||
Grafana determines a user's email address by querying the OAuth provider until it finds an e-mail address:
|
||||
1. Refer to the following table to update field values located in the `[auth.generic_oauth]` section of the Grafana configuration file:
|
||||
|
||||
1. Check for the presence of an e-mail address via the `email` field encoded in the OAuth `id_token` parameter.
|
||||
1. Check for the presence of an e-mail address using the [JMESPath](http://jmespath.org/examples.html) specified via the `email_attribute_path` configuration option. The JSON used for the path lookup is the HTTP response obtained from querying the UserInfo endpoint specified via the `api_url` configuration option.
|
||||
**Note**: Only available in Grafana v6.4+.
|
||||
1. Check for the presence of an e-mail address in the `attributes` map encoded in the OAuth `id_token` parameter. By default Grafana will perform a lookup into the attributes map using the `email:primary` key, however, this is configurable and can be adjusted by using the `email_attribute_name` configuration option.
|
||||
1. Query the `/emails` endpoint of the OAuth provider's API (configured with `api_url`), then check for the presence of an email address marked as a primary address.
|
||||
1. If no email address is found in steps (1-4), then the email address of the user is set to an empty string.
|
||||
| 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. |
|
||||
| `token_url` | The token 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](https://connect2id.com/products/server/docs/api/userinfo). |
|
||||
| `token_url` | The token endpoint of your OAuth2 provider. |
|
||||
| `enabled` | Enables generic OAuth2 authentication. Set this value to `true`. |
|
||||
|
||||
### Groups / Teams
|
||||
Review the list of other generic OAuth2 [configuration options]({{< relref "#configuration-options" >}}) and complete them, as necessary.
|
||||
|
||||
Similarly, group mappings are made using [JMESPath](http://jmespath.org/examples.html) with the `groups_attribute_path` configuration option. The `id_token` is attempted first, followed by the UserInfo from the `api_url`. The result of the JMESPath expression should be a string array of groups.
|
||||
1. Optional: [Configure a refresh token]({{< relref "#configure-a-refresh-token" >}}):
|
||||
|
||||
Furthermore, Grafana will check for the presence of at least one of the teams specified via the `team_ids` configuration option using the [JMESPath](http://jmespath.org/examples.html) specified via the `team_ids_attribute_path` configuration option. The JSON used for the path lookup is the HTTP response obtained from querying the Teams endpoint specified via the `teams_url` configuration option (using `/teams` as a fallback endpoint). The result should be a string array of Grafana Team IDs. Using this setting ensures that only certain teams is allowed to authenticate to Grafana using your OAuth provider.
|
||||
a. Enable `accessTokenExpirationCheck` feature toggle.
|
||||
|
||||
You can limit access to only members of a given group or list of groups by setting the `allowed_groups` option.
|
||||
b. Extend the `scopes` field of `[auth.generic_oauth]` section in Grafana configuration file with refresh token scope used by your OAuth2 provider.
|
||||
|
||||
### Login
|
||||
c. Enable the refresh token on the provider if required.
|
||||
|
||||
Customize user login using `login_attribute_path` configuration option. Order of operations is as follows:
|
||||
1. [Configure role mapping]({{< relref "#configure-role-mapping" >}}).
|
||||
1. Optional: [Configure team synchronization]({{< relref "#configure-team-synchronization" >}}).
|
||||
1. Restart Grafana.
|
||||
|
||||
1. Grafana evaluates the `login_attribute_path` JMESPath expression against the ID token.
|
||||
1. If Grafana finds no value, then Grafana evaluates expression against the JSON data obtained from UserInfo endpoint. The UserInfo endpoint URL is specified in the `api_url` configuration option.
|
||||
You should now see a generic OAuth2 login button on the login page and be able to log in or sign up with your OAuth2 provider.
|
||||
|
||||
You can customize the attribute name used to extract the ID token from the returned OAuth token with the `id_token_attribute_name` option.
|
||||
## Configuration options
|
||||
|
||||
You can set the user's display name with JMESPath using the `name_attribute_path` configuration option. It operates the same way as the `login_attribute_path` option.
|
||||
The following table outlines the various generic OAuth2 configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana.
|
||||
|
||||
> **Note:** `name_attribute_path` is available in Grafana 7.4+.
|
||||
| Setting | Required | Description | Default |
|
||||
| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
|
||||
| `enabled` | No | Enables generic OAuth2 authentication. | `false` |
|
||||
| `name` | No | Name that refers to the generic OAuth2 authentication from the Grafana user interface. | `OAuth` |
|
||||
| `icon` | No | Icon used for the generic OAuth2 authentication in the Grafana user interface. | `signin` |
|
||||
| `client_id` | Yes | Client ID provided by your OAuth2 app. | |
|
||||
| `client_secret` | Yes | Client secret provided by your OAuth2 app. | |
|
||||
| `auth_url` | Yes | Authorization endpoint of your OAuth2 provider. | |
|
||||
| `token_url` | Yes | Endpoint used to obtain the OAuth2 access token. | |
|
||||
| `api_url` | Yes | Endpoint used to obtain user information compatible with [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo). | |
|
||||
| `auth_style` | No | Name of the [OAuth2 AuthStyle](https://pkg.go.dev/golang.org/x/oauth2#AuthStyle) to be used when ID token is requested from OAuth2 provider. It determines how `client_id` and `client_secret` are sent to Oauth2 provider. Available values are `AutoDetect`, `InParams` and `InHeader`. | `AutoDetect` |
|
||||
| `scopes` | No | List of comma- or space-separated OAuth2 scopes. | `user:email` |
|
||||
| `empty_scopes` | No | Set to `true` to use an empty scope during authentication. | `false` |
|
||||
| `allow_sign_up` | No | Controls Grafana user creation through the generic OAuth2 login. Only existing Grafana users can log in with generic OAuth if set to `false`. | `true` |
|
||||
| `auto_login` | No | Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login. | `false` |
|
||||
| `id_token_attribute_name` | No | The name of the key used to extract the ID token from the returned OAuth2 token. | `id_token` |
|
||||
| `login_attribute_path` | No | [JMESPath](http://jmespath.org/examples.html) expression to use for user login lookup from the user ID token. For more information on how user login is retrieved, refer to [Configure login]({{< relref "#configure-login" >}}). | |
|
||||
| `name_attribute_path` | No | [JMESPath](http://jmespath.org/examples.html) expression to use for user name lookup from the user ID token. This name will be used as the user's display name. For more information on how user display name is retrieved, refer to [Configure display name]({{< relref "#configure-display-name" >}}). | |
|
||||
| `email_attribute_path` | No | [JMESPath](http://jmespath.org/examples.html) expression to use for user email lookup from the user information. For more information on how user email is retrieved, refer to [Configure email address]({{< relref "#configure-email-address" >}}). | |
|
||||
| `email_attribute_name` | No | Name of the key to use for user email lookup within the `attributes` map of OAuth2 ID token. For more information on how user email is retrieved, refer to [Configure email address]({{< relref "#configure-email-address" >}}). | `email:primary` |
|
||||
| `role_attribute_path` | No | [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana role lookup. 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. The result of the evaluation should be a valid Grafana role (`Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to [Configure role mapping]({{< relref "#configure-role-mapping" >}}). | |
|
||||
| `role_attribute_strict` | No | Set to `true` to deny user login if the Grafana role cannot be extracted using `role_attribute_path`. For more information on user role mapping, refer to [Configure role mapping]({{< relref "#configure-role-mapping" >}}). | `false` |
|
||||
| `allow_assign_grafana_admin` | No | Set to `true` to enable automatic sync of the Grafana server administrator role. If this option is set to `true` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user the server administrator privileges and organization administrator role. If this option is set to `false` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user only organization administrator role. For more information on user role mapping, refer to [Configure role mapping]({{< relref "#configure-role-mapping" >}}). | `false` |
|
||||
| `skip_org_role_sync` | No | Set to `true` to stop automatically syncing user roles. This will allow you to set organization roles for your users from within Grafana manually. | `false` |
|
||||
| `groups_attribute_path` | No | [JMESPath](http://jmespath.org/examples.html) expression to use for user group lookup. Grafana will first evaluate the expression using the OAuth2 ID token. If no groups are found, the expression will be evaluated using the user information obtained from the UserInfo endpoint. The result of the evaluation should be a string array of groups. | |
|
||||
| `allowed_groups` | No | List of comma- or space-separated groups. The user should be a member of at least one group to log in. If you configure `allowed_groups`, you must also configure `groups_attribute_path`. | |
|
||||
| `allowed_organizations` | No | List of comma- or space-separated organizations. The user should be a member of at least one organization to log in. | |
|
||||
| `allowed_domains` | No | List comma- or space-separated domains. The user should belong to at least one domain to log in. | |
|
||||
| `team_ids` | No | String list of team IDs. If set, the user must be a member of one of the given teams to log in. If you configure `team_ids`, you must also configure `teams_url` and `team_ids_attribute_path`. | |
|
||||
| `team_ids_attribute_path` | No | The [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana team ID lookup within the results returned by the `teams_url` endpoint. | |
|
||||
| `teams_url` | No | The URL used to query for team IDs. If not set, the default value is `/teams`. If you configure `teams_url`, you must also configure `team_ids_attribute_path`. | |
|
||||
| `tls_skip_verify_insecure` | No | If set to `true`, the client accepts any certificate presented by the server and any host name in that certificate. _You should only use this for testing_, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks. | `false` |
|
||||
| `tls_client_cert` | No | The path to the certificate. | |
|
||||
| `tls_client_key` | No | The path to the key. | |
|
||||
| `tls_client_ca` | No | The path to the trusted certificate authority list. | |
|
||||
| `use_pkce` | No | Set to `true` to use [Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636). Grafana uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier. | `false` |
|
||||
|
||||
### PKCE
|
||||
### Configure login
|
||||
|
||||
> Available in Grafana v8.3 and later versions.
|
||||
Grafana can resolve a user's login from the OAuth2 ID token or user information retrieved from the OAuth2 UserInfo endpoint.
|
||||
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.
|
||||
|
||||
IETF's [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)
|
||||
introduces "proof key for code exchange" (PKCE) which provides
|
||||
additional protection against some forms of authorization code
|
||||
interception attacks. PKCE will be required in [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-03).
|
||||
Refer to the following table for information on what to configure based on how your Oauth2 provider returns a user's login:
|
||||
|
||||
You can enable PKCE in Grafana by setting `use_pkce` to `true` in the
|
||||
`[auth.generic_oauth]` section.
|
||||
| Source of login | Required configuration |
|
||||
| ------------------------------------------------------------------------------- | ------------------------------------------------ |
|
||||
| `login` or `username` field of the OAuth2 ID token. | N/A |
|
||||
| Another field of the OAuth2 ID token. | Set `login_attribute_path` configuration option. |
|
||||
| `login` or `username` field of the user information from the UserInfo endpoint. | N/A |
|
||||
| Another field of the user information from the UserInfo endpoint. | Set `login_attribute_path` configuration option. |
|
||||
|
||||
```
|
||||
use_pkce = true
|
||||
```
|
||||
### Configure display name
|
||||
|
||||
Grafana always uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier.
|
||||
Grafana can resolve a user's display name from the OAuth2 ID token or user information retrieved from the OAuth2 UserInfo endpoint.
|
||||
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.
|
||||
|
||||
### Configure refresh token
|
||||
Refer to the following table for information on what you need to configure depending on how your Oauth2 provider returns a user's name:
|
||||
|
||||
> Available in Grafana v9.3 and later versions.
|
||||
| Source of display name | Required configuration |
|
||||
| ---------------------------------------------------------------------------------- | ----------------------------------------------- |
|
||||
| `name` or `display_name` field of the OAuth2 ID token. | N/A |
|
||||
| Another field of the OAuth2 ID token. | Set `name_attribute_path` configuration option. |
|
||||
| `name` or `display_name` field of the user information from the UserInfo endpoint. | N/A |
|
||||
| Another field of the user information from the UserInfo endpoint. | Set `name_attribute_path` configuration option. |
|
||||
|
||||
### 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, 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:
|
||||
|
||||
| Source of email address | Required configuration |
|
||||
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
||||
| `email` field of the OAuth2 ID token. | N/A |
|
||||
| `attributes` map of the OAuth2 ID token. | Set `email_attribute_name` configuration option. By default, Grafana searches for email under `email:primary` key. |
|
||||
| `upn` field of the OAuth2 ID token. | N/A |
|
||||
| `email` field of the user information from the UserInfo endpoint. | N/A |
|
||||
| Another field of the user information from the UserInfo endpoint. | Set `email_attribute_path` configuration option. |
|
||||
| Email address marked as primary from the `/emails` endpoint of <br /> the OAuth2 provider (obtained by appending `/emails` to the URL <br /> configured with `api_url`) | N/A |
|
||||
|
||||
## Configure a refresh token
|
||||
|
||||
> **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.
|
||||
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, perform one or both of the following tasks, if required:
|
||||
To configure generic OAuth2 to use a refresh token, perform one or both of the following steps, if required:
|
||||
|
||||
- Extend the `[auth.generic_oauth]` section with additional scopes
|
||||
- Enable the refresh token on the provider
|
||||
1. Extend the `scopes` field of `[auth.generic_oauth]` section in Grafana configuration file with additional scopes.
|
||||
1. Enable the refresh token on the provider.
|
||||
|
||||
### Configure automatic login
|
||||
## Configure role mapping
|
||||
|
||||
Set `auto_login` option to true to attempt login automatically, skipping the login screen.
|
||||
This setting is ignored if multiple auth providers are configured to use auto login.
|
||||
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.
|
||||
|
||||
```
|
||||
auto_login = true
|
||||
```
|
||||
The user's role is retrieved using a [JMESPath](http://jmespath.org/examples.html) 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]({{< relref "#configuration-options" >}}) for more information.
|
||||
|
||||
## Set up OAuth2 with Auth0
|
||||
If no valid role is found, 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`.
|
||||
This setting denies user access if no role or an invalid role is returned.
|
||||
|
||||
1. Use the following parameters to create a client in Auth0:
|
||||
To ease configuration of a proper JMESPath expression, go to [JMESPath](http://jmespath.org/) to test and evaluate expressions with custom payloads.
|
||||
|
||||
- Name: Grafana
|
||||
- Type: Regular Web Application
|
||||
### Role mapping examples
|
||||
|
||||
1. Go to the Settings tab and set:
|
||||
|
||||
- Allowed Callback URLs: `https://<grafana domain>/login/generic_oauth`
|
||||
|
||||
1. Click Save Changes, then use the values at the top of the page to configure Grafana:
|
||||
|
||||
```bash
|
||||
[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
|
||||
```
|
||||
|
||||
## Set up OAuth2 with Bitbucket
|
||||
|
||||
```bash
|
||||
[auth.generic_oauth]
|
||||
name = BitBucket
|
||||
enabled = true
|
||||
allow_sign_up = true
|
||||
auto_login = false
|
||||
client_id = <client id>
|
||||
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 =
|
||||
```
|
||||
|
||||
By default, a refresh token is included in the response for the **Authorization Code Grant**.
|
||||
|
||||
## Set up OAuth2 with Centrify
|
||||
|
||||
1. Create a new Custom OpenID Connect application configuration in the Centrify dashboard.
|
||||
|
||||
1. Create a memorable unique Application ID, e.g. "grafana", "grafana_aws", etc.
|
||||
|
||||
1. Put in other basic configuration (name, description, logo, category)
|
||||
|
||||
1. On the Trust tab, generate a long password and put it into the OpenID Connect Client Secret field.
|
||||
|
||||
1. Put the URL to the front page of your Grafana instance into the "Resource Application URL" field.
|
||||
|
||||
1. Add an authorized Redirect URI like https://your-grafana-server/login/generic_oauth
|
||||
|
||||
1. Set up permissions, policies, etc. just like any other Centrify app
|
||||
|
||||
1. Configure Grafana as follows:
|
||||
|
||||
```bash
|
||||
[auth.generic_oauth]
|
||||
name = Centrify
|
||||
enabled = true
|
||||
allow_sign_up = true
|
||||
auto_login = false
|
||||
client_id = <OpenID Connect Client ID from Centrify>
|
||||
client_secret = <your generated OpenID Connect Client Secret>
|
||||
scopes = openid profile email
|
||||
auth_url = https://<your domain>.my.centrify.com/OAuth2/Authorize/<Application ID>
|
||||
token_url = https://<your domain>.my.centrify.com/OAuth2/Token/<Application ID>
|
||||
api_url = https://<your domain>.my.centrify.com/OAuth2/UserInfo/<Application ID>
|
||||
```
|
||||
|
||||
By default, a refresh token is included in the response for the **Authorization Code Grant**.
|
||||
|
||||
## Set up OAuth2 with OneLogin
|
||||
|
||||
1. Create a new Custom Connector 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`
|
||||
|
||||
then:
|
||||
|
||||
1. Add an App to the Grafana Connector:
|
||||
|
||||
- Display Name: Grafana
|
||||
|
||||
then:
|
||||
|
||||
1. Under the SSO tab on the Grafana App details page you'll find the Client ID and Client Secret.
|
||||
|
||||
Your OneLogin Domain will match the URL you use to access OneLogin.
|
||||
|
||||
Configure Grafana as follows:
|
||||
|
||||
```bash
|
||||
[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 =
|
||||
```
|
||||
|
||||
## Role 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. The JMESPath is applied to the `id_token` first. If there is no match, then the UserInfo endpoint specified via the `api_url` configuration option is tried next. The result after evaluation of the `role_attribute_path` JMESPath expression should be a valid Grafana role, for example, `Viewer`, `Editor` or `Admin`.
|
||||
|
||||
For more information, refer to the [JMESPath examples](#jmespath-examples).
|
||||
|
||||
{{% admonition type="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 `skip_org_role_sync` option.
|
||||
See [Configure Grafana]({{< relref "../../../configure-grafana#authgeneric_oauth" >}}) for more information.
|
||||
{{% /admonition %}}
|
||||
|
||||
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.
|
||||
|
||||
{{% admonition type="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" >}}).
|
||||
{{% /admonition %}}
|
||||
|
||||
### JMESPath examples
|
||||
This section includes examples of JMESPath expressions used for role mapping.
|
||||
|
||||
#### Map user organization role
|
||||
|
||||
To ease configuration of a proper JMESPath expression, you can test/evaluate expressions with custom payloads at http://jmespath.org/.
|
||||
|
||||
**Basic example:**
|
||||
|
||||
In the following example user will get `Editor` as role when authenticating. The value of the property `role` will be the resulting role if the role is a proper Grafana role, i.e. `Viewer`, `Editor` or `Admin`.
|
||||
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 `Viewer`, `Editor` or `Admin`.
|
||||
|
||||
Payload:
|
||||
|
||||
@ -330,9 +214,8 @@ Config:
|
||||
role_attribute_path = role
|
||||
```
|
||||
|
||||
**Advanced example:**
|
||||
|
||||
In the following example user will get `Admin` as role when authenticating since it has a role `admin`. If a user has a role `editor` it will get `Editor` as role, otherwise `Viewer`.
|
||||
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:
|
||||
|
||||
@ -341,7 +224,7 @@ Payload:
|
||||
...
|
||||
"info": {
|
||||
...
|
||||
"roles": [
|
||||
"groups": [
|
||||
"engineer",
|
||||
"admin",
|
||||
],
|
||||
@ -354,41 +237,50 @@ Payload:
|
||||
Config:
|
||||
|
||||
```bash
|
||||
role_attribute_path = contains(info.roles[*], 'admin') && 'Admin' || contains(info.roles[*], 'editor') && 'Editor' || 'Viewer'
|
||||
role_attribute_path = contains(info.groups[*], 'admin') && 'Admin' || contains(info.groups[*], 'editor') && 'Editor' || 'Viewer'
|
||||
```
|
||||
|
||||
#### Map server administrator privileges
|
||||
#### Map server administrator role
|
||||
|
||||
> Available in Grafana v9.2 and later versions.
|
||||
In the following example, the user is granted the Grafana server administrator role.
|
||||
|
||||
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.
|
||||
Payload:
|
||||
|
||||
The setting `allow_assign_grafana_admin` under `[auth.generic_oauth]` 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
|
||||
```json
|
||||
{
|
||||
...
|
||||
"info": {
|
||||
...
|
||||
"roles": [
|
||||
"admin",
|
||||
],
|
||||
...
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Example:
|
||||
Config:
|
||||
|
||||
```ini
|
||||
role_attribute_path = contains(info.roles[*], 'admin') && 'GrafanaAdmin' || contains(info.roles[*], 'editor') && 'Editor' || 'Viewer'
|
||||
allow_assign_grafana_admin = true
|
||||
```
|
||||
|
||||
## Team synchronization
|
||||
## Configure team synchronization
|
||||
|
||||
> Available in Grafana Enterprise v8.1 and later versions.
|
||||
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise" >}}) and [Grafana Cloud](/docs/grafana-cloud/).
|
||||
|
||||
With Team Sync you can map your Generic OAuth groups to teams in Grafana so that the users are automatically added to the correct teams.
|
||||
By using Team Sync, you can link your OAuth2 groups to teams within Grafana. This will automatically assign users to the appropriate teams.
|
||||
|
||||
Generic OAuth groups can be referenced by group ID, like `8bab1c86-8fba-33e5-2089-1d1c80ec267d` or `myteam`.
|
||||
Generic OAuth2 groups can be referenced by group ID, such as `8bab1c86-8fba-33e5-2089-1d1c80ec267d` or `myteam`.
|
||||
For information on configuring OAuth2 groups with Grafana using the `groups_attribute_path` configuration option, refer to [configuration options]({{< relref "#configuration-options" >}}).
|
||||
|
||||
[Learn more about Team Sync]({{< relref "../../configure-team-sync" >}})
|
||||
To learn more about Team Sync, refer to [Configure team sync]({{< relref "../../configure-team-sync" >}}).
|
||||
|
||||
Config:
|
||||
### Team synchronization example
|
||||
|
||||
Configuration:
|
||||
|
||||
```bash
|
||||
groups_attribute_path = info.groups
|
||||
@ -411,15 +303,108 @@ Payload:
|
||||
}
|
||||
```
|
||||
|
||||
## Skip organization role sync
|
||||
## Examples of setting up generic OAuth2
|
||||
|
||||
To prevent the sync of organization roles from the OAuth provider, set `skip_org_role_sync` to `true`. This is useful if you want to manage the organization roles for your users from within Grafana.
|
||||
This also impacts the `allow_assign_grafana_admin` setting by not syncing the Grafana admin role from the OAuth provider.
|
||||
This section includes examples of setting up generic OAuth2 integration.
|
||||
|
||||
```ini
|
||||
[auth.generic_oauth]
|
||||
# ..
|
||||
# prevents the sync of org roles from the Oauth provider
|
||||
skip_org_role_sync = true
|
||||
``
|
||||
```
|
||||
### Set up OAuth2 with Auth0
|
||||
|
||||
To set up generic OAuth2 authentication with Auth0, follow these steps:
|
||||
|
||||
1. Create an Auth0 application using the following parameters:
|
||||
|
||||
- Name: Grafana
|
||||
- Type: Regular Web Application
|
||||
|
||||
1. Go to the **Settings** tab of the application and set **Allowed Callback URLs** to `https://<grafana domain>/login/generic_oauth`.
|
||||
|
||||
1. Click **Save Changes**.
|
||||
|
||||
1. Update the `[auth.generic_oauth]` section of the Grafana configuration file using the values from the **Settings** tab:
|
||||
|
||||
```bash
|
||||
[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
|
||||
```
|
||||
|
||||
### Set up OAuth2 with Bitbucket
|
||||
|
||||
To set up generic OAuth2 authentication with Bitbucket, follow these steps:
|
||||
|
||||
1. Navigate to **Settings > Workspace setting > OAuth consumers** in BitBucket.
|
||||
|
||||
1. Create an application by selecting **Add consumer** and using the following parameters:
|
||||
|
||||
- Allowed Callback URLs: `https://<grafana domain>/login/generic_oauth`
|
||||
|
||||
1. Click **Save**.
|
||||
|
||||
1. Update the `[auth.generic_oauth]` section of the Grafana configuration file using the values from the `Key` and `Secret` from the consumer description:
|
||||
|
||||
```bash
|
||||
[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 =
|
||||
```
|
||||
|
||||
By default, a refresh token is included in the response for the **Authorization Code Grant**.
|
||||
|
||||
### Set up OAuth2 with OneLogin
|
||||
|
||||
To set up generic OAuth2 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`
|
||||
|
||||
1. Add an app to the Grafana Connector:
|
||||
|
||||
- Display Name: Grafana
|
||||
|
||||
1. 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.
|
||||
|
||||
```bash
|
||||
[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 =
|
||||
```
|
||||
|
||||
@ -122,7 +122,7 @@ then the user is assigned the role specified by
|
||||
[the `auto_assign_org_role` option]({{< relref "../../../configure-grafana#auto_assign_org_role" >}}).
|
||||
{{% /admonition %}}
|
||||
|
||||
Read about how to [add custom claims](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/add-custom-claim/) to the user info in Okta. Also, check Generic OAuth page for [JMESPath examples]({{< relref "../generic-oauth#jmespath-examples" >}}).
|
||||
Read about how to [add custom claims](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/add-custom-claim/) to the user info in Okta. Also, check Generic OAuth page for [Role mapping examples]({{< relref "../generic-oauth#role-mapping-examples" >}}) with JMESPath.
|
||||
|
||||
#### Map server administrator privileges
|
||||
|
||||
|
||||
9
docs/sources/shared/auth/intro.md
Normal file
9
docs/sources/shared/auth/intro.md
Normal file
@ -0,0 +1,9 @@
|
||||
---
|
||||
title: Intro paragraph
|
||||
---
|
||||
|
||||
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]({{< relref "/docs/grafana/latest/setup-grafana/configure-security/configure-authentication" >}}).
|
||||
Loading…
Reference in New Issue
Block a user