diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/azuread/index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/azuread/index.md index 206a641ad6f..48de62a6c9a 100644 --- a/docs/sources/setup-grafana/configure-security/configure-authentication/azuread/index.md +++ b/docs/sources/setup-grafana/configure-security/configure-authentication/azuread/index.md @@ -15,12 +15,21 @@ weight: 600 The Azure AD authentication allows you to use an Azure Active Directory tenant as an identity provider for Grafana. You can use Azure AD Application Roles to assign users and groups to Grafana roles from the Azure Portal. This topic has the following sections: -- [Azure AD OAuth2 authentication](#azure-ad-oauth2-authentication) +- [Configure Azure AD OAuth2 authentication](#configure-azure-ad-oauth2-authentication) - [Create the Azure AD application](#create-the-azure-ad-application) + - [Assign server administrator privileges](#assign-server-administrator-privileges) - [Enable Azure AD OAuth in Grafana](#enable-azure-ad-oauth-in-grafana) + - [Configure refresh token](#configure-refresh-token) - [Configure allowed groups](#configure-allowed-groups) - [Configure allowed domains](#configure-allowed-domains) + - [PKCE](#pkce) + - [Configure automatic login](#configure-automatic-login) - [Team Sync (Enterprise only)](#team-sync-enterprise-only) + - [Common troubleshooting](#common-troubleshooting) + - [Users with over 200 Group assignments](#users-with-over-200-group-assignments) + - [Force fetching groups from Microsoft graph API](#force-fetching-groups-from-microsoft-graph-api) + - [Map roles](#map-roles) + - [Skip organization role sync](#skip-organization-role-sync) ## Create the Azure AD application @@ -125,7 +134,7 @@ If the setting is set to `false`, the user is assigned the role of `Admin` of th ## Enable Azure AD OAuth in Grafana -1. Add the following to the [Grafana configuration file]({{< relref "../../../configure-grafana/#config-file-locations" >}}): +1. Add the following to the [Grafana configuration file]({{< relref "../../../configure-grafana#configuration-file-location" >}}): ``` [auth.azuread] @@ -143,6 +152,7 @@ allowed_groups = role_attribute_strict = false allow_assign_grafana_admin = false skip_org_role_sync = false +use_pkce = true ``` You can also use these environment variables to configure **client_id** and **client_secret**: @@ -152,7 +162,7 @@ GF_AUTH_AZUREAD_CLIENT_ID GF_AUTH_AZUREAD_CLIENT_SECRET ``` -**Note:** Verify that the Grafana [root_url]({{< relref "../../../configure-grafana/#root-url" >}}) is set in your Azure Application Redirect URLs. +**Note:** Verify that the Grafana [root_url]({{< relref "../../../configure-grafana#root_url" >}}) is set in your Azure Application Redirect URLs. ### Configure refresh token @@ -191,9 +201,18 @@ The `allowed_domains` option limits access to users who belong to specific domai allowed_domains = mycompany.com mycompany.org ``` +### PKCE + +IETF's [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) +introduces "proof key for code exchange" (PKCE) which provides +additional protection against some forms of authorization code +interception attacks. PKCE will be required in [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-03). + +> You can disable PKCE in Grafana by setting `use_pkce` to `false` in the`[auth.azuread]` section. + ### Configure automatic login -Set `auto_login` option to true to attempt login automatically, skipping the login screen. +To bypass the login screen and log in automatically, enable the "auto_login" feature. This setting is ignored if multiple auth providers are configured to use auto login. ``` @@ -207,7 +226,7 @@ the correct teams. You can reference Azure AD groups by group object ID, like `8bab1c86-8fba-33e5-2089-1d1c80ec267d`. -To learn more, refer to the [Team Sync]({{< relref "../../configure-team-sync/" >}}) documentation. +To learn more, refer to the [Team Sync]({{< relref "../../configure-team-sync" >}}) documentation. ## Common troubleshooting @@ -254,15 +273,12 @@ their organization membership will be reset to the default organization. ## Skip organization role sync -If Azure AD authentication is not intended to sync user roles and organization membership, -`oauth_skip_org_role_update_sync` should be enabled, this is not recommended to use in favor of setting provider specific `skip_org_role_sync` option. -See [configure-grafana]({{< relref "../../../configure-grafana#oauth_skip_org_role_update_sync" >}}) for more details. - -To prevent the sync of org roles from Grafana.com, set `skip_org_role_sync` to `true`. This is useful if you want to manage the organization roles for your users from within Grafana. +If Azure AD authentication is not intended to sync user roles and organization membership and prevent the sync of org roles from AzureAD, set `skip_org_role_sync` to `true`. This is useful if you want to manage the organization roles for your users from within Grafana or that your organization roles are synced from another provider. +See [Configure Grafana]({{< relref "../../../configure-grafana#authazuread" >}}) for more details. ```ini [auth.azuread] # .. -# prevents the sync of org roles from Grafana.com +# prevents the sync of org roles from AzureAD skip_org_role_sync = true ``` diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/generic-oauth/index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/generic-oauth/index.md index 91252194de5..cb60725af00 100644 --- a/docs/sources/setup-grafana/configure-security/configure-authentication/generic-oauth/index.md +++ b/docs/sources/setup-grafana/configure-security/configure-authentication/generic-oauth/index.md @@ -15,13 +15,23 @@ weight: 200 You can configure many different OAuth2 authentication services with Grafana using the generic OAuth2 feature. Examples: -- [Generic OAuth authentication](#generic-oauth-authentication) +- [Configure generic OAuth authentication](#configure-generic-oauth-authentication) + - [Email address](#email-address) + - [Groups / Teams](#groups--teams) + - [Login](#login) + - [PKCE](#pkce) + - [Configure refresh token](#configure-refresh-token) + - [Configure automatic login](#configure-automatic-login) - [Set up OAuth2 with Auth0](#set-up-oauth2-with-auth0) - [Set up OAuth2 with Bitbucket](#set-up-oauth2-with-bitbucket) - [Set up OAuth2 with Centrify](#set-up-oauth2-with-centrify) - [Set up OAuth2 with OneLogin](#set-up-oauth2-with-onelogin) - - [Role mapping](#role-mapping) + - [Role Mapping](#role-mapping) + - [JMESPath examples](#jmespath-examples) + - [Map user organization role](#map-user-organization-role) + - [Map server administrator privileges](#map-server-administrator-privileges) - [Team synchronization](#team-synchronization) + - [Skip organization role sync](#skip-organization-role-sync) This callback URL must match the full HTTP address that you use in your browser to access Grafana, but with the suffixed path of `/login/generic_oauth`. @@ -45,6 +55,7 @@ auth_url = token_url = api_url = allowed_domains = mycompany.com mycompany.org +allowed_groups = ["Admins", "Software Engineers"] tls_skip_verify_insecure = false tls_client_cert = tls_client_key = @@ -85,6 +96,8 @@ Similarly, group mappings are made using [JMESPath](http://jmespath.org/examples Furthermore, Grafana will check for the presence of at least one of the teams specified via the `team_ids` configuration option using the [JMESPath](http://jmespath.org/examples.html) specified via the `team_ids_attribute_path` configuration option. The JSON used for the path lookup is the HTTP response obtained from querying the Teams endpoint specified via the `teams_url` configuration option (using `/teams` as a fallback endpoint). The result should be a string array of Grafana Team IDs. Using this setting ensures that only certain teams is allowed to authenticate to Grafana using your OAuth provider. +You can limit access to only members of a given group or list of groups by setting the `allowed_groups` option. + ### Login Customize user login using `login_attribute_path` configuration option. Order of operations is as follows: @@ -103,7 +116,7 @@ You can set the user's display name with JMESPath using the `name_attribute_path > Available in Grafana v8.3 and later versions. IETF's [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) -introduces "proof key for code exchange" (PKCE) which introduces +introduces "proof key for code exchange" (PKCE) which provides additional protection against some forms of authorization code interception attacks. PKCE will be required in [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-03). @@ -217,7 +230,7 @@ By default, a refresh token is included in the response for the **Authorization allow_sign_up = true auto_login = false client_id = - client_secret = scopes = openid profile email auth_url = https://.my.centrify.com/OAuth2/Authorize/ token_url = https://.my.centrify.com/OAuth2/Token/ @@ -272,19 +285,23 @@ Grafana checks for the presence of a role using the [JMESPath](http://jmespath.o For more information, refer to the [JMESPath examples](#jmespath-examples). -> **Warning**: Currently if no organization role mapping is found for a user, Grafana doesn't -> update the user's organization role. This is going to change in Grafana 10. To avoid overriding manually set roles, -> enable the `oauth_skip_org_role_update_sync` option. -> See [configure-grafana]({{< relref "../../../configure-grafana#oauth_skip_org_role_update_sync" >}}) for more information. +{{% admonition type="warning" %}} +Currently if no organization role mapping is found for a user, Grafana doesn't +update the user's organization role. This is going to change in Grafana 10. To avoid overriding manually set roles, +enable the `skip_org_role_sync` option. +See [Configure Grafana]({{< relref "../../../configure-grafana#authgeneric_oauth" >}}) for more information. +{{% /admonition %}} On first login, if the`role_attribute_path` property does not return a role, then the user is assigned the role specified by [the `auto_assign_org_role` option]({{< relref "../../../configure-grafana#auto_assign_org_role" >}}). You can disable this default role assignment by setting `role_attribute_strict = true`. It denies user access if no role or an invalid role is returned. -> **Warning**: With Grafana 10, **on every login**, if the`role_attribute_path` property does not return a role, -> then the user is assigned the role specified by -> [the `auto_assign_org_role` option]({{< relref "../../../configure-grafana#auto_assign_org_role" >}}). +{{% admonition type="warning" %}} +With Grafana 10, **on every login**, if the`role_attribute_path` property does not return a role, +then the user is assigned the role specified by +[the `auto_assign_org_role` option]({{< relref "../../../configure-grafana#auto_assign_org_role" >}}). +{{% /admonition %}} ### JMESPath examples @@ -368,7 +385,7 @@ With Team Sync you can map your Generic OAuth groups to teams in Grafana so that Generic OAuth groups can be referenced by group ID, like `8bab1c86-8fba-33e5-2089-1d1c80ec267d` or `myteam`. -[Learn more about Team Sync]({{< relref "../../configure-team-sync/" >}}) +[Learn more about Team Sync]({{< relref "../../configure-team-sync" >}}) Config: @@ -392,3 +409,16 @@ Payload: ... } ``` + +## Skip organization role sync + +To prevent the sync of organization roles from the OAuth provider, set `skip_org_role_sync` to `true`. This is useful if you want to manage the organization roles for your users from within Grafana. +This also impacts the `allow_assign_grafana_admin` setting by not syncing the Grafana admin role from the OAuth provider. + +```ini +[auth.generic_oauth] +# .. +# prevents the sync of org roles from the Oauth provider +skip_org_role_sync = true +`` +``` diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/gitlab/index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/gitlab/index.md index 2fe7302ab1d..e754cc1620e 100644 --- a/docs/sources/setup-grafana/configure-security/configure-authentication/gitlab/index.md +++ b/docs/sources/setup-grafana/configure-security/configure-authentication/gitlab/index.md @@ -7,7 +7,7 @@ keywords: - configuration - documentation - oauth -title: Configure GitLab OAuth2 Authentication +title: Configure GitLab OAuth2 authentication weight: 700 --- @@ -61,6 +61,11 @@ allowed_groups = role_attribute_path = role_attribute_strict = false allow_assign_grafana_admin = false +tls_skip_verify_insecure = false +tls_client_cert = +tls_client_key = +tls_client_ca = +use_pkce = true ``` You may have to set the `root_url` option of `[server]` for the callback URL to be @@ -81,6 +86,14 @@ to login on your Grafana instance. You can limit access to only members of a given group or list of groups by setting the `allowed_groups` option. +You can also specify the SSL/TLS configuration used by the client. + +- Set `tls_client_cert` to the path of the certificate. +- Set `tls_client_key` to the path containing the key. +- Set `tls_client_ca` to the path containing a trusted certificate authority list. + +`tls_skip_verify_insecure` controls whether a client verifies the server's certificate chain and host name. If it is true, then SSL/TLS accepts any certificate presented by the server and any host name in that certificate. _You should only use this for testing_, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks. + ### Configure refresh token > Available in Grafana v9.3 and later versions. @@ -140,8 +153,28 @@ allowed_groups = example, foo/bar role_attribute_path = is_admin && 'Admin' || 'Viewer' role_attribute_strict = true allow_assign_grafana_admin = false +tls_skip_verify_insecure = false +tls_client_cert = +tls_client_key = +tls_client_ca = +use_pkce = true ``` +### PKCE + +IETF's [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) +introduces "proof key for code exchange" (PKCE) which provides +additional protection against some forms of authorization code +interception attacks. PKCE will be required in [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-03). + +> You can disable PKCE in Grafana by setting `use_pkce` to `false` in the`[auth.gitlab]` section. + +``` +use_pkce = true +``` + +Grafana always uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier. + ### Configure automatic login Set `auto_login` option to true to attempt login automatically, skipping the login screen. @@ -155,21 +188,25 @@ auto_login = true You can use GitLab OAuth to map roles. During mapping, Grafana checks for the presence of a role using the [JMESPath](http://jmespath.org/examples.html) specified via the `role_attribute_path` configuration option. -For the path lookup, Grafana uses JSON obtained from querying GitLab's API [`/api/v4/user`](https://docs.gitlab.com/ee/api/users.html#list-current-user-for-normal-users) endpoint and a `groups` key containing all of the user's teams. The result of evaluating the `role_attribute_path` JMESPath expression must be a valid Grafana role, for example, `Viewer`, `Editor` or `Admin`. For more information about roles and permissions in Grafana, refer to [Roles and permissions]({{< relref "../../../../administration/roles-and-permissions/" >}}). +For the path lookup, Grafana uses JSON obtained from querying GitLab's API [`/api/v4/user`](https://docs.gitlab.com/ee/api/users.html#list-current-user-for-normal-users) endpoint and a `groups` key containing all of the user's teams. The result of evaluating the `role_attribute_path` JMESPath expression must be a valid Grafana role, for example, `Viewer`, `Editor` or `Admin`. For more information about roles and permissions in Grafana, refer to [Roles and permissions]({{< relref "../../../../administration/roles-and-permissions" >}}). -> **Warning**: Currently if no organization role mapping is found for a user, Grafana doesn't -> update the user's organization role. This is going to change in Grafana 10. To avoid overriding manually set roles, -> enable the `oauth_skip_org_role_update_sync` option. -> See [configure-grafana]({{< relref "../../../configure-grafana#oauth_skip_org_role_update_sync" >}}) for more information. +{{% admonition type="warning" %}} +Currently if no organization role mapping is found for a user, Grafana doesn't +update the user's organization role. This is going to change in Grafana 10. To avoid overriding manually set roles, +enable the `skip_org_role_sync` option. +See [Configure Grafana]({{< relref "../../../configure-grafana#authgitlab" >}}) for more information. +{{% /admonition %}} On first login, if the`role_attribute_path` property does not return a role, then the user is assigned the role specified by [the `auto_assign_org_role` option]({{< relref "../../../configure-grafana#auto_assign_org_role" >}}). You can disable this default role assignment by setting `role_attribute_strict = true`. It denies user access if no role or an invalid role is returned. -> **Warning**: With Grafana 10, **on every login**, if the`role_attribute_path` property does not return a role, -> then the user is assigned the role specified by -> [the `auto_assign_org_role` option]({{< relref "../../../configure-grafana#auto_assign_org_role" >}}). +{{% admonition type="warning" %}} +With Grafana 10, **on every login**, if the`role_attribute_path` property does not return a role, +then the user is assigned the role specified by +[the `auto_assign_org_role` option]({{< relref "../../../configure-grafana#auto_assign_org_role" >}}). +{{% /admonition %}} An example Query could look like the following: @@ -222,7 +259,7 @@ the correct teams. Your GitLab groups can be referenced in the same way as `allowed_groups`, like `example` or `foo/bar`. -[Learn more about Team Sync]({{< relref "../../configure-team-sync/" >}}) +[Learn more about Team Sync]({{< relref "../../configure-team-sync" >}}) ## Skip organization role sync diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/google/index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/google/index.md index 31344b83f5b..5dd85bfdfae 100644 --- a/docs/sources/setup-grafana/configure-security/configure-authentication/google/index.md +++ b/docs/sources/setup-grafana/configure-security/configure-authentication/google/index.md @@ -41,6 +41,7 @@ auth_url = https://accounts.google.com/o/oauth2/auth token_url = https://accounts.google.com/o/oauth2/token allowed_domains = mycompany.com mycompany.org hosted_domain = mycompany.com +use_pkce = true ``` You may have to set the `root_url` option of `[server]` for the callback URL to be @@ -58,6 +59,15 @@ 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 + +IETF's [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) +introduces "proof key for code exchange" (PKCE) which provides +additional protection against some forms of authorization code +interception attacks. PKCE will be required in [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-03). + +> You can disable PKCE in Grafana by setting `use_pkce` to `false` in the`[auth.google]` section. + ### Configure refresh token > Available in Grafana v9.3 and later versions. diff --git a/docs/sources/setup-grafana/configure-security/configure-authentication/okta/index.md b/docs/sources/setup-grafana/configure-security/configure-authentication/okta/index.md index 143d7eb0861..a0268e1a3f5 100644 --- a/docs/sources/setup-grafana/configure-security/configure-authentication/okta/index.md +++ b/docs/sources/setup-grafana/configure-security/configure-authentication/okta/index.md @@ -51,8 +51,18 @@ api_url = https://.okta.com/oauth2/v1/userinfo allowed_domains = allowed_groups = role_attribute_path = +use_pkce = true ``` +### PKCE + +IETF's [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) +introduces "proof key for code exchange" (PKCE) which provides +additional protection against some forms of authorization code +interception attacks. PKCE will be required in [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-03). + +> You can disable PKCE in Grafana by setting `use_pkce` to `false` in the`[auth.okta]` section. + ### Configure refresh token > Available in Grafana v9.3 and later versions.