IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Setup OAuth providers using the SSO Settings UI (#81589)

Browse Source 
* initial changes for generic_oauth, okta

* updates

* add terraform examples for each provider

* add link to terraform registry for grafana_sso_settings resource

* remove auth_url, token_url and api_url from github, gitlab and google

* Add documentation for enabling email lookup

* Apply suggestions from code review

Co-authored-by: lwandz13 <126723338+lwandz13@users.noreply.github.com>

* Address review feedback

* Update TF provider version

* Apply suggestions from code review

Co-authored-by: lwandz13 <126723338+lwandz13@users.noreply.github.com>

* Use Azure AD for now

---------

Co-authored-by: Mihai Doarna <mihai.doarna@grafana.com>
Co-authored-by: lwandz13 <126723338+lwandz13@users.noreply.github.com>
This commit is contained in:
Misi 2024-02-16 17:24:42 +01:00 committed by GitHub
parent f71f54c872
commit bc8952b9f1
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
7 changed files with 549 additions and 242 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/sources/setup-grafana/configure-security/configure-authentication/_index.md
View File

@ -76,6 +76,12 @@ In scenarios where you have multiple identity providers of the same type, there
- Check if the identity provider supports account federation. In such cases, you can configure it once and let your identity provider federate the accounts from different providers.
- If SAML is supported by the identity provider, you can configure one [Generic OAuth]({{< relref "./generic-oauth" >}}) and one [SAML]({{< relref "./saml" >}}) (Enterprise only).
## Using the same email address to login with different identity providers
If users want to use the same email address with multiple identity providers (for example, Grafana.Com OAuth and Google OAuth), you can configure Grafana to use the email address as the unique identifier for the user. This is done by enabling the `oauth_allow_insecure_email_lookup` option, which is disabled by default. Please note that enabling this option can lower the security of your Grafana instance. If you enable this option, you should also ensure that the `Allowed organization`, `Allowed groups` and `Allowed domains` settings are configured correctly to prevent unauthorized access.
To enable this option, refer to the [Enable email lookup](#enable-email-lookup) section.
## Grafana Auth
Grafana of course has a built in user authentication system with password authentication enabled by default. You can
@ -178,6 +184,20 @@ We strongly recommend against enabling email lookups, however it is possible to
oauth_allow_insecure_email_lookup = true
```
You can also enable email lookup using the API:
{{% admonition type="note" %}}
Available in [Grafana Enterprise]({{< relref "../../../introduction/grafana-enterprise" >}}) and [Grafana Cloud]({{< relref "../../../introduction/grafana-cloud" >}}) since Grafana v10.4.
{{% /admonition %}}
```
curl --request PUT \
--url http://{slug}.grafana.com/api/admin/settings \
--header 'Authorization: Bearer glsa_yourserviceaccounttoken' \
--header 'Content-Type: application/json' \
--data '{ "updates": { "auth": { "oauth_allow_insecure_email_lookup": "true" }}}'
```
### Automatic OAuth login
Set to true to attempt login with specific OAuth provider automatically, skipping the login screen.

61
docs/sources/setup-grafana/configure-security/configure-authentication/azuread/index.md
View File

@ -58,7 +58,7 @@ To enable the Azure AD OAuth2, register your application with Azure AD.
1. Click **Users and Groups**.
1. Click **Add user/group** to add a user or group to the Grafana roles.
#### Configure application roles for Grafana in the Azure Portal
### Configure application roles for Grafana in the Azure Portal
This section describes setting up basic application roles for Grafana within the Azure Portal. For more information, see [Add app roles to your application and receive them in the token](https://learn.microsoft.com/en-us/entra/identity-platform/howto-add-app-roles-in-apps).
@ -78,7 +78,7 @@ This section describes setting up basic application roles for Grafana within the
1. Click **Apply**.
#### Configure application roles for Grafana in the manifest file
### Configure application roles for Grafana in the manifest file
If you prefer to configure the application roles for Grafana in the manifest file, complete the following steps:
@ -161,7 +161,60 @@ If the setting is set to `false`, the user is assigned the role of `Admin` of th
}
```
## Enable Azure AD OAuth in Grafana
## Before you begin
Ensure that you have followed the steps in [Create the Azure AD application](#create-the-azure-ad-application) before you begin.
## Configure Azure AD authentication client using the Grafana UI
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle.
{{% /admonition %}}
As a Grafana Admin, you can configure your Azure AD OAuth2 client from within Grafana using the GitLab UI. To do this, navigate to **Administration > Authentication > Azure AD** 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** 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 %}}
## Configure Azure AD authentication client using the Terraform provider
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle. Supported in the Terraform provider since v2.12.0.
{{% /admonition %}}
```terraform
resource "grafana_sso_settings" "azuread_sso_settings" {
provider_name = "azuread"
oauth2_settings {
name = "Azure AD"
auth_url = "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize"
token_url = "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token"
client_id = "APPLICATION_ID"
client_secret = "CLIENT_SECRET"
allow_sign_up = true
auto_login = false
scopes = "openid email profile"
allowed_organizations = "TENANT_ID"
role_attribute_strict = false
allow_assign_grafana_admin = false
skip_org_role_sync = false
use_pkce = true
}
}
```
Refer to [Terraform Registry](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/sso_settings) for a complete reference on using the `grafana_sso_settings` resource.
## Configure Azure AD authentication client using the Grafana configuration file
Ensure that you have access to the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}).
### Enable Azure AD OAuth in Grafana
Add the following to the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}):
@ -340,7 +393,7 @@ Admin consent might be required for this permission.
Admin consent may be required for this permission.
{{% /admonition %}}
### Force fetching groups from Microsoft graph API
### Force fetching groups from Microsoft Graph API
To force fetching groups from Microsoft Graph API instead of the `id_token`. You can use the `force_use_graph_api` config option.

