* 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 topic helps you get started with Grafana and build your first dashboard using the built-in `Grafana` data source. To learn more about Grafana, refer to [Introduction to Grafana](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Grafana also offers a [free account with Grafana Cloud](/signup/cloud/connect-account?pg=gsdocs) to help getting started even easier and faster. You can install Grafana to self-host or get a free Grafana Cloud account.
@ -49,9 +49,9 @@ Prometheus Node exporter is a widely used tool that exposes system metrics. For
When you run Node exporter locally, navigate to `http://localhost:9100/metrics` to check that it is exporting metrics.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
The instructions in the referenced topic are intended for Linux users. You may have to alter the instructions slightly depending on your operating system. For example, if you are on Windows, use the [windows_exporter](https://github.com/prometheus-community/windows_exporter) instead.
{{% /admonition %}}
{{</admonition>}}
## Install and configure Prometheus
@ -115,9 +115,9 @@ remote_write:
password: <YourGrafana.comAPIKey>
```
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
To configure your Prometheus instance to work with Grafana locally instead of Grafana Cloud, install Grafana [here](/grafana/download) and follow the configuration steps listed [here](/docs/grafana/latest/datasources/prometheus/#configure-the-data-source).
@ -25,9 +25,9 @@ You can configure Grafana to only allow certain IP addresses or hostnames to be
The request security configuration option allows users to limit requests from the Grafana server. It targets requests that are generated by users. For more information, refer to [Request security](configure-request-security/).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Request security is available in Grafana Enterprise v7.4 and later versions.
Available in [Grafana Enterprise](../../../introduction/grafana-enterprise/) and [Grafana Cloud](../../../introduction/grafana-cloud/) since Grafana v10.4.
{{% /admonition %}}
{{</admonition>}}
```
curl --request PUT \
@ -226,9 +226,9 @@ a Grafana admin user, you can also do the same for any user from the Server Admi
### Protected roles
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Available in [Grafana Enterprise](../../../introduction/grafana-enterprise/) and [Grafana Cloud](../../../introduction/grafana-cloud/).
{{% /admonition %}}
{{</admonition>}}
By default, after you configure an authorization provider, Grafana will adopt existing users into the new authentication scheme. For example, if you have created a user with basic authentication having the login `jsmith@example.com`, then set up SAML authentication where `jsmith@example.com` is an account, the user's authentication type will be changed to SAML if they perform a SAML sign-in.
- Create a htpasswd file. We create a new user **anthony** with the password **password**
- Create a `htpasswd` file. We create a new user **anthony** with the password **password**
```bash
htpasswd -bc htpasswd anthony password
```
- Launch the httpd container using our custom httpd.conf and our htpasswd file. The container will listen on port 80, and we create a link to the **grafana** container so that this container can resolve the hostname **grafana** to the Grafana container’s IP address.
- Launch the Apache HTTP server container using our custom `httpd.conf` and our `htpasswd` file. The container will listen on port 80, and we create a link to the **grafana** container so that this container can resolve the hostname **grafana** to the Grafana container’s IP address.
With our Grafana and Apache containers running, you can now connect to http://localhost/ and log in using the username/password we created in the htpasswd file.
With our Grafana and Apache containers running, you can now connect to http://localhost/ and log in using the username and password we created in the `htpasswd` file.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If the user is deleted from Grafana, the user will be not be able to login and resync until after the `sync_ttl` has expired.
The Azure AD authentication allows you to use a Microsoft Entra ID (formerly known as Azure Active Directory) tenant as an identity provider for Grafana. You can use Entra ID application roles to assign users and groups to Grafana roles from the Azure Portal.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If Users use the same email address in Microsoft Entra ID 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 [Using the same email address to login with different identity providers](../#using-the-same-email-address-to-login-with-different-identity-providers) for more information.
{{% /admonition %}}
{{</admonition>}}
## Create the Microsoft Entra ID application
@ -37,7 +37,7 @@ To enable the Azure AD/Entra ID OAuth, register your application with Entra ID.
1. Under **Redirect URI**, select the app type **Web**.
1. Add the following redirect URLs `https://<grafana domain>/login/azuread` and `https://<grafana domain>` then click **Register**. The app's **Overview** page opens.
1. Add the redirect URLs `https://<grafana domain>/login/azuread` and `https://<grafana domain>`, then click **Register**. The app's **Overview** page opens.
1. Note the **Application ID**. This is the OAuth client ID.
@ -94,9 +94,9 @@ To enable the Azure AD/Entra ID OAuth, register your application with Entra ID.
1. Click **Users and Groups**.
1. Click **Add user/group** to add a user or group to the Grafana roles.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
When assigning a group to a Grafana role, ensure that users are direct members of the group. Users in nested groups will not have access to Grafana due to limitations within Azure AD/Entra ID side. For more information, see [Microsoft Entra service limits and restrictions](https://learn.microsoft.com/en-us/entra/identity/users/directory-service-limits-restrictions).
{{% /admonition %}}
{{</admonition>}}
### Configure application roles for Grafana in the Azure Portal
@ -128,9 +128,9 @@ If you prefer to configure the application roles for Grafana in the manifest fil
1. Add a Universally Unique Identifier to each role.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Every role requires a [Universally Unique Identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier) which you can generate on Linux with `uuidgen`, and on Windows through Microsoft PowerShell with `New-Guid`.
{{% /admonition %}}
{{</admonition>}}
1. Replace each "SOME_UNIQUE_ID" with the generated ID in the manifest file:
@ -205,9 +205,9 @@ Ensure that you have followed the steps in [Create the Microsoft Entra ID applic
## Configure Azure AD authentication client using the Grafana UI
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle.
{{% /admonition %}}
{{</admonition>}}
As a Grafana Admin, you can configure your Azure AD/Entra ID OAuth client from within Grafana using the Grafana UI. To do this, navigate to the **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.
@ -215,15 +215,15 @@ After you have filled in the form, click **Save** to save the configuration. If
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" %}}
{{<admonitiontype="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 Azure AD authentication client using the Terraform provider
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle. Supported in the Terraform provider since v2.12.0.
Verify that the Grafana [root_url](../../../configure-grafana/#root_url) is set in your Azure Application Redirect URLs.
{{% /admonition %}}
{{</admonition>}}
### Configure refresh token
@ -304,12 +304,14 @@ Grafana uses a refresh token to obtain a new access token without requiring the
Refresh token fetching and access token expiration check is enabled by default for the AzureAD provider since Grafana v10.1.0. If you would like to disable access token expiration check then set the `use_refresh_token` configuration value to `false`.
> **Note:** 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.
{{<admonitiontype="note">}}
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 allowed tenants
To limit access to authenticated users who are members of one or more tenants, set `allowed_organizations`
to a comma- or space-separated list of tenant IDs. You can find tenant IDs on the Azure portal under **Microsoft Entra ID -> Overview**.
to a _comma-_ or _space-separated_ list of tenant IDs. You can find tenant IDs on the Azure portal under **Microsoft Entra ID -> Overview**.
Make sure to include the tenant IDs of all the federated Users' root directory if your Entra ID contains external identities.
Microsoft Entra ID groups can be used to limit user access to Grafana. For more information about managing groups in Entra ID, refer to [Manage Microsoft Entra groups and group membership](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-manage-groups).
To limit access to authenticated users who are members of one or more Entra ID groups, set `allowed_groups`
to a **comma-** or **space-separated** list of group object IDs.
to a _comma-_ or _space-separated_ list of group object IDs.
1. To find object IDs for a specific group on the Azure portal, go to **Microsoft Entra ID > Manage > Groups**.
@ -348,9 +350,9 @@ To configure group membership claims from the Azure Portal UI, complete the foll
For more information, see [Configure groups optional claims](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims#configure-groups-optional-claims).
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If the user is a member of more than 200 groups, Entra ID does not emit the groups claim in the token and instead emits a group overage claim. To set up a group overage claim, see [Users with over 200 Group assignments](#users-with-over-200-group-assignments).
{{% /admonition %}}
{{</admonition>}}
#### Configure group membership claim in the manifest file
@ -424,9 +426,9 @@ The Entra ID `App registration` must include the following API permissions for g
Admin consent is required for the `GroupMember.Read.All` permission. To grant admin consent, navigate to **API permissions** in the **App registration** and select **Grant admin consent for [your-organization]**.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
You can make Grafana always get group information from the Microsoft Graph API by turning on the [`force_use_graph_api`](./#force-fetching-groups-from-microsoft-graph-api) setting in the configuration.
{{% /admonition %}}
{{</admonition>}}
#### Configure the required Graph API permissions
@ -441,9 +443,9 @@ You can make Grafana always get group information from the Microsoft Graph API b
1. In the **Select permissions** pane, under the **User** section, select **User.Read**.
1. Click the **Add permissions** button at the bottom of the page.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Admin consent may be required for this permission.
{{% /admonition %}}
{{</admonition>}}
### Force fetching groups from Microsoft Graph API
@ -463,7 +465,7 @@ You can disable this default role assignment by setting `role_attribute_strict =
You can use the `org_mapping` configuration option to assign the user to multiple organizations and specify their role based on their Entra ID group membership. For more information, refer to [Org roles mapping example](#org-roles-mapping-example). If the org role mapping (`org_mapping`) is specified and Entra ID returns a valid role, then the user will get the highest of the two roles.
**On every login** the user organization role will be reset to match Entra ID's application role and
_On every login_ the user organization role will be reset to match Entra ID's application role and
their organization membership will be reset to the default organization.
The enhanced LDAP integration adds additional functionality on top of the [LDAP integration](../ldap/) available in the open source edition of Grafana.
> **Note:** Available in [Grafana Enterprise](../../../../introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud).
> If you are a Grafana Cloud customer, please [open a support ticket in the Cloud Portal](/profile/org#support) to request this feature.
{{<admonitiontype="note">}}
Available in [Grafana Enterprise](../../../../introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud).
If you are a Grafana Cloud customer, please [open a support ticket in the Cloud Portal](/profile/org#support) to request this feature.
{{</admonition>}}
> To control user access with role-based permissions, refer to [role-based access control](../../../../administration/roles-and-permissions/access-control/).
@ -51,7 +53,7 @@ With active LDAP synchronization, you can configure Grafana to actively sync use
Users with updated role and team membership will need to refresh the page to get access to the new features.
Removed users are automatically logged out and their account disabled. These accounts are displayed in the Server Admin > Users page with a `disabled` label. Disabled users keep their custom permissions on dashboards, folders, and data sources, so if you add them back in your LDAP database, they have access to the application with the same custom permissions as before.
Removed users are automatically logged out and their account disabled. These accounts are displayed in the **Server Admin > Users** page with a `disabled` label. Disabled users keep their custom permissions on dashboards, folders, and data sources, so if you add them back in your LDAP database, they have access to the application with the same custom permissions as before.
Single bind configuration (as in the [Single bind example](../ldap/#single-bind-example)) is not supported with active LDAP synchronization because Grafana needs user information to perform LDAP searches.
For the synchronization to work, the `servers.search_filter` and `servers.attributes.username` in the ldap.toml config file must match. By default, the `servers.attributes.username` is `cn`, so if you use another attribute as the search filter, you must also update the username attribute.
For the synchronization to work, the `servers.search_filter` and `servers.attributes.username` in the `ldap.toml` configuration file must match. By default, the `servers.attributes.username` is `cn`, so if you use another attribute as the search filter, you must also update the username attribute.
- 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.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If Users use the same email address in Azure AD 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>}}
## 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 %}}
{{<admonitiontype="note">}}
Available behind the `ssoSettingsAPI` feature toggle, which is enabled by default.
{{</admonition>}}
As a Grafana Admin, you can configure Generic OAuth 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.
@ -59,17 +59,17 @@ After you have filled in the form, click **Save** to save the configuration. If
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" %}}
{{<admonitiontype="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>}}
Refer to [configuration options](#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 %}}
{{<admonitiontype="note">}}
Available behind the `ssoSettingsAPI` feature toggle, which is enabled by default. Supported in the Terraform provider since v2.12.0.
@ -412,9 +412,9 @@ To set up Generic OAuth authentication with Descope, follow these steps:
1. Update the `[auth.generic_oauth]` section of the Grafana configuration file using the values from the **Settings** tab:
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
You can get your Client ID (Descope Project ID) under [Project Settings](https://app.descope.com/settings/project). Your Client Secret (Descope Access Key) can be generated under [Access Keys](https://app.descope.com/accesskeys).
{{% /admonition %}}
{{</admonition>}}
```bash
[auth.generic_oauth]
@ -558,10 +558,10 @@ steps:
- 'https://<grafanadomain>/login/generic_oauth'
```
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Unlike many other OAuth2 providers, Dex doesn't provide `<client secret>`.
Instead, a secret can be generated with for example `openssl rand -hex 20`.
{{% /admonition %}}
{{</admonition>}}
2. Update the `[auth.generic_oauth]` section of the Grafana configuration:
This topic describes how to configure GitHub OAuth authentication.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If Users use the same email address in GitHub 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>}}
## Before you begin
@ -43,9 +43,9 @@ Ensure you know how to create a GitHub OAuth app. Consult GitHub's documentation
## Configure GitHub authentication client using the Grafana UI
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle.
{{% /admonition %}}
{{<admonitiontype="note">}}
Available behind the `ssoSettingsAPI` feature toggle, which is enabled by default.
{{</admonition>}}
As a Grafana Admin, you can configure GitHub OAuth 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.
@ -53,17 +53,17 @@ After you have filled in the form, click **Save**. If the save was successful, G
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" %}}
{{<admonitiontype="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>}}
Refer to [configuration options](#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 %}}
{{<admonitiontype="note">}}
Available behind the `ssoSettingsAPI` feature toggle, which is enabled by default. Supported in the Terraform provider since v2.12.0.
This topic describes how to configure GitLab OAuth authentication.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If Users use the same email address in GitLab 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>}}
## Before you begin
@ -43,27 +43,23 @@ Ensure you know how to create a GitLab OAuth application. Consult GitLab's docum
## Configure GitLab 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 GitLab OAuth 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" %}}
{{<admonitiontype="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>}}
Refer to [configuration options](#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 %}}
{{<admonitiontype="note">}}
Available behind the `ssoSettingsAPI` feature toggle, which is enabled by default. Supported in the Terraform provider since v2.12.0.
@ -134,9 +130,9 @@ By default, GitLab provides a refresh token.
Refresh token fetching and access token expiration check is enabled by default for the GitLab provider since Grafana v10.1.0. If you would like to disable access token expiration check then set the `use_refresh_token` configuration value to `false`.
{{% admonition type="note" %}}
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 %}}
{{<admonitiontype="note">}}
The `accessTokenExpirationCheck` feature toggle has been removed in Grafana v10.3.0. Use the `use_refresh_token` configuration value instead for configuring refresh token fetching and access token expiration check.
{{</admonition>}}
### Configure allowed groups
@ -259,7 +255,7 @@ To learn more about Team Sync, refer to [Configure team sync](https://grafana.co
## Configuration options
The table below describes all GitLab OAuth configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana. For more information, refer to [Override configuration with environment variables](../../../configure-grafana/#override-configuration-with-environment-variables).
The following table describes all GitLab OAuth configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana. For more information, refer to [Override configuration with environment variables](../../../configure-grafana/#override-configuration-with-environment-variables).
{{<admonitiontype="note">}}
If the configuration option requires a JMESPath expression that includes a colon, enclose the entire expression in quotes to prevent parsing errors. For example `role_attribute_path: "role:view"`
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" %}}
{{<admonitiontype="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 %}}
{{<admonitiontype="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" %}}
{{<admonitiontype="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 %}}
{{<admonitiontype="note">}}
Available behind the `ssoSettingsAPI` feature toggle, which is enabled by default. Supported in the Terraform provider since v2.12.0.
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" %}}
{{<admonitiontype="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" %}}
{{<admonitiontype="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 login 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" %}}
{{<admonitiontype="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 %}}
{{<admonitiontype="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.
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.
In this scenario, you will need to configure Grafana to accept a JWT
provided in the HTTP header and a reverse proxy should rewrite requests to the
Grafana instance to include the JWT in the request's headers.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
For embedding to work, you must enable `allow_embedding` in the [security section](../../../configure-grafana/#allow_embedding). This setting is not available in Grafana Cloud.
{{% /admonition %}}
{{</admonition>}}
In a scenario where it is not possible to rewrite the request headers you
can use URL login instead.
@ -117,12 +117,14 @@ can use URL login instead.
`url_login` allows grafana to search for a JWT in the URL query parameter
`auth_token` and use it as the authentication token.
**Note**: You need to have enabled JWT before setting this setting see section Enabled JWT
{{<admonitiontype="note">}}
You need to enable JWT before setting this setting. Refer to [Enabled JWT](#enable-jwt).
{{</admonition>}}
{{% admonition type="warning" %}}
this can lead to JWTs being exposed in logs and possible session hijacking if the server is not
{{<admonitiontype="warning">}}
This can lead to JWTs being exposed in logs and possible session hijacking if the server is not
> **Note**: If the JWKS endpoint includes cache control headers and the value is less than the configured `cache_ttl`, then the cache control header value is used instead. If the cache_ttl is not set, no caching is performed. `no-store` and `no-cache` cache control headers are ignored.
{{<admonitiontype="note">}}
If the JWKS endpoint includes cache control headers and the value is less than the configured `cache_ttl`, then the cache control header value is used instead. If the `cache_ttl` is not set, no caching is performed. `no-store` and `no-cache` cache control headers are ignored.
{{</admonition>}}
### Verify token using a JSON Web Key Set loaded from JSON file
@ -24,9 +24,9 @@ Keycloak OAuth2 authentication allows users to log in to Grafana using their Key
Refer to [Generic OAuth authentication](../generic-oauth/) for extra configuration options available for this provider.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If Users use the same email address in Keycloak 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>}}
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.
@ -59,10 +59,10 @@ To configure the `kc_idp_hint` parameter for Keycloak, you need to change the `a
api_url is not required if the id_token contains all the necessary user information and can add latency to the login process.
It is useful as a fallback or if the user has more than 150 group memberships.
{{% /admonition %}}
{{</admonition>}}
## Keycloak configuration
@ -108,9 +108,9 @@ viewer
## Teamsync
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
{{</admonition>}}
[Teamsync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-team-sync/) is a feature that allows you to map groups from your identity provider to Grafana teams. This is useful if you want to give your users access to specific dashboards or folders based on their group membership.
@ -18,22 +18,22 @@ This page explains how to configure LDAP authentication in Grafana using the Gra
Benefits of using the Grafana user interface to configure LDAP authentication include:
- There is no need to edit the configuration file manually.
- No need to edit the configuration file manually.
- Quickly test the connection to the LDAP server.
- There is no need to restart Grafana after making changes.
- No need to restart Grafana after making changes.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Any configuration changes made through the Grafana user interface (UI) will take precedence over settings specified in the Grafana configuration file or through environment variables. If you modify any configuration settings in the UI, they will override any corresponding settings set via environment variables or defined in the configuration file.
{{% /admonition %}}
{{</admonition>}}
## Before you begin
Prerequisites:
To follow these instructions, you need:
- Knowledge of LDAP authentication and how it works.
- Grafana instance v11.3.0 or later.
- A Grafana instance v11.3.0 or later.
- Permissions `settings:read` and `settings:write` with `settings:auth.ldap:*` scope.
- This feature requires the `ssoSettingsLDAP` feature toggle to be enabled.
- The `ssoSettingsLDAP` feature toggle enabled.
## Steps to configure LDAP authentication
@ -86,7 +86,7 @@ Map LDAP groups to Grafana roles.
1. **Group name attribute**: Identifies users within group entries.
1. **Manage group mappings**:
When managing group mappings, the following fields will become available. To add a new group mapping, click the **Add group mapping** button.
When managing group mappings, the following fields are available. To add a new group mapping, click the **Add group mapping** button.
1. **Add a group DN mapping**: The name of the key used to extract the ID token.
1. **Add an organization role mapping**: Select the Basic Role mapped to this group.
The LDAP integration in Grafana allows your Grafana users to login with their LDAP credentials. You can also specify mappings between LDAP
group memberships and Grafana Organization user roles.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
[Enhanced LDAP authentication](../enhanced-ldap/) is available in [Grafana Cloud](/docs/grafana-cloud/) and in [Grafana Enterprise](../../../../introduction/grafana-enterprise/).
{{% /admonition %}}
{{</admonition>}}
Refer to [Role-based access control](../../../../administration/roles-and-permissions/access-control/) to understand how you can control access with role-based permissions.
@ -73,7 +73,7 @@ skip_org_role_sync = true
## Grafana LDAP Configuration
Depending on which LDAP server you're using and how that's configured your Grafana LDAP configuration may vary.
Depending on which LDAP server you're using and how that's configured, your Grafana LDAP configuration may vary.
See [configuration examples](#configuration-examples) for more information.
**LDAP specific configuration file (ldap.toml) example:**
@ -130,9 +130,9 @@ member_of = "memberOf"
email = "email"
```
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Whenever you modify the ldap.toml file, you must restart Grafana in order for the change(s) to take effect.
{{% /admonition %}}
{{</admonition>}}
### Using environment variables
@ -236,10 +236,10 @@ org_role = "Viewer"
| `org_id` | No | The Grafana organization database id. Setting this allows for multiple group_dn's to be assigned to the same `org_role` provided the `org_id` differs | `1` (default org id) |
| `grafana_admin` | No | When `true` makes user of `group_dn` Grafana server admin. A Grafana server admin has admin access over all organizations and users. | `false` |
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Commenting out a group mapping requires also commenting out the header of
said group or it will fail validation as an empty mapping.
{{% /admonition %}}
{{</admonition>}}
Example:
@ -273,7 +273,7 @@ To configure `group_search_filter`:
**Active Directory example:**
Active Directory groups store the Distinguished Names (DNs) of members, so your filter will need to know the DN for the user based only on the submitted username.
Active Directory groups store the Distinguished Names (DNs) of members, so your filter needs to know the DN for the user based only on the submitted username.
Multiple DN templates are searched by combining filters with the LDAP OR-operator. Two examples:
For more information on AD searches see [Microsoft's Search Filter Syntax](https://docs.microsoft.com/en-us/windows/desktop/adsi/search-filter-syntax) documentation.
For more information on AD searches refer to [Microsoft's Search Filter Syntax](https://docs.microsoft.com/en-us/windows/desktop/adsi/search-filter-syntax) documentation.
For troubleshooting, changing `member_of` in `[servers.attributes]` to "dn" will show you more accurate group memberships when [debug is enabled](#troubleshooting).
@ -409,12 +409,13 @@ email = "mail"
#### Port requirements
In above example SSL is enabled and an encrypted port have been configured. If your Active Directory don't support SSL please change `enable_ssl = false` and `port = 389`.
Please inspect your Active Directory configuration and documentation to find the correct settings. For more information about Active Directory and port requirements see [link](<https://technet.microsoft.com/en-us/library/dd772723(v=ws.10)>).
In the previous example, SSL is enabled and an encrypted port has been configured. If your Active Directory doesn't support SSL, use `enable_ssl = false` and `port = 389` instead.
Inspect your Active Directory configuration and documentation to find the correct settings. For more information about Active Directory and port requirements, refer to the [Microsoft documentation](https://learn.microsoft.com/en-us/troubleshoot/windows-server/networking/service-overview-and-network-port-requirements#active-directory-local-security-authority).
## Troubleshooting
To troubleshoot and get more log info enable LDAP debug logging in the [main config file](../../../configure-grafana/).
To troubleshoot and get more log information, enable LDAP debug logging in the [`grafana.ini` or `custom.ini`](../../../configure-grafana/) file:
If Users use the same email address in Okta 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>}}
## Before you begin
@ -82,9 +82,9 @@ To follow this guide, ensure you have permissions in your Okta workspace to crea
1. Include the `groups` scope in the **Scopes** field in Grafana of the Okta integration.
For Terraform or in the Grafana configuration file, include the `groups` scope in `scopes` field.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
If you configure the `groups` claim differently, ensure that the `groups` claim is a string array.
{{% /admonition %}}
{{</admonition>}}
#### Optional: Add the role attribute to the User (default) Okta profile
@ -101,9 +101,9 @@ If you want to configure the role for all users in the Okta directory, you can a
## Configure Okta authentication client using the Grafana UI
{{% admonition type="note" %}}
Available in Public Preview in Grafana 10.4 behind the `ssoSettingsApi` feature toggle.
{{% /admonition %}}
{{<admonitiontype="note">}}
Available behind the `ssoSettingsAPI` feature toggle, which is enabled by default.
{{</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.
@ -111,17 +111,17 @@ After you have filled in the form, click **Save**. If the save was successful, G
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" %}}
{{<admonitiontype="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>}}
Refer to [configuration options](#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 %}}
{{<admonitiontype="note">}}
Available behind the `ssoSettingsAPI` feature toggle, which is enabled by default. Supported in the Terraform provider since v2.12.0.
@ -208,9 +208,9 @@ At the configuration file, extend the `scopes` in `[auth.okta]` section with `of
### Configure role mapping
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
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.
{{% /admonition %}}
{{</admonition>}}
The user's role is retrieved using a [JMESPath](http://jmespath.org/examples.html) expression from the `role_attribute_path` configuration option against the `api_url` (`/userinfo` OIDC endpoint) endpoint payload.
@ -230,9 +230,9 @@ To learn about adding custom claims to the user info in Okta, refer to [add cust
#### Org roles mapping example
{{% admonition type="note" %}}
Available in on-premise Grafana installations.
{{% /admonition %}}
{{<admonitiontype="note">}}
Available in self-managed Grafana installations.
{{</admonition>}}
In this example, the `org_mapping` uses the `groups` attribute as the source (`org_attribute_path`) to map the current user to different organizations and roles. The user has been granted the role of a `Viewer` in the `org_foo` org if they are a member of the `Group 1` group, the role of an `Editor` in the `org_bar` org if they are a member of the `Group 2` group, and the role of an `Editor` in the `org_baz`(OrgID=3) org.
@ -15,9 +15,9 @@ Passwordless authentication lets Grafana users authenticate with a magic link or
## Enable passwordless authentication
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Passwordless authentication is an experimental feature. Engineering and on-call support is not available. Documentation is either limited or not provided outside of code comments. No SLA is provided. Enable the `passwordlessMagicLinkAuthentication` feature toggle in Grafana to use this feature.
{{% /admonition %}}
{{</admonition>}}
To enable passwordless authentication, use the following configuration:
# Configure SAML authentication using the configuration file
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud).
{{% /admonition %}}
{{</admonition>}}
SAML authentication integration allows your Grafana users to log in by using an external SAML 2.0 Identity Provider (IdP). To enable this, Grafana becomes a Service Provider (SP) in the authentication flow, interacting with the IdP to exchange user information.
@ -34,15 +34,15 @@ You can configure SAML authentication in Grafana through one of the following me
- The user interface (refer to [Configure SAML authentication using the Grafana user interface](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-authentication/saml-ui/)
- The Terraform provider (refer to [Terraform docs](https://registry.terraform.io/providers/grafana/grafana/<GRAFANA_VERSION>/docs/resources/sso_settings))
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
The API and Terraform support are available in Public Preview in Grafana v11.1 behind the `ssoSettingsSAML` feature toggle. You must also enable the `ssoSettingsApi` flag.
{{% /admonition %}}
{{</admonition>}}
All methods offer the same configuration options. However, if you want to keep all of Grafana authentication settings in one place, use the Grafana configuration file or the Terraform provider. If you are a Grafana Cloud user, you do not have access to Grafana configuration file. Instead, configure SAML through the other methods.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Configuration in the API takes precedence over the configuration in the Grafana configuration file. SAML settings from the API will override any SAML configuration set in the Grafana configuration file.
{{% /admonition %}}
{{</admonition>}}
## Supported SAML
@ -71,12 +71,12 @@ Grafana supports:
- SP-initiated requests
- IdP-initiated requests
By default, SP-initiated requests are enabled. For instructions on how to enable IdP-initiated logins, see [IdP-initiated Single Sign-On (SSO)](#idp-initiated-single-sign-on-sso).
By default, SP-initiated requests are enabled. For instructions on how to enable IdP-initiated logins, refer to [IdP-initiated Single Sign-On (SSO)](#idp-initiated-single-sign-on-sso).
{{% admonition type="note" %}}
It is possible to set up Grafana with SAML authentication using Azure AD. However, if an Azure AD user belongs to more than 150 groups, a Graph API endpoint is shared instead.
{{<admonitiontype="note">}}
It's possible to set up Grafana with SAML authentication using Azure AD. However, if an Azure AD user belongs to more than 150 groups, a Graph API endpoint is shared instead.
Grafana versions 11.1 and below, do not support fetching the groups from the Graph API endpoint. As a result, users with more than 150 groups will not be able to retrieve their groups. Instead, it is recommended that you use OIDC/OAuth workflows.
Grafana versions 11.1 and below do not support fetching the groups from the Graph API endpoint. As a result, users with more than 150 groups will not be able to retrieve their groups. Instead, it's recommended that you use OIDC/OAuth workflows.
As of Grafana 11.2, the SAML integration offers a mechanism to retrieve user groups from the Graph API.
@ -85,7 +85,7 @@ Related links:
- [Azure AD SAML limitations](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#groups-overage-claim)
- [Set up SAML with Azure AD](#set-up-saml-with-azure-ad)
- [Configure a Graph API application in Azure AD](#configure-a-graph-api-application-in-azure-ad)
{{% /admonition %}}
{{</admonition>}}
### Edit SAML options in the Grafana config file
@ -101,7 +101,7 @@ Related links:
1. Optionally, set the `name` parameter in the `[auth.saml]` section in the Grafana configuration file. This parameter replaces SAML in the Grafana user interface in locations such as the sign-in button.
1. Save the configuration file and then restart the Grafana server.
When you are finished, the Grafana configuration might look like this example:
When you're finished, the Grafana configuration might look like this example:
```ini
[server]
@ -122,7 +122,7 @@ assertion_attribute_groups = Group
## Enable SAML authentication in Grafana
To use the SAML integration, in the `auth.saml` section of in the Grafana custom configuration file, set `enabled` to `true`.
To use the SAML integration, in the `auth.saml` section of in the `grafana.ini` or `custom.ini` file, set `enabled` to `true`.
Refer to [Configuration](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/) for more information about configuring Grafana.
@ -132,9 +132,9 @@ If multiple bindings are supported for SAML Single Sign-On (SSO) by the Identity
To allow Grafana to initiate a POST request to the IdP, update the `content_security_policy_template` and `content_security_policy_report_only_template` settings in the Grafana configuration file and add the IdP's domain to the `form-action` directive. By default, the `form-action` directive is set to `self` which only allows POST requests to the same domain as Grafana. To allow POST requests to the IdP's domain, update the `form-action` directive to include the IdP's domain, for example: `form-action 'self' https://idp.example.com`.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
For Grafana Cloud instances, please contact Grafana Support to update the `content_security_policy_template` and `content_security_policy_report_only_template` settings of your Grafana instance. Please provide the metadata URL/file of your IdP.
{{% /admonition %}}
{{</admonition>}}
## Certificate and private key
@ -147,9 +147,9 @@ If you are directly supplying the certificate and key, Grafana supports two ways
- Without a suffix (`certificate` or `private_key`), the configuration assumes you've supplied the base64-encoded file contents.
- With the `_path` suffix (`certificate_path` or `private_key_path`), then Grafana treats the value entered as a file path and attempts to read the file from the file system.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
You can only use one form of each configuration option. Using multiple forms, such as both `certificate` and `certificate_path`, results in an error.
{{% /admonition %}}
{{</admonition>}}
Always work with your company's security team on setting up certificates and private keys. If you need to generate them yourself (such as in the short term, for testing purposes, and so on), use the following example to generate your certificate and private key, including the step of ensuring that the key is generated with the [PKCS#8](https://en.wikipedia.org/wiki/PKCS_8) format.
@ -438,10 +438,10 @@ By default, new Grafana users using SAML authentication will have an account cre
### 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 login automatically, skipping the login screen.
This setting is ignored if multiple auth providers are configured to use auto login.
```
```ini
auto_login = true
```
@ -510,7 +510,7 @@ Role sync allows you to map user roles from an identity provider to Grafana. To
1. Set the [`role_values_admin`](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/enterprise-configuration/#role_values_admin) option to the values mapped to the organization `Admin` role.
1. Set the [`role_values_grafana_admin`](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/enterprise-configuration/#role_values_grafana_admin) option to the values mapped to the `Grafana Admin` role.
If a user role doesn't match any of configured values, then the role specified by the `auto_assign_org_role` config option will be assigned. If the `auto_assign_org_role` field is not set then the user role will default to `Viewer`.
If a user role doesn't match any of configured values, then the role specified by the `auto_assign_org_role` configuration option will be assigned. If the `auto_assign_org_role` field isn't set then the user role will default to `Viewer`.
For more information about roles and permissions in Grafana, refer to [Roles and permissions](/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/).
@ -544,7 +544,7 @@ Organization mapping allows you to assign users to particular organization in Gr
1. In configuration file, set [`assertion_attribute_org`](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/enterprise-configuration/#assertion_attribute_org) to the attribute name you store organization info in. This attribute can be an array if you want a user to be in multiple organizations.
1. Set [`org_mapping`](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/enterprise-configuration/#org_mapping) option to the comma-separated list of `Organization:OrgId` pairs to map organization from IdP to Grafana organization specified by ID. If you want users to have different roles in multiple organizations, you can set this option to a comma-separated list of `Organization:OrgId:Role` mappings.
For example, use following configuration to assign users from`Engineering` organization to the Grafana organization with ID `2` as Editor and users from `Sales`- to the org with ID `3` as Admin, based on `Org` assertion attribute value:
For example, the following configuration assigns users from the`Engineering` organization to the Grafana organization with ID `2` as Editor and users from `Sales` to the org with ID `3` as Admin, based on the`Org` assertion attribute value:
```ini
[auth.saml]
@ -565,7 +565,7 @@ If one of the mappings contains a `:`, use the JSON syntax and escape the `:` wi
org_mapping = ["External\:Admin:ACME Corp:Admin"]
```
For example, to assign users from `Engineering` organization to the Grafana organization with name `ACME Corp` as Editor and users from `Sales`- to the org with id `3` as Admin, based on `Org` assertion attribute value:
For example, to assign users from `Engineering` organization to the Grafana organization with name `ACME Corp` as Editor and users from `Sales` to the org with id `3` as Admin, based on `Org` assertion attribute value:
@ -95,9 +95,9 @@ These are just a few examples of how Grafana can be used in M2M scenarios. The p
You can use a service account to run automated workloads in Grafana, such as dashboard provisioning, configuration, or report generation. Create service accounts and service accounts tokens to authenticate applications, such as Terraform, with the Grafana API.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Service accounts will eventually replace [API keys](/docs/grafana/<GRAFANA_VERSION>/administration/service-accounts/migrate-api-keys/) as the primary way to authenticate applications that interact with Grafana.
{{% /admonition %}}
{{</admonition>}}
A common use case for creating a service account is to perform operations on automated or triggered tasks. You can use service accounts to:
@ -108,9 +108,9 @@ A common use case for creating a service account is to perform operations on aut
In [Grafana Enterprise](../../../introduction/grafana-enterprise/), you can also use service accounts in combination with [role-based access control](../../../administration/roles-and-permissions/access-control/) to grant very specific permissions to applications that interact with Grafana.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Service accounts can only act in the organization they are created for. We recommend creating service accounts in each organization if you have the same task needed for multiple organizations.
{{% /admonition %}}
{{</admonition>}}
The following video shows how to migrate from API keys to service accounts.
{{<vimeo742056367>}}
@ -127,17 +127,17 @@ You can create multiple tokens for the same service account. You might want to d
- Multiple applications use the same permissions, but you want to audit or manage their actions separately.
- You need to rotate or replace a compromised token.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
In Grafana's audit logs it will still show up as the same service account.
{{% /admonition %}}
{{</admonition>}}
Service account access tokens inherit permissions from the service account.
### API keys
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Grafana recommends using service accounts instead of API keys. API keys will be deprecated in the near future. For more information, refer to [Grafana service accounts](./#service-accounts).
{{% /admonition %}}
{{</admonition>}}
You can use Grafana API keys to interact with data sources via HTTP APIs.
@ -169,9 +169,9 @@ Dashboard, folder, and data source permissions can be set through the UI or APIs
### Role-based access control
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Available in [Grafana Enterprise](../../../introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud/).
{{% /admonition %}}
{{</admonition>}}
If you think that the basic organization and server administrator roles are too limiting, it might be beneficial to employ [role-based access control (RBAC)](../../../administration/roles-and-permissions/access-control/).
RBAC is a flexible approach to managing user access to Grafana resources, including users, data sources, and reports. It enables easy granting, changing, and revoking of read and write access for users.
@ -189,13 +189,13 @@ When connecting Grafana to an identity provider, it's important to think beyond
Team sync is a feature that allows you to synchronize teams or groups from your authentication provider with teams in Grafana. This means that users of specific teams or groups in LDAP, OAuth, or SAML will be automatically added or removed as members of corresponding teams in Grafana. Whenever a user logs in, Grafana will check for any changes in the teams or groups of the authentication provider and update the user's teams in Grafana accordingly. This makes it easy to manage user permissions across multiple systems.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Available in [Grafana Enterprise](../../../introduction/grafana-enterprise/) and [Grafana Cloud Advanced](/docs/grafana-cloud/).
{{% /admonition %}}
{{</admonition>}}
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Team synchronization occurs only when a user logs in. However, if you are using LDAP, it is possible to enable active background synchronization. This allows for the continuous synchronization of teams.
{{% /admonition %}}
{{</admonition>}}
### Role Sync
@ -207,14 +207,14 @@ Organization sync is the process of binding all the users from an organization i
With organization sync, users from identity provider groups can be assigned to corresponding Grafana organizations. This functionality is similar to role sync but with the added benefit of specifying the organization that a user belongs to for a particular identity provider group. Please note that this feature is only available for self-hosted Grafana instances, as Cloud Grafana instances have a single organization limit.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Organization sync is currently only supported for SAML and LDAP.
{{% /admonition %}}
{{</admonition>}}
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
You don't need to invite users through Grafana when syncing with Organization sync.
{{% /admonition %}}
{{</admonition>}}
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Currently, only basic roles can be mapped via Organization sync.
@ -37,9 +37,9 @@ Grafana supports the following operating systems:
- [macOS](mac/)
- [Windows](windows/)
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Installation of Grafana on other operating systems is possible, but is not recommended or supported.
{{% /admonition %}}
{{</admonition>}}
## Hardware recommendations
@ -66,20 +66,20 @@ Grafana supports the following databases:
By default Grafana uses an embedded SQLite database, which is stored in the Grafana installation location.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
SQLite works well if your environment is small, but is not recommended when your environment starts growing. For more information about the limitations of SQLite, refer to [Appropriate Uses For SQLite](https://www.sqlite.org/whentouse.html). If you want [high availability](/docs/grafana/latest/setup-grafana/set-up-for-high-availability), you must use either a MySQL or PostgreSQL database. For information about how to define the database configuration parameters inside the `grafana.ini` file, refer to [[database]](/docs/grafana/latest/setup-grafana/configure-grafana/#database).
{{% /admonition %}}
{{</admonition>}}
Grafana supports the versions of these databases that are officially supported by the project at the time a version of Grafana is released. When a Grafana version becomes unsupported, Grafana Labs might also drop support for that database version. See the links above for the support policies for each project.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
PostgreSQL versions 10.9, 11.4, and 12-beta2 are affected by a bug (tracked by the PostgreSQL project as [bug #15865](https://www.postgresql.org/message-id/flat/15865-17940eacc8f8b081%40postgresql.org)) which prevents those versions from being used with Grafana. The bug has been fixed in more recent versions of PostgreSQL.
{{% /admonition %}}
{{</admonition>}}
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Grafana binaries and images might not work with unsupported databases, even if they claim to be drop-in or replicate the API to their best.
Binaries and images built with [BoringCrypto](https://pkg.go.dev/crypto/internal/boring) may have different problems than other distributions of Grafana.
{{% /admonition %}}
{{</admonition>}}
> Grafana can report errors when relying on read-only MySQL servers, such as in high-availability failover scenarios or serverless AWS Aurora MySQL. This is a known issue; for more information, see [issue #13399](https://github.com/grafana/grafana/issues/13399).
@ -87,9 +87,9 @@ Binaries and images built with [BoringCrypto](https://pkg.go.dev/crypto/internal
Grafana supports the current version of the following browsers. Older versions of these browsers might not be supported, so you should always upgrade to the latest browser version when using Grafana.
{{% admonition type="note" %}}
{{<admonitiontype="note">}}
Enable JavaScript in your browser. Running Grafana without JavaScript enabled in the browser is not supported.
> **Note:** If you want to specify the version of a plugin, add the version number to the `GF_PLUGINS_PREINSTALL` environment variable. For example: `-e "GF_PLUGINS_PREINSTALL=grafana-clock-panel@1.0.1,grafana-simple-json-datasource@1.3.5"`. If you do not specify a version number, the latest version is used.
{{<admonitiontype="note">}}
If you want to specify the version of a plugin, add the version number to the `GF_PLUGINS_PREINSTALL` environment variable. For example: `-e "GF_PLUGINS_PREINSTALL=grafana-clock-panel@1.0.1,grafana-simple-json-datasource@1.3.5"`. If you do not specify a version number, the latest version is used.
Depending on your use case requirements, you can use a single YAML file that contains your configuration changes or you can create multiple YAML files.
Jacob Valdez
1 month ago
committed by