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:
Misi
GitHub
+96
-49
@@ -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` |
|
||||
|
||||
Reference in New Issue
Block a user