156
docs/sources/setup-grafana/configure-security/configure-authentication/generic-oauth/index.md
View File

@ -33,18 +33,66 @@ Grafana provides OAuth2 integrations for the following auth providers:
If your OAuth2 provider is not listed, you can use generic OAuth2 authentication.
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.
This topic describes how to configure generic OAuth2 authentication using different methods and includes [examples of setting up generic OAuth2]({{< relref "#examples-of-setting-up-generic-oauth2" >}}) with specific OAuth2 providers.
## Before you begin
To follow this guide:
- 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.
- Ensure your identity provider returns OpenID UserInfo compatible information such as `sub` claim.
- 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.
## Steps
## Configure generic OAuth authentication client using the Grafana UI
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle.
{{% /admonition %}}
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.
{{% 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]({{< relref "#configuration-options" >}}) for more information.
## Configure generic OAuth authentication client using the Terraform provider
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle. Supported in the Terraform provider since v2.12.0.
{{% /admonition %}}
```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](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/sso_settings) 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]({{< relref "../../../configure-grafana#configuration-file-location" >}}).
### Steps
To integrate your OAuth2 provider with Grafana using our generic OAuth2 authentication, follow these steps:
@ -80,48 +128,6 @@ To integrate your OAuth2 provider with Grafana using our generic OAuth2 authenti
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.
## Configuration options
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.
| 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` |
| `use_refresh_token` | No | Set to `true` to use refresh token and check access token expiration. | `false` |
### Configure login
Grafana can resolve a user's login from the OAuth2 ID token or user information retrieved from the OAuth2 UserInfo endpoint.
@ -169,7 +175,7 @@ Refer to the following table for information on what to configure based on how t
| 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
### Configure a refresh token
> **Note:** This feature is behind the `accessTokenExpirationCheck` feature toggle.
@ -184,7 +190,7 @@ To configure generic OAuth2 to use a refresh token, set `use_refresh_token` conf
> **Note:** The `accessTokenExpirationCheck` feature toggle will be 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.
## Configure role mapping
### 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.
@ -198,11 +204,11 @@ This setting denies user access if no role or an invalid role is returned.
To ease configuration of a proper JMESPath expression, go to [JMESPath](http://jmespath.org/) to test and evaluate expressions with custom payloads.
### Role mapping examples
#### Role mapping examples
This section includes examples of JMESPath expressions used for role mapping.
#### Map user organization role
##### 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`.
@ -248,7 +254,7 @@ Config:
role_attribute_path = contains(info.groups[*], 'admin') && 'Admin' || contains(info.groups[*], 'editor') && 'Editor' || 'Viewer'
```
#### Map server administrator role
##### Map server administrator role
In the following example, the user is granted the Grafana server administrator role.
@ -275,7 +281,7 @@ role_attribute_path = contains(info.roles[*], 'admin') && 'GrafanaAdmin' || cont
allow_assign_grafana_admin = true
```
#### Map one role to all users
##### 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.
@ -286,7 +292,7 @@ role_attribute_path = "'Viewer'"
skip_org_role_sync = false
```
## Configure team synchronization
### Configure team synchronization
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise" >}}) and [Grafana Cloud](/docs/grafana-cloud/).
@ -298,7 +304,7 @@ For information on configuring OAuth2 groups with Grafana using the `groups_attr
To learn more about Team Sync, refer to [Configure team sync]({{< relref "../../configure-team-sync" >}}).
### Team synchronization example
#### Team synchronization example
Configuration:
@ -323,6 +329,48 @@ Payload:
}
```
## Configuration options
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.
| 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` |
| `use_refresh_token` | No | Set to `true` to use refresh token and check access token expiration. | `false` |
## Examples of setting up generic OAuth2
This section includes examples of setting up generic OAuth2 integration.

237
docs/sources/setup-grafana/configure-security/configure-authentication/github/index.md
View File

@ -25,12 +25,57 @@ This topic describes how to configure GitHub OAuth2 authentication.
## Before you begin
To follow this guide:
Ensure you know how to create a GitHub OAuth app. Consult GitHub's documentation on [creating an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) for more information.
- Ensure that you have access to the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}).
- Ensure you know how to create a GitHub OAuth app. Consult GitHub's documentation on [creating an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) for more information.
## Configure GitHub authentication client using the Grafana UI
## Steps
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle.
{{% /admonition %}}
As a Grafana Admin, you can configure GitHub OAuth2 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]({{< relref "#configuration-options" >}}) for more information.
## Configure GitHub authentication client using the Terraform provider
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle. Supported in the Terraform provider since v2.12.0.
{{% /admonition %}}
```terraform
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](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/sso_settings) 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]({{< relref "../../../configure-grafana#configuration-file-location" >}}).
### Configure GitHub authentication
To configure GitHub authentication with Grafana, follow these steps:
@ -56,6 +101,99 @@ To configure GitHub authentication with Grafana, follow these steps:
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 `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](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.
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.
To ease configuration of a proper JMESPath expression, go to [JMESPath](http://jmespath.org/) to test and evaluate expressions with custom payloads.
#### Role mapping examples
This section includes examples of JMESPath expressions used for role mapping.
##### 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.
```bash
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.
```bash
role_attribute_path = contains(groups[*], '@my-github-organization/my-github-team') && 'Editor' || 'Viewer'
```
#### 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.
```bash
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.
```ini
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.
```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
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]({{< relref "../../../../introduction/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]({{< relref "../../configure-team-sync" >}}).
## Configuration options
The table below describes all GitHub OAuth configuration options. Like any other Grafana configuration, you can apply these options as environment variables.
@ -84,94 +222,3 @@ The table below describes all GitHub OAuth configuration options. Like any other
| `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. | |
## Configure role mapping
Unless `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](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.
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.
To ease configuration of a proper JMESPath expression, go to [JMESPath](http://jmespath.org/) to test and evaluate expressions with custom payloads.
### Role mapping examples
This section includes examples of JMESPath expressions used for role mapping.
#### 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.
```bash
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.
```bash
role_attribute_path = contains(groups[*], '@my-github-organization/my-github-team') && 'Editor' || 'Viewer'
```
### 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.
```bash
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.
```ini
role_attribute_path = "'Viewer'"
skip_org_role_sync = false
```
## Configure team synchronization
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise" >}}) and [Grafana Cloud](/docs/grafana-cloud/).
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>`
For example, `https://github.com/orgs/grafana/teams/developers` or `@grafana/developers`.
To learn more about Team Sync, refer to [Configure team sync]({{< relref "../../configure-team-sync" >}}).
## Example of GitHub configuration in Grafana
This section includes an example of GitHub configuration in the Grafana configuration file.
```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
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'
```

145
docs/sources/setup-grafana/configure-security/configure-authentication/gitlab/index.md
View File

@ -25,12 +25,59 @@ This topic describes how to configure GitLab OAuth2 authentication.
## Before you begin
To follow this guide:
Ensure you know how to create a GitLab OAuth application. Consult GitLab's documentation on [creating a GitLab OAuth application](https://docs.gitlab.com/ee/integration/oauth_provider.html) for more information.
- Ensure that you have access to the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}).
- Ensure you know how to create a GitLab OAuth application. Consult GitLab's documentation on [creating a GitLab OAuth application](https://docs.gitlab.com/ee/integration/oauth_provider.html) for more information.
## Configure GitLab authentication client using the Grafana UI
## Steps
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle.
{{% /admonition %}}
As a Grafana Admin, you can configure GitLab OAuth2 client from within Grafana using the GitLab UI. To do this, navigate to **Administration > Authentication > GitLab** 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]({{< relref "#configuration-options" >}}) for more information.
## Configure GitLab authentication client using the Terraform provider
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle. Supported in the Terraform provider since v2.12.0.
{{% /admonition %}}
```terraform
resource "grafana_sso_settings" "gitlab_sso_settings" {
provider_name = "gitlab"
oauth2_settings {
name = "Gitlab"
client_id = "YOUR_GITLAB_APPLICATION_ID"
client_secret = "YOUR_GITLAB_APPLICATION_SECRET"
allow_sign_up = true
auto_login = false
scopes = "openid email profile"
allowed_domains = "mycompany.com mycompany.org"
role_attribute_path = "contains(groups[*], 'example-group') && 'Editor' || 'Viewer'"
role_attribute_strict = false
allowed_groups = "[\"admins\", \"software engineers\", \"developers/frontend\"]"
use_pkce = true
use_refresh_token = true
}
}
```
Go to [Terraform Registry](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/sso_settings) for a complete reference on using the `grafana_sso_settings` resource.
## Configure GitLab authentication client using the Grafana configuration file
Ensure that you have access to the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}).
### Steps
To configure GitLab authentication with Grafana, follow these steps:
@ -63,36 +110,6 @@ To configure GitLab authentication with Grafana, follow these steps:
You should now see a GitLab login button on the login page and be able to log in or sign up with your GitLab accounts.
## Configuration options
The table below describes all GitLab OAuth configuration options. Like any other Grafana configuration, you can apply these options as environment variables.
| Setting | Required | Description | Default |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `enabled` | Yes | Whether GitLab OAuth authentication is allowed. | `false` |
| `client_id` | Yes | Client ID provided by your GitLab OAuth app. | |
| `client_secret` | Yes | Client secret provided by your GitLab OAuth app. | |
| `auth_url` | Yes | Authorization endpoint of your GitLab OAuth provider. If you use your own instance of GitLab instead of gitlab.com, adjust `auth_url` by replacing the `gitlab.com` hostname with your own. | `https://gitlab.com/oauth/authorize` |
| `token_url` | Yes | Endpoint used to obtain GitLab OAuth access token. If you use your own instance of GitLab instead of gitlab.com, adjust `token_url` by replacing the `gitlab.com` hostname with your own. | `https://gitlab.com/oauth/token` |
| `api_url` | No | Grafana uses `<api_url>/user` endpoint to obtain GitLab user information compatible with [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo). | `https://gitlab.com/api/v4` |
| `name` | No | Name used to refer to the GitLab authentication in the Grafana user interface. | `GitLab` |
| `icon` | No | Icon used for GitLab authentication in the Grafana user interface. | `gitlab` |
| `scopes` | No | List of comma or space-separated GitLab OAuth scopes. | `openid email profile` |
| `allow_sign_up` | No | Whether to allow new Grafana user creation through GitLab login. If set to `false`, then only existing Grafana users can log in with GitLab OAuth. | `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` |
| `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 GitLab OAuth token. If no role is found, Grafana creates a JSON data with `groups` key that maps to groups obtained from GitLab's `/oauth/userinfo` endpoint, and evaluates the expression using this data. Finally, if a valid role is still not found, the expression is evaluated against the user information retrieved from `api_url/users` endpoint and groups retrieved from `api_url/groups` 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. | `false` |
| `allowed_domains` | No | List of comma or space-separated domains. User must belong to at least one domain to log in. | |
| `allowed_groups` | No | List of comma or space-separated groups. The user should be a member of at least one group to log in. | |
| `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. | `true` |
| `use_refresh_token` | No | Set to `true` to use refresh token and check access token expiration. The `accessTokenExpirationCheck` feature toggle should also be enabled to use refresh token. | `true` |
### Configure a refresh token
> Available in Grafana v9.3 and later versions.
@ -119,7 +136,7 @@ GitLab's groups are referenced by the group name. For example, `developers`. To
Note that in GitLab, the group or subgroup name does not always match its display name, especially if the display name contains spaces or special characters.
Make sure you always use the group or subgroup name as it appears in the URL of the group or subgroup.
## Configure role mapping
### Configure role mapping
Unless `skip_org_role_sync` option is enabled, the user's role will be set to the role retrieved from GitLab upon user login.
@ -173,20 +190,7 @@ role_attribute_path = "'Viewer'"
skip_org_role_sync = false
```
## Configure team synchronization
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise" >}}) and [Grafana Cloud](/docs/grafana-cloud/).
By using Team Sync, you can map GitLab 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.
GitLab groups are referenced by the group name. For example, `developers`. To reference a subgroup `frontend`, use `developers/frontend`.
Note that in GitLab, the group or subgroup name does not always match its display name, especially if the display name contains spaces or special characters.
Make sure you always use the group or subgroup name as it appears in the URL of the group or subgroup.
To learn more about Team Sync, refer to [Configure team sync]({{< relref "../../configure-team-sync" >}}).
## Example of GitLab configuration in Grafana
### Example of GitLab configuration in Grafana
This section includes an example of GitLab configuration in the Grafana configuration file.
@ -210,3 +214,46 @@ tls_skip_verify_insecure = false
use_pkce = true
use_refresh_token = true
```
## Configure team synchronization
> **Note:** Available in [Grafana Enterprise]({{< relref "../../../../introduction/grafana-enterprise" >}}) and [Grafana Cloud](/docs/grafana-cloud/).
By using Team Sync, you can map GitLab 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.
GitLab groups are referenced by the group name. For example, `developers`. To reference a subgroup `frontend`, use `developers/frontend`.
Note that in GitLab, the group or subgroup name does not always match its display name, especially if the display name contains spaces or special characters.
Make sure you always use the group or subgroup name as it appears in the URL of the group or subgroup.
To learn more about Team Sync, refer to [Configure team sync]({{< relref "../../configure-team-sync" >}}).
## Configuration options
The table below describes all GitLab OAuth configuration options. Like any other Grafana configuration, you can apply these options as environment variables.
| Setting | Required | Description | Default |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `enabled` | Yes | Whether GitLab OAuth authentication is allowed. | `false` |
| `client_id` | Yes | Client ID provided by your GitLab OAuth app. | |
| `client_secret` | Yes | Client secret provided by your GitLab OAuth app. | |
| `auth_url` | Yes | Authorization endpoint of your GitLab OAuth provider. If you use your own instance of GitLab instead of gitlab.com, adjust `auth_url` by replacing the `gitlab.com` hostname with your own. | `https://gitlab.com/oauth/authorize` |
| `token_url` | Yes | Endpoint used to obtain GitLab OAuth access token. If you use your own instance of GitLab instead of gitlab.com, adjust `token_url` by replacing the `gitlab.com` hostname with your own. | `https://gitlab.com/oauth/token` |
| `api_url` | No | Grafana uses `<api_url>/user` endpoint to obtain GitLab user information compatible with [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo). | `https://gitlab.com/api/v4` |
| `name` | No | Name used to refer to the GitLab authentication in the Grafana user interface. | `GitLab` |
| `icon` | No | Icon used for GitLab authentication in the Grafana user interface. | `gitlab` |
| `scopes` | No | List of comma or space-separated GitLab OAuth scopes. | `openid email profile` |
| `allow_sign_up` | No | Whether to allow new Grafana user creation through GitLab login. If set to `false`, then only existing Grafana users can log in with GitLab OAuth. | `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` |
| `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 GitLab OAuth token. If no role is found, Grafana creates a JSON data with `groups` key that maps to groups obtained from GitLab's `/oauth/userinfo` endpoint, and evaluates the expression using this data. Finally, if a valid role is still not found, the expression is evaluated against the user information retrieved from `api_url/users` endpoint and groups retrieved from `api_url/groups` 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. | `false` |
| `allowed_domains` | No | List of comma or space-separated domains. User must belong to at least one domain to log in. | |
| `allowed_groups` | No | List of comma or space-separated groups. The user should be a member of at least one group to log in. | |
| `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. | `true` |
| `use_refresh_token` | No | Set to `true` to use refresh token and check access token expiration. The `accessTokenExpirationCheck` feature toggle should also be enabled to use refresh token. | `true` |

