mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Docs: Setup OAuth providers using the SSO Settings UI (#81589)
* 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:
parent
f71f54c872
commit
bc8952b9f1
@ -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.
|
||||
|
@ -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.
|
||||
|
||||
|
@ -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.
|
||||
|
@ -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'
|
||||
```
|
||||
|
@ -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` |
|
||||
|
@ -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.
|
||||
|
||||
|
@ -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` |
|
||||
|
Loading…
Reference in New Issue
Block a user