public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: removing docs debt in install docs (#101750)

Browse Source 
* Docs: removing docs debt in install docs

* cleaning up set up docs debt

* fixing some vale errors

* fixing broken admonition shortcode

* fixing broken shortcode

* fixing broken shortcode

* working to the grafana authentication config

* updating some more files

* editing down to ldap in the repo

* editing ldap doc except final section with link needed

* Finishing doc debt cleanup through configure authetication

* fixing shortcodes reverted by merge conflict fix

* fixing admonition

* fixing more broken shortcodes

* adjusting some wordings ot make vale happy

* updating feature toggle info
This commit is contained in:
Jacob Valdez
2025-04-09 09:02:51 -05:00
committed by GitHub
parent af6c536c22
commit 8dfb0874a0
24 changed files with 243 additions and 236 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/setup-grafana/configure-security/configure-authentication/google/index.md
+28 -28
View File
@@ -16,9 +16,9 @@ weight: 1100
To enable Google OAuth you must register your application with Google. Google will generate a client ID and secret key for you to use.
{{% admonition type="note" %}}
{{< admonition type="note" >}}
If Users use the same email address in Google that they use with other authentication providers (such as Grafana.com), you need to do additional configuration to ensure that the users are matched correctly. Please refer to the [Using the same email address to login with different identity providers](../#using-the-same-email-address-to-login-with-different-identity-providers) documentation for more information.
{{% /admonition %}}
{{< /admonition >}}
## Create Google OAuth keys
@@ -45,9 +45,9 @@ First, you need to create a Google OAuth Client:
## 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 %}}
{{< admonition type="note" >}}
Available behind the `ssoSettingsAPI` feature toggle, which is enabled by default.
{{< /admonition >}}
As a Grafana Admin, you can configure Google OAuth 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.
@@ -55,15 +55,15 @@ After you have filled in the form, click **Save**. If the save was successful, G
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" %}}
{{< 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 %}}
{{< /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 %}}
{{< admonition type="note" >}}
Available behind the `ssoSettingsAPI` feature toggle, which is enabled by default. Supported in the Terraform provider since v2.12.0.
{{< /admonition >}}
```terraform
resource "grafana_sso_settings" "google_sso_settings" {
@@ -109,9 +109,9 @@ use_pkce = true
```
You may have to set the `root_url` option of `[server]` for the callback URL to be
correct. For example in case you are serving Grafana behind a proxy.
correct. For example, in case you are serving Grafana behind a proxy.
Restart the Grafana back-end. You should now see a Google login button
Restart the Grafana backend. You should now see a Google login button
on the login page. You can now login or sign up with your Google
accounts. The `allowed_domains` option is optional, and domains were separated by space.
@@ -123,13 +123,13 @@ 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).
{{% admonition type="note" %}}
{{< admonition type="note" >}}
Since Grafana 10.3.0, the `hd` parameter retrieved from Google ID token is also used to determine the user's hosted domain. The Google Oauth `allowed_domains` configuration option is used to restrict access to users from a specific domain. If the `allowed_domains` configuration option is set, the `hd` parameter from the Google ID token must match the `allowed_domains` configuration option. If the `hd` parameter from the Google ID token does not match the `allowed_domains` configuration option, the user is denied access.
When an account does not belong to a google workspace, the hd claim will not be available.
When an account does not belong to a google workspace, the `hd` claim will not be available.
This validation is enabled by default. To disable this validation, set the `validate_hd` configuration option to `false`. The `allowed_domains` configuration option will use the email claim to validate the domain.
{{% /admonition %}}
{{< /admonition >}}
#### PKCE
@@ -138,9 +138,9 @@ 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).
{{% admonition type="note" %}}
{{< admonition type="note" >}}
You can disable PKCE in Grafana by setting `use_pkce` to `false` in the`[auth.google]` section.
{{% /admonition %}}
{{< /admonition >}}
#### Configure refresh token
@@ -158,7 +158,7 @@ The `accessTokenExpirationCheck` feature toggle has been removed in Grafana v10.
#### Configure automatic login
Set `auto_login` option to true to attempt login automatically, skipping the login screen.
Set the `auto_login` option to true to attempt log in automatically, skipping the login screen.
This setting is ignored if multiple auth providers are configured to use auto login.
```
@@ -195,13 +195,13 @@ to a comma or space separated list of groups.
Google groups are referenced by the group email key. For example, `developers@google.com`.
{{% admonition type="note" %}}
{{< admonition type="note" >}}
Add the `https://www.googleapis.com/auth/cloud-identity.groups.readonly` scope to your Grafana `[auth.google]` scopes configuration to retrieve groups.
{{% /admonition %}}
{{< /admonition >}}
#### Configure role mapping
Unless `skip_org_role_sync` option is enabled, the user's role will be set to the role mapped from Google upon user login. If no mapping is set the default instance role is used.
Unless the `skip_org_role_sync` option is enabled, the user's role will be set to the role mapped from Google upon user login. If no mapping is set the default instance role is used.
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.
@@ -210,9 +210,9 @@ If no valid role is found, the user is assigned the role specified by [the `auto
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 after evaluating the `role_attribute_path` and the `org_mapping` expressions.
To ease configuration of a proper JMESPath expression, go to [JMESPath](http://jmespath.org/) to test and evaluate expressions with custom payloads.
{{% admonition type="note" %}}
By default skip_org_role_sync is enabled. skip_org_role_sync will default to false in Grafana v10.3.0 and later versions.
{{% /admonition %}}
{{< admonition type="note" >}}
By default the `skip_org_role_sync` option is enabled. The `skip_org_role_sync` option defaults to false in Grafana v10.3.0 and later versions.
{{< /admonition >}}
##### Role mapping examples
@@ -252,13 +252,13 @@ role_attribute_path = contains(groups[*], 'example-group@google.com') && 'Editor
skip_org_role_sync = false
```
{{% admonition type="note" %}}
{{< admonition type="note" >}}
Add the `https://www.googleapis.com/auth/cloud-identity.groups.readonly` scope to your Grafana `[auth.google]` scopes configuration to retrieve groups.
{{% /admonition %}}
{{< /admonition >}}
###### 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.
In this example, the user with email `admin@company.com` is granted the `Admin` organization role as well as the Grafana server admin role.
All other users are granted the `Viewer` role.
```ini
@@ -269,7 +269,7 @@ role_attribute_path = email=='admin@company.com' && '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.
In this example, all users are assigned the `Viewer` role regardless of the user information received from the identity provider.
```ini
role_attribute_path = "'Viewer'"