67
docs/sources/setup-grafana/configure-security/configure-authentication/google/index.md
View File

@ -31,7 +31,52 @@ First, you need to create a Google OAuth Client:
1. Click Create
1. Copy the Client ID and Client Secret from the 'OAuth Client' modal
## Enable Google OAuth in Grafana
## Configure Google authentication client using the Grafana UI
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle.
{{% /admonition %}}
As a Grafana Admin, you can configure Google OAuth2 client from within Grafana using the Google UI. To do this, navigate to **Administration > Authentication > Google** 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**. If the save was successful, Grafana will apply the new configurations.
If you need to reset changes 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 %}}
## Configure Google authentication client using the Terraform provider
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle. Supported in the Terraform provider since v2.12.0.
{{% /admonition %}}
```terraform
resource "grafana_sso_settings" "google_sso_settings" {
provider_name = "google"
oauth2_settings {
name = "Google"
client_id = "CLIENT_ID"
client_secret = "CLIENT_SECRET"
allow_sign_up = true
auto_login = false
scopes = "openid email profile"
allowed_domains = "mycompany.com mycompany.org"
hosted_domain = "mycompany.com"
use_pkce = true
}
}
```
Go to [Terraform Registry](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/sso_settings) for a complete reference on using the `grafana_sso_settings` resource.
## Configure Google authentication client using the Grafana configuration file
Ensure that you have access to the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}).
### Enable Google OAuth in Grafana
Specify the Client ID and Secret in the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}). For example:
@ -66,7 +111,7 @@ automatically signed up.
You may specify a domain to be passed as `hd` query parameter accepted by Google's
OAuth 2.0 authentication API. Refer to Google's OAuth [documentation](https://developers.google.com/identity/openid-connect/openid-connect#hd-param).
### PKCE
#### PKCE
IETF's [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)
introduces "proof key for code exchange" (PKCE) which provides
@ -75,7 +120,7 @@ interception attacks. PKCE will be required in [OAuth 2.1](https://datatracker.i
> You can disable PKCE in Grafana by setting `use_pkce` to `false` in the`[auth.google]` section.
### Configure refresh token
#### Configure refresh token
> Available in Grafana v9.3 and later versions.
@ -91,7 +136,7 @@ Refresh token fetching and access token expiration check is enabled by default f
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 automatic login
#### Configure automatic login
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.
@ -123,7 +168,7 @@ With team sync, you can easily add users to teams by utilizing their Google grou
To learn more about Team Sync, refer to [Configure Team Sync]({{< relref "../../configure-team-sync" >}}).
### Configure allowed groups
#### Configure allowed groups
> Available in Grafana v10.2.0 and later versions.
@ -134,7 +179,7 @@ Google groups are referenced by the group email key. For example, `developers@go
> Note: Add the `https://www.googleapis.com/auth/cloud-identity.groups.readonly` scope to your Grafana `[auth.google]` scopes configuration to retrieve groups
## Configure role mapping
#### Configure role mapping
> Available in Grafana v10.2.0 and later versions.
@ -151,11 +196,11 @@ To ease configuration of a proper JMESPath expression, go to [JMESPath](http://j
> By default skip_org_role_sync is enabled. skip_org_role_sync will default to false in Grafana v10.3.0 and later versions.
### Role mapping examples
##### Role mapping examples
This section includes examples of JMESPath expressions used for role mapping.
#### Map roles using user information from OAuth token
###### Map roles using user information from OAuth token
In this example, the user with email `admin@company.com` has been granted the `Admin` role.
All other users are granted the `Viewer` role.
@ -165,7 +210,7 @@ role_attribute_path = email=='admin@company.com' && 'Admin' || 'Viewer'
skip_org_role_sync = false
```
#### Map roles using groups
###### Map roles using groups
In this example, the user from Google group 'example-group@google.com' have been granted the `Editor` role.
All other users are granted the `Viewer` role.
@ -177,7 +222,7 @@ skip_org_role_sync = false
> Note: Add the `https://www.googleapis.com/auth/cloud-identity.groups.readonly` scope to your Grafana `[auth.google]` scopes configuration to retrieve groups
#### Map server administrator role
###### Map server administrator role
In this example, the user with email `admin@company.com` has been granted the `Admin` organization role as well as the Grafana server admin role.
All other users are granted the `Viewer` role.
@ -188,7 +233,7 @@ skip_org_role_sync = false
role_attribute_path = email=='admin@company.com' && 'GrafanaAdmin' || 'Viewer'
```
#### Map one role to all users
###### 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.

105
docs/sources/setup-grafana/configure-security/configure-authentication/okta/index.md
View File

@ -18,12 +18,59 @@ weight: 1400
## Before you begin
To follow this guide:
To follow this guide, ensure you have permissions in your Okta workspace to create an OIDC app.
- Ensure that you have access to the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}).
- Ensure you have permissions in your Okta workspace to create an OIDC app.
## Configure Okta authentication client using the Grafana UI
## Steps
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle.
{{% /admonition %}}
As a Grafana Admin, you can configure Okta OAuth2 client from within Grafana using the Okta UI. To do this, navigate to **Administration > Authentication > Okta** 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**. 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]({{< relref "#configuration-options" >}}) for more information.
## Configure Okta authentication client using the Terraform provider
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle. Supported in the Terraform provider since v2.12.0.
{{% /admonition %}}
```terraform
resource "grafana_sso_settings" "okta_sso_settings" {
provider_name = "okta"
oauth2_settings {
name = "Okta"
auth_url = "https://<okta tenant id>.okta.com/oauth2/v1/authorize"
token_url = "https://<okta tenant id>.okta.com/oauth2/v1/token"
api_url = "https://<okta tenant id>.okta.com/oauth2/v1/userinfo"
client_id = "CLIENT_ID"
client_secret = "CLIENT_SECRET"
allow_sign_up = true
auto_login = false
scopes = "openid profile email offline_access"
role_attribute_path = "contains(groups[*], 'Example::DevOps') && 'Admin' || 'None'"
role_attribute_strict = true
allowed_groups = "Example::DevOps,Example::Dev,Example::QA"
}
}
```
Go to [Terraform Registry](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/sso_settings) for a complete reference on using the `grafana_sso_settings` resource.
## Configure Okta authentication client using the Grafana configuration file
Ensure that you have access to the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}).
### Steps
To integrate your Okta OIDC provider with Grafana using our Okta OIDC integration, follow these steps:
@ -87,31 +134,6 @@ role_attribute_strict = true
allowed_groups = "Example::DevOps" "Example::Dev" "Example::QA"
```
## Configuration options
The following table outlines the various Okta OIDC configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana.
| Setting | Required | Description | Default |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `enabled` | No | Enables Okta OIDC authentication. | `false` |
| `name` | No | Name that refers to the Okta OIDC authentication from the Grafana user interface. | `Okta` |
| `icon` | No | Icon used for the Okta OIDC authentication in the Grafana user interface. | `okta` |
| `client_id` | Yes | Client ID provided by your Okta OIDC app. | |
| `client_secret` | Yes | Client secret provided by your Okta OIDC app. | |
| `auth_url` | Yes | Authorization endpoint of your Okta OIDC provider. | |
| `token_url` | Yes | Endpoint used to obtain the Okta OIDC access token. | |
| `api_url` | Yes | Endpoint used to obtain user information. | |
| `scopes` | No | List of comma- or space-separated Okta OIDC scopes. | `openid profile email groups` |
| `allow_sign_up` | No | Controls Grafana user creation through the Okta OIDC login. Only existing Grafana users can log in with Okta OIDC 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` |
| `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 Okta OIDC 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` |
| `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` |
| `allowed_groups` | No | List of comma- or space-separated groups. The user should be a member of at least one group to log in. | |
| `allowed_domains` | No | List comma- or space-separated domains. The user should belong to at least one domain to log in. | |
| `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. | `true` |
| `use_refresh_token` | No | Set to `true` to use refresh token and check access token expiration. | `false` |
### Configure a refresh token
> Available in Grafana v9.3 and later versions.
@ -157,3 +179,28 @@ the correct teams.
Okta groups can be referenced by group names, like `Admins` or `Editors`.
To learn more about Team Sync, refer to [Configure Team Sync]({{< relref "../../configure-team-sync" >}}).
## Configuration options
The following table outlines the various Okta OIDC configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana.
| Setting | Required | Description | Default |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `enabled` | No | Enables Okta OIDC authentication. | `false` |
| `name` | No | Name that refers to the Okta OIDC authentication from the Grafana user interface. | `Okta` |
| `icon` | No | Icon used for the Okta OIDC authentication in the Grafana user interface. | `okta` |
| `client_id` | Yes | Client ID provided by your Okta OIDC app. | |
| `client_secret` | Yes | Client secret provided by your Okta OIDC app. | |
| `auth_url` | Yes | Authorization endpoint of your Okta OIDC provider. | |
| `token_url` | Yes | Endpoint used to obtain the Okta OIDC access token. | |
| `api_url` | Yes | Endpoint used to obtain user information. | |
| `scopes` | No | List of comma- or space-separated Okta OIDC scopes. | `openid profile email groups` |
| `allow_sign_up` | No | Controls Grafana user creation through the Okta OIDC login. Only existing Grafana users can log in with Okta OIDC 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` |
| `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 Okta OIDC 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` |
| `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` |
| `allowed_groups` | No | List of comma- or space-separated groups. The user should be a member of at least one group to log in. | |
| `allowed_domains` | No | List comma- or space-separated domains. The user should belong to at least one domain to log in. | |
| `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. | `true` |
| `use_refresh_token` | No | Set to `true` to use refresh token and check access token expiration. | `false` |