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

Restructure IAM documentation (#112929)

Browse Source 
Co-authored-by: Misi <mgyongyosi@users.noreply.github.com>
This commit is contained in:
Jack Baldry
2025-10-24 12:54:59 +01:00
committed by GitHub
co-authored by Misi
parent 5b717af829
commit e48eaa567e
70 changed files with 375 additions and 279 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/setup-grafana/configure-access/_index.md
+213
View File
@@ -0,0 +1,213 @@
---
aliases:
- ../setup-grafana/configure-security/planning-iam-strategy/ # /docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/planning-iam-strategy/
- ./configure-security/planning-iam-strategy/ # /docs/grafana/next/setup-grafana/configure-security/planning-iam-strategy/
title: Plan your IAM integration strategy
menuTitle: Configure access management
description: Learn how to plan your identity and access management strategy before setting up Grafana.
weight: 700
keywords:
- IdP
- IAM
- Auth
- Grafana
---
# Plan your IAM integration strategy
This section describes the decisions you should make when using an Identity and Access Management (IAM) provider to manage access to Grafana. IAM ensures that users have secure access to sensitive data and [other resources](../../administration/data-source-management/), simplifying user management and authentication.
## Benefits of integrating with an IAM provider
Integrating with an IAM provider provides the following benefits:
- **User management**: By providing Grafana access to your current user management system, you eliminate the overhead of replicating user information and instead have centralized user management for users' roles and permissions to Grafana resources.
- **Security**: Many IAM solutions provide advanced security features such as multi-factor authentication, RBAC, and audit trails, which can help to improve the security of your Grafana installation.
- **SSO**: Properly setting up Grafana with your current IAM solution enables users to access Grafana with the same credentials they use for other applications.
- **Scalability**: User additions and updates in your user database are immediately reflected in Grafana.
In order to plan an integration with Grafana, assess your organization's current needs, requirements, and any existing IAM solutions being used. This includes thinking about how roles and permissions will be mapped to users in Grafana and how users can be grouped to access shared resources.
## Internal vs external users
As a first step, determine how you want to manage users who will access Grafana.
Do you already use an identity provider to manage users? If so, Grafana might be able to integrate with your identity provider through one of our IdP integrations.
Refer to [Configure authentication documentation](../configure-access/configure-authentication/) for the list of supported providers.
If you are not interested in setting up an external identity provider, but still want to limit access to your Grafana instance, consider using Grafana's basic authentication.
Finally, if you want your Grafana instance to be accessible to everyone, you can enable anonymous access to Grafana.
For information, refer to the [anonymous authentication documentation](../configure-access/configure-authentication/#anonymous-authentication).
## Ways to organize users
Organize users in subgroups that are sensible to the organization. For example:
- **Security**: Different groups of users or customers should only have access to their intended resources.
- **Simplicity**: Reduce the scope of dashboards and resources available.
- **Cost attribution**: Track and bill costs to individual customers, departments, or divisions.
- **Customization**: Each group of users could have a personalized experience like different dashboards or theme colors.
### Users in Grafana teams
You can organize users into [teams](../../administration/team-management/) and assign them roles and permissions reflecting the current organization. For example, instead of assigning five users access to the same dashboard, you can create a team of those users and assign dashboard permissions to the team.
A user can belong to multiple teams and be a member or an administrator for a given team. Team members inherit permissions from the team but cannot edit the team itself. Team administrators can add members to a team and update its settings, such as the team name, team members, roles assigned, and UI preferences.
Teams are a perfect solution for working with a subset of users. Teams can share resources with other teams.
### Users in Grafana organizations
[Grafana organizations](../../administration/organization-management/) allow complete isolation of resources, such as dashboards and data sources. Users can be members of one or several organizations, and they can only access resources from an organization they belong to.
Having multiple organizations in a single instance of Grafana lets you manage your users in one place while completely separating resources.
Organizations provide a higher measure of isolation within Grafana than teams do and can be helpful in certain scenarios. However, because organizations lack the scalability and flexibility of teams and [folders](../../dashboards/manage-dashboards/#create-a-dashboard-folder), we do not recommend using them as the default way to group users and resources.
Note that Grafana Cloud does not support having more than 1 organizations per instance.
### Choosing between teams and organizations
[Grafana teams](../../administration/team-management/) and Grafana organizations serve similar purposes in the Grafana platform. Both are designed to help group users and manage and control access to resources.
Teams provide more flexibility, as resources can be accessible by multiple teams, and team creation and management are simple.
In contrast, organizations provide more isolation than teams, as resources cannot be shared between organizations.
They are more difficult to manage than teams, as you must create and update resources for each organization individually.
Organizations cater to bigger companies or users with intricate access needs, necessitating complete resource segregation.
## Access to external systems
Consider the need for machine-to-machine [M2M](https://en.wikipedia.org/wiki/Machine_to_machine) communications. If a system needs to interact with Grafana, ensure it has proper access.
Consider the following scenarios:
**Schedule reports**: Generate reports periodically from Grafana through the reporting API and have them delivered to different communications channels like email, instant messaging, or keep them in a shared storage.
**Define alerts**: Define alert rules to be triggered when a specific condition is met. Route alert notifications to different teams according to your organization's needs.
**Provisioning file**: Provisioning files can be used to automate the creation of dashboards, data sources, and other resources.
These are just a few examples of how Grafana can be used in M2M scenarios. The platform is highly flexible and can be used in various M2M applications, making it a powerful tool for organizations seeking insights into their systems and devices.
### Service accounts
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" >}}
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 >}}
A common use case for creating a service account is to perform operations on automated or triggered tasks. You can use service accounts to:
- Schedule reports for specific dashboards to be delivered on a daily/weekly/monthly basis
- Define alerts in your system to be used in Grafana
- Set up an external SAML authentication provider
- Interact with Grafana without signing in as a user
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" >}}
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 >}}
The following video shows how to migrate from API keys to service accounts.
{{< vimeo 742056367 >}}
<br>
#### Service account tokens
To authenticate with Grafana's HTTP API, a randomly generated string known as a service account token can be used as an alternative to a password.
When a service account is created, it can be linked to multiple access tokens. These service access tokens can be utilized in the same manner as API keys, providing a means to programmatically access Grafana HTTP API.
You can create multiple tokens for the same service account. You might want to do this if:
- 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" >}}
In Grafana's audit logs it will still show up as the same service account.
{{< /admonition >}}
Service account access tokens inherit permissions from the service account.
## How to work with roles?
Grafana roles control the access of users and service accounts to specific resources and determine their authorized actions.
You can assign roles through the user interface or APIs, establish them through Terraform, or synchronize them automatically via an external IAM provider.
### What are roles?
Within an organization, Grafana has established three primary [organization roles](../../administration/roles-and-permissions/#organization-roles) - organization administrator, editor, and viewer - which dictate the user's level of access and permissions, including the ability to edit data sources or create teams. Grafana also has an empty role that you can start with and to which you can gradually add custom permissions.
To be a member of any organization, every user must be assigned a role.
In addition, Grafana provides a server administrator role that grants access to and enables interaction with resources that affect the entire instance, including organizations, users, and server-wide settings.
This particular role can only be accessed by users of self-hosted Grafana instances. It is a significant role intended for the administrators of the Grafana instance.
### What are permissions?
Each role consists of a set of [permissions](../../administration/roles-and-permissions/#dashboard-permissions) that determine the tasks a user can perform in the system.
For example, the **Admin** role includes permissions that let an administrator create and delete users.
Grafana allows for precise permission settings on both dashboards and folders, giving you the ability to control which users and teams can view, edit, and administer them.
For example, you might want a certain viewer to be able to edit a dashboard. While that user can see all dashboards, you can grant them access to update only one of them.
In [Grafana Enterprise](../../introduction/grafana-enterprise/), you can also grant granular permissions for data sources to control who can query and edit them.
Dashboard, folder, and data source permissions can be set through the UI or APIs or provisioned through Terraform.
### Role-based access control
{{< admonition type="note" >}}
Available in [Grafana Enterprise](../../introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud/).
{{< /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.
RBAC comes with pre-defined roles, such as data source writer, which allows updating, reading, or querying all data sources.
You can assign these roles to users, teams, and service accounts.
In addition, RBAC empowers you to generate personalized roles and modify permissions authorized by the standard Grafana roles.
## User synchronization between Grafana and identity providers
When connecting Grafana to an identity provider, it's important to think beyond just the initial authentication setup. You should also think about the maintenance of user bases and roles. Using Grafana's team and role synchronization features ensures that updates you make to a user in your identity provider will be reflected in their role assignment and team memberships in Grafana.
### Team sync
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" >}}
Available in [Grafana Enterprise](../../introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
{{< admonition type="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 >}}
### Role Sync
Grafana can synchronize basic roles from your authentication provider by mapping attributes from the identity provider to the user role in Grafana. This means that users with specific attributes, like role, team, or group membership in LDAP, OAuth, or SAML, can be automatically assigned the corresponding role in Grafana. Whenever a user logs in, Grafana checks for any changes in the user information retrieved from the authentication provider and updates the user's role in Grafana accordingly.
### Organization sync
Organization sync is the process of binding all the users from an organization in Grafana. This delegates the role of managing users to the identity provider. This way, there's no need to manage user access from Grafana because the identity provider will be queried whenever a new user tries to log in.
With organization sync, you can assign users from identity provider groups 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" >}}
The following applies:
- Organization sync is currently only supported for SAML and LDAP.
- You can only map basic roles with Organization sync.
- You don't need to invite users through Grafana when syncing with Organization sync.
{{< /admonition >}}
docs/sources/setup-grafana/configure-access/configure-authentication/_index.md
+245
View File
@@ -0,0 +1,245 @@
---
aliases:
- ../../auth/ # /docs/grafana/next/auth/
- ../../auth/overview/ # /docs/grafana/next/auth/overview/
- ../setup-grafana/configure-security/configure-authentication/ # /docs/grafana/next/setup-grafana/setup-grafana/configure-security/configure-authentication/
- ../configure-security/configure-authentication/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/
description: Learn about all the ways in which you can configure Grafana to authenticate users.
labels:
products:
- cloud
- enterprise
- oss
title: Configure authentication
weight: 100
---
# Configure authentication
Grafana provides many ways to authenticate users. Some authentication integrations also enable syncing user permissions and org memberships.
The following table shows all supported authentication methods and the features available for them. [Team sync](../configure-team-sync/) and [active sync](enhanced-ldap/#active-ldap-synchronization) are only available in Grafana Enterprise.
| Authentication method | Multi Org Mapping | Enforce Sync | Role Mapping | Grafana Admin Mapping | Team Sync | Allowed groups | Active Sync | Skip OrgRole mapping | Auto Login | Single Logout | SCIM support |
| :---------------------------------- | :---------------- | :----------- | :----------- | :-------------------- | :-------- | :------------- | :---------- | :------------------- | :--------- | :------------ | :----------- |
| [Anonymous access](anonymous-auth/) | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A | N/A |
| [Auth Proxy](auth-proxy/) | no | yes | yes | no | yes | no | N/A | no | N/A | N/A | N/A |
| [Entra ID OAuth](azuread/) | yes | yes | yes | yes | yes | yes | N/A | yes | yes | yes | N/A |
| [Basic auth](grafana/) | yes | N/A | yes | yes | N/A | N/A | N/A | N/A | N/A | N/A | N/A |
| [Passwordless auth](passwordless/) | yes | N/A | yes | yes | N/A | N/A | N/A | N/A | N/A | N/A | N/A |
| [Generic OAuth](generic-oauth/) | yes | yes | yes | yes | yes | no | N/A | yes | yes | yes | N/A |
| [GitHub OAuth](github/) | yes | yes | yes | yes | yes | yes | N/A | yes | yes | yes | N/A |
| [GitLab OAuth](gitlab/) | yes | yes | yes | yes | yes | yes | N/A | yes | yes | yes | N/A |
| [Google OAuth](google/) | yes | no | no | no | yes | no | N/A | no | yes | yes | N/A |
| [Grafana.com OAuth](grafana-cloud/) | no | no | yes | no | N/A | N/A | N/A | yes | yes | yes | N/A |
| [Okta OAuth](okta/) | yes | yes | yes | yes | yes | yes | N/A | yes | yes | yes | N/A |
| [SAML](saml/) (Enterprise only) | yes | yes | yes | yes | yes | yes | N/A | yes | yes | yes | yes |
| [LDAP](ldap/) | yes | yes | yes | yes | yes | yes | yes | no | N/A | N/A | N/A |
| [JWT Proxy](jwt/) | no | yes | yes | yes | no | no | N/A | no | N/A | N/A | N/A |
Fields explanation:
**Multi Org Mapping:** Able to add a user and map roles to multiple organizations
**Enforce Sync:** If the information provided by the identity provider is empty, does the integration skip setting that user’s field or does it enforce a default.
**Role Mapping:** Able to map a user’s role in the default org
**Grafana Admin Mapping:** Able to map a user’s admin role in the default org
**Team Sync:** Able to sync teams from a predefined group/team in a your IdP
**Allowed Groups:** Only allow members of certain groups to login
**Active Sync:** Add users to teams and update their profile without requiring them to log in
**Skip OrgRole Sync:** Able to modify org role for users and not sync it back to the IdP
**Auto Login:** Automatically redirects to provider login page if user is not logged in \* for OAuth; Only works if it's the only configured provider
**Single Logout:** Logging out from Grafana also logs you out of provider session
**SCIM support:** Support for SCIM provisioning. Supported Identity Providers are Entra ID and Okta.
## Configuring multiple identity providers
Grafana allows you to configure more than one authentication provider, however it is not possible to configure the same type of authentication provider twice.
For example, you can have [SAML](saml/) (Enterprise only) and [Generic OAuth](generic-oauth/) configured, but you can not have two different [Generic OAuth](generic-oauth/) configurations.
> Note: Grafana does not support multiple identity providers resolving the same user. Ensure there are no user account overlaps between the different providers
In scenarios where you have multiple identity providers of the same type, there are a couple of options:
- Use different Grafana instances each configured with a given identity provider.
- Check if the identity provider supports account federation. In such cases, you can configure it once and let your identity provider federate the accounts from different providers.
- If SAML is supported by the identity provider, you can configure one [Generic OAuth](generic-oauth/) and one [SAML](saml/) (Enterprise only).
## Using the same email address to login with different identity providers
If users want to use the same email address with multiple identity providers (for example, Grafana.Com OAuth and Google OAuth), you can configure Grafana to use the email address as the unique identifier for the user. This is done by enabling the `oauth_allow_insecure_email_lookup` option, which is disabled by default. Please note that enabling this option can lower the security of your Grafana instance. If you enable this option, you should also ensure that the `Allowed organization`, `Allowed groups` and `Allowed domains` settings are configured correctly to prevent unauthorized access.
To enable this option, refer to the [Enable email lookup](#enable-email-lookup) section.
## Multi-factor authentication (MFA/2FA)
Grafana and the Grafana Cloud portal currently do not include built-in support for multi-factor authentication (MFA).
We strongly recommend integrating an external identity provider (IdP) that supports MFA, such as Okta, Entra ID, or Google Workspace. By configuring your Grafana instances to use an external IdP, you can leverage MFA to protect your accounts and resources effectively.
## Login and short-lived tokens
> The following applies when using Grafana's basic authentication, LDAP (without Auth proxy) or OAuth integration.
Grafana uses short-lived tokens as a mechanism for verifying authenticated users.
These short-lived tokens are rotated on an interval specified by `token_rotation_interval_minutes` for active authenticated users.
Inactive authenticated users will remain logged in for a duration specified by `login_maximum_inactive_lifetime_duration`.
This means that a user can close a Grafana window and return before `now + login_maximum_inactive_lifetime_duration` to continue their session.
This is true as long as the time since last user login is less than `login_maximum_lifetime_duration`.
## Session handling with SSO
When using SSO (Single Sign-On) authentication methods, Grafana handles sessions differently based on the configuration:
### OAuth/OpenID Connect
- Without refresh tokens (default):
- Grafana creates a session valid for up to `login_maximum_lifetime_duration` (default: 30 days).
- During this time, the session remains valid even if the user loses access at the IdP.
- With refresh tokens enabled:
- The user receives a JWT refresh token. When the JWT expires and the refresh token is used to obtain a new token, Grafana will revalidate access with the IdP.
- If the user has been removed from required groups or access has been revoked, the refresh will fail and the session will be invalidated.
### SAML
- After successful SAML authentication, Grafana creates a session with the default session lifetime.
- If SAML Single Logout (SLO) is properly configured, the session will be revoked when the user's access is revoked on the IdP side.
- If SAML Single Logout (SLO) is properly configured, the session will be revoked when the user's access is revoked on the IdP side. For more information on configuring SAML and SLO, refer to the [SAML configuration documentation](./saml/#configure-single-logout).
## Settings
Example:
```bash
[auth]
# Login cookie name
login_cookie_name = grafana_session
# The maximum lifetime (duration) an authenticated user can be inactive before being required to login at next visit. Default is 7 days (7d). This setting should be expressed as a duration, e.g. 5m (minutes), 6h (hours), 10d (days), 2w (weeks), 1M (month). The lifetime resets at each successful token rotation (token_rotation_interval_minutes).
login_maximum_inactive_lifetime_duration =
# The maximum lifetime (duration) an authenticated user can be logged in since login time before being required to login. Default is 30 days (30d). This setting should be expressed as a duration, e.g. 5m (minutes), 6h (hours), 10d (days), 2w (weeks), 1M (month).
login_maximum_lifetime_duration =
# How often should auth tokens be rotated for authenticated users when being active. The default is every 10 minutes.
token_rotation_interval_minutes = 10
# The maximum lifetime (seconds) an API key can be used. If it is set all the API keys should have limited lifetime that is lower than this value.
api_key_max_seconds_to_live = -1
# Enforce user lookup based on email instead of the unique ID provided by the IdP.
oauth_allow_insecure_email_lookup = false
```
## Extended authentication settings
### Enable email lookup
By default, Grafana identifies users based on the unique ID provided by the identity provider (IdP).
In certain cases, however, enabling user lookups by email can be a feasible option, such as when:
- The identity provider is a single-tenant setup.
- Unique, validated, and non-editable emails are provided by the IdP.
- The infrastructure allows email-based identification without compromising security.
**Important note**: While it is possible to configure Grafana to allow email-based user lookups, we strongly recommend against this approach in most cases due to potential security risks.
If you still choose to proceed, the following configuration can be applied to enable email lookup.
```bash
[auth]
oauth_allow_insecure_email_lookup = true
```
You can also enable email lookup using the API:
{{< admonition type="note" >}}
Available in [Grafana Enterprise](../../../introduction/grafana-enterprise/) and [Grafana Cloud](../../../introduction/grafana-cloud/) since Grafana v10.4.
{{< /admonition >}}
```
curl --request PUT \
--url http://{slug}.grafana.com/api/admin/settings \
--header 'Authorization: Bearer glsa_yourserviceaccounttoken' \
--header 'Content-Type: application/json' \
--data '{ "updates": { "auth": { "oauth_allow_insecure_email_lookup": "true" }}}'
```
Finally, you can also enable it using the UI by going to **Administration -> Authentication -> Auth settings**.
### Automatic OAuth login
Set to true to attempt login with specific OAuth provider automatically, skipping the login screen.
This setting is ignored if multiple auth providers are configured to use auto login.
Defaults to `false`.
```bash
[auth.generic_oauth]
auto_login = true
```
### Avoid automatic login
The `disableAutoLogin=true` URL parameter allows users to bypass the automatic login feature in scenarios where incorrect configuration changes prevent normal login functionality.
This feature is especially helpful when you need to access the login screen to troubleshoot and fix misconfigurations.
#### How to use
1. Add `disableAutoLogin=true` as a query parameter to your Grafana URL.
- Example: `grafana.example.net/login?disableAutoLogin=true` or `grafana.example.net/login?disableAutoLogin`
1. This will redirect you to the standard login screen, bypassing the automatic login mechanism.
1. Fix any configuration issues and test your login setup.
This feature is available for both for OAuth and SAML. Ensure that after fixing the issue, you remove the parameter or revert the configuration to re-enable the automatic login feature, if desired.
### Hide sign-out menu
Set the option detailed below to true to hide sign-out menu link. Useful if you use an auth proxy or JWT authentication.
```bash
[auth]
disable_signout_menu = true
```
### URL redirect after signing out
URL to redirect the user to after signing out from Grafana. This can for example be used to enable signout from an OAuth provider.
Example for Generic OAuth:
```bash
[auth.generic_oauth]
signout_redirect_url =
```
### Remote logout
You can log out from other devices by removing login sessions from the bottom of your profile page. If you are
a Grafana admin user, you can also do the same for any user from the Server Admin / Edit User view.
### Protected roles
{{< admonition type="note" >}}
Available in [Grafana Enterprise](../../../introduction/grafana-enterprise/) and [Grafana Cloud](../../../introduction/grafana-cloud/).
{{< /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.
You can disable this user adoption for certain roles using the `protected_roles` property:
```bash
[auth.security]
protected_roles = server_admins org_admins
```
The value of `protected_roles` should be a list of roles to protect, separated by spaces. Valid roles are `viewers`, `editors`, `org_admins`, `server_admins`, and `all` (a superset of the other roles).
docs/sources/setup-grafana/configure-access/configure-authentication/anonymous-auth/index.md
+69
View File
@@ -0,0 +1,69 @@
---
aliases:
- ../../../auth/anonymous-auth/ # /docs/grafana/next/auth/anonymous-auth/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/anonymous-auth/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/anonymous-auth/
- ../../configure-security/configure-authentication/anonymous-auth/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/anonymous-auth/
description: Learn how to configure anonymous access in Grafana
labels:
products:
- enterprise
- oss
menuTitle: Anonymous access
title: Configure anonymous access
weight: 250
---
# Anonymous authentication
You can make Grafana accessible without any login required by enabling anonymous access in the configuration file.
{{< admonition type="note" >}}
Anonymous users are charged as active users in Grafana Enterprise
{{< /admonition >}}
## Before you begin
To see the devices, you need:
- Permissions `users:read` which is normally only granted to server admins, that allow you to read users and devices tab.
## Anonymous devices
The anonymous devices feature enhances the management and monitoring of anonymous access within your Grafana instance. This feature is part of ongoing efforts to provide more control and transparency over anonymous usage.
Users can now view anonymous usage statistics, including the count of devices and users over the last 30 days.
- Go to **Administration -> Users** to access the anonymous devices tab.
- A new stat for the usage stats page -> Usage & Stats page shows the active anonymous devices last 30 days.
The number of anonymous devices is not limited by default. The configuration option `device_limit` allows you to enforce a limit on the number of anonymous devices. This enables you to have greater control over the usage within your Grafana instance and keep the usage within the limits of your environment. Once the limit is reached, any new devices that try to access Grafana will be denied access.
To display anonymous users and devices for versions 10.2, 10.3, 10.4, you need to enable the feature toggle `displayAnonymousStats`
```bash
[feature_toggles]
enable = displayAnonymousStats
```
## Configuration
Example:
```bash
[auth.anonymous]
enabled = true
# Organization name that should be used for unauthenticated users
org_name = Main Org.
# Role for unauthenticated users, other valid values are `Editor` and `Admin`
org_role = Viewer
# Hide the Grafana version text from the footer and help tooltip for unauthenticated users (default: false)
hide_version = true
# Setting this limits the number of anonymous devices in your instance. Any new anonymous devices added after the limit has been reached will be denied access.
device_limit =
```
If you change your organization name in the Grafana UI this setting needs to be updated to match the new name.
docs/sources/setup-grafana/configure-access/configure-authentication/auth-proxy/index.md
+328
View File
@@ -0,0 +1,328 @@
---
aliases:
- ../../../auth/auth-proxy/ # /docs/grafana/next/auth/auth-proxy/
- ../../../tutorials/authproxy/ # /docs/grafana/next/tutorials/authproxy/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/authproxy/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/authproxy/
- ../../configure-security/configure-authentication/auth-proxy/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/auth-proxy/
description: Grafana Auth Proxy Guide
keywords:
- grafana
- configuration
- documentation
- proxy
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Auth proxy
title: Configure auth proxy authentication
weight: 1500
---
# Configure auth proxy authentication
You can configure Grafana to let a HTTP reverse proxy handle authentication. Popular web servers have a very
extensive list of pluggable authentication modules, and any of them can be used with the AuthProxy feature.
Below we detail the configuration options for auth proxy.
```bash
[auth.proxy]
# Defaults to false, but set to true to enable this feature
enabled = true
# HTTP Header name that will contain the username or email
header_name = X-WEBAUTH-USER
# HTTP Header property, defaults to `username` but can also be `email`
header_property = username
# Set to `true` to enable auto sign up of users who do not exist in Grafana DB. Defaults to `true`.
auto_sign_up = true
# Define cache time to live in minutes
# If combined with Grafana LDAP integration it is also the sync interval
# Set to 0 to always fetch and sync the latest user data
sync_ttl = 15
# Limit where auth proxy requests come from by configuring a list of IP addresses.
# This can be used to prevent users spoofing the X-WEBAUTH-USER header.
# Example `whitelist = 192.168.1.1, 192.168.1.0/24, 2001::23, 2001::0/120`
whitelist =
# Optionally define more headers to sync other user attributes
# Example `headers = Name:X-WEBAUTH-NAME Role:X-WEBAUTH-ROLE Email:X-WEBAUTH-EMAIL Groups:X-WEBAUTH-GROUPS`
headers =
# Non-ASCII strings in header values are encoded using quoted-printable encoding
;headers_encoded = false
# Check out docs on this for more details on the below setting
enable_login_token = false
```
## Interacting with Grafana’s AuthProxy via curl
```bash
curl -H "X-WEBAUTH-USER: admin" http://localhost:3000/api/users
[
{
"id":1,
"name":"",
"login":"admin",
"email":"admin@localhost",
"isAdmin":true
}
]
```
We can then send a second request to the `/api/user` method which will return the details of the logged in user. We will use this request to show how Grafana automatically adds the new user we specify to the system. Here we create a new user called “anthony”.
```bash
curl -H "X-WEBAUTH-USER: anthony" http://localhost:3000/api/user
{
"email":"anthony",
"name":"",
"login":"anthony",
"theme":"",
"orgId":1,
"isGrafanaAdmin":false
}
```
## Making Apache’s auth work together with Grafana’s AuthProxy
I’ll demonstrate how to use Apache for authenticating users. In this example we use BasicAuth with Apache’s text file based authentication handler, i.e. htpasswd files. However, any available Apache authentication capabilities could be used.
### Apache BasicAuth
In this example we use Apache as a reverse proxy in front of Grafana. Apache handles the Authentication of users before forwarding requests to the Grafana backend service.
#### Apache configuration
```bash
<VirtualHost *:80>
ServerAdmin webmaster@authproxy
ServerName authproxy
ErrorLog "logs/authproxy-error_log"
CustomLog "logs/authproxy-access_log" common
<Proxy *>
AuthType Basic
AuthName GrafanaAuthProxy
AuthBasicProvider file
AuthUserFile /etc/apache2/grafana_htpasswd
Require valid-user
RewriteEngine On
RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS]
RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e"
</Proxy>
RequestHeader unset Authorization
ProxyRequests Off
ProxyPass / http://localhost:3000/
ProxyPassReverse / http://localhost:3000/
</VirtualHost>
```
- The first four lines of the virtualhost configuration are standard, so we won’t go into detail on what they do.
- We use a **\<proxy>** configuration block for applying our authentication rules to every proxied request. These rules include requiring basic authentication where user:password credentials are stored in the **/etc/apache2/grafana_htpasswd** file. This file can be created with the `htpasswd` command.
- The next part of the configuration is the tricky part. We use Apache’s rewrite engine to create our **X-WEBAUTH-USER header**, populated with the authenticated user.
- **RewriteRule .\* - [E=PROXY_USER:%{LA-U:REMOTE_USER}, NS]**: This line is a little bit of magic. What it does, is for every request use the rewriteEngines look-ahead (LA-U) feature to determine what the REMOTE_USER variable would be set to after processing the request. Then assign the result to the variable PROXY_USER. This is necessary as the REMOTE_USER variable is not available to the RequestHeader function.
- **RequestHeader set X-WEBAUTH-USER “%{PROXY_USER}e”**: With the authenticated username now stored in the PROXY_USER variable, we create a new HTTP request header that will be sent to our backend Grafana containing the username.
- The **RequestHeader unset Authorization** removes the Authorization header from the HTTP request before it is forwarded to Grafana. This ensures that Grafana does not try to authenticate the user using these credentials (BasicAuth is a supported authentication handler in Grafana).
- The last 3 lines are then just standard reverse proxy configuration to direct all authenticated requests to our Grafana server running on port 3000.
## Full walkthrough using Docker.
For this example, we use the official Grafana Docker image available at [Docker Hub](https://hub.docker.com/r/grafana/grafana/).
- Create a file `grafana.ini` with the following contents
```bash
[users]
allow_sign_up = false
auto_assign_org = true
auto_assign_org_role = Editor
[auth.proxy]
enabled = true
header_name = X-WEBAUTH-USER
header_property = username
auto_sign_up = true
```
Launch the Grafana container, using our custom `grafana.ini` to replace `/etc/grafana/grafana.ini`. We don't expose
any ports for this container as it will only be connected to by our Apache container.
```bash
docker run -i -v $(pwd)/grafana.ini:/etc/grafana/grafana.ini --name grafana grafana/grafana
```
### Apache Container
For this example we use the official Apache docker image available at [Docker Hub](https://hub.docker.com/_/httpd/)
- Create a file named `httpd.conf` with the following contents
```bash
ServerRoot "/usr/local/apache2"
Listen 80
LoadModule mpm_event_module modules/mod_mpm_event.so
LoadModule authn_file_module modules/mod_authn_file.so
LoadModule authn_core_module modules/mod_authn_core.so
LoadModule authz_host_module modules/mod_authz_host.so
LoadModule authz_user_module modules/mod_authz_user.so
LoadModule authz_core_module modules/mod_authz_core.so
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule log_config_module modules/mod_log_config.so
LoadModule env_module modules/mod_env.so
LoadModule headers_module modules/mod_headers.so
LoadModule unixd_module modules/mod_unixd.so
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
<IfModule unixd_module>
User daemon
Group daemon
</IfModule>
ServerAdmin you@example.com
<Directory />
AllowOverride none
Require all denied
</Directory>
DocumentRoot "/usr/local/apache2/htdocs"
ErrorLog /proc/self/fd/2
LogLevel error
<IfModule log_config_module>
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
LogFormat "%h %l %u %t \"%r\" %>s %b" common
<IfModule logio_module>
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %I %O" combinedio
</IfModule>
CustomLog /proc/self/fd/1 common
</IfModule>
<Proxy *>
AuthType Basic
AuthName GrafanaAuthProxy
AuthBasicProvider file
AuthUserFile /tmp/htpasswd
Require valid-user
RewriteEngine On
RewriteRule .* - [E=PROXY_USER:%{LA-U:REMOTE_USER},NS]
RequestHeader set X-WEBAUTH-USER "%{PROXY_USER}e"
</Proxy>
RequestHeader unset Authorization
ProxyRequests Off
ProxyPass / http://grafana:3000/
ProxyPassReverse / http://grafana:3000/
```
- Create a `htpasswd` file. We create a new user **anthony** with the password **password**
```bash
htpasswd -bc htpasswd anthony password
```
- 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.
```bash
docker run -i -p 80:80 --link grafana:grafana -v $(pwd)/httpd.conf:/usr/local/apache2/conf/httpd.conf -v $(pwd)/htpasswd:/tmp/htpasswd httpd:2.4
```
### Use grafana.
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" >}}
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.
{{< /admonition >}}
### Team Sync
{{< admonition type="note" >}}
Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
With Team Sync, it's possible to set up synchronization between teams in your authentication provider and Grafana. You can send Grafana values as part of an HTTP header and have Grafana map them to your team structure. This allows you to put users into specific teams automatically.
To support the feature, auth proxy allows optional headers to map additional user attributes. The specific attribute to support team sync is `Groups`.
```bash
# Optionally define more headers to sync other user attributes
headers = "Groups:X-WEBAUTH-GROUPS"
```
You use the `X-WEBAUTH-GROUPS` header to send the team information for each user. Specifically, the set of Grafana's group IDs that the user belongs to.
First, we need to set up the mapping between your authentication provider and Grafana. Follow [these instructions](../../configure-team-sync/#synchronize-a-grafana-team-with-an-external-group) to add groups to a team within Grafana.
Once that's done. You can verify your mappings by querying the API.
```bash
# First, inspect your teams and obtain the corresponding ID of the team we want to inspect the groups for.
curl -H "X-WEBAUTH-USER: admin" -H "X-WEBAUTH-GROUPS: lokiteamOnExternalSystem" http://localhost:3000/api/teams/search
{
"totalCount": 2,
"teams": [
{
"id": 1,
"orgId": 1,
"name": "Core",
"email": "core@grafana.com",
"avatarUrl": "/avatar/327a5353552d2dc3966e2e646908f540",
"memberCount": 1,
"permission": 0
},
{
"id": 2,
"orgId": 1,
"name": "Loki",
"email": "loki@grafana.com",
"avatarUrl": "/avatar/102f937d5344d33fdb37b65d430f36ef",
"memberCount": 0,
"permission": 0
}
],
"page": 1,
"perPage": 1000
}
# Then, query the groups for that particular team. In our case, the Loki team which has an ID of "2".
curl -H "X-WEBAUTH-USER: admin" -H "X-WEBAUTH-GROUPS: lokiteamOnExternalSystem" http://localhost:3000/api/teams/2/groups
[
{
"orgId": 1,
"teamId": 2,
"groupId": "lokiTeamOnExternalSystem"
}
]
```
Finally, whenever Grafana receives a request with a header of `X-WEBAUTH-GROUPS: lokiTeamOnExternalSystem`, the user under authentication will be placed into the specified team. Placement in multiple teams is supported by using comma-separated values e.g. `lokiTeamOnExternalSystem,CoreTeamOnExternalSystem`.
```bash
curl -H "X-WEBAUTH-USER: leonard" -H "X-WEBAUTH-GROUPS: lokiteamOnExternalSystem" http://localhost:3000/dashboards/home
{
"meta": {
"isHome": true,
"canSave": false,
...
}
```
With this, the user `leonard` will be automatically placed into the Loki team as part of Grafana authentication.
{{< admonition type="note" >}}
An empty `X-WEBAUTH-GROUPS` or the absence of a groups header will remove the user from all teams.
{{< /admonition >}}
[Learn more about Team Sync](../../configure-team-sync/)
## Login token and session cookie
With `enable_login_token` set to `true` Grafana will, after successful auth proxy header validation, assign the user
a login token and cookie. You only have to configure your auth proxy to provide headers for the /login route.
Requests via other routes will be authenticated using the cookie.
Use the settings `login_maximum_inactive_lifetime_duration` and `login_maximum_lifetime_duration` under `[auth]` to control session
lifetime.
docs/sources/setup-grafana/configure-access/configure-authentication/enhanced-ldap/index.md
+93
View File
@@ -0,0 +1,93 @@
---
aliases:
- ../../../enterprise/enhanced_ldap/ # /docs/grafana/next/enterprise/enhanced_ldap/
- ../../../auth/enhanced_ldap/ # /docs/grafana/next/auth/enhanced_ldap/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/enhanced_ldap/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/enhanced_ldap/
- ../../configure-security/configure-authentication/enhanced-ldap/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/enhanced-ldap/
description: Grafana Enhanced LDAP Integration Guide
keywords:
- grafana
- configuration
- documentation
- ldap
- active directory
- enterprise
labels:
products:
- cloud
- enterprise
menuTitle: Enhanced LDAP
title: Configure enhanced LDAP integration
weight: 400
---
# Configure enhanced LDAP integration
The enhanced LDAP integration adds additional functionality on top of the [LDAP integration](../ldap/) available in the open source edition of Grafana.
{{< admonition type="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/).
## LDAP group synchronization for teams
With enhanced LDAP integration, you can set up synchronization between LDAP groups and teams. This enables LDAP users that are members
of certain LDAP groups to automatically be added or removed as members to certain teams in Grafana.
![LDAP group synchronization](/static/img/docs/enterprise/team_members_ldap.png)
Grafana keeps track of all synchronized users in teams, and you can see which users have been synchronized from LDAP in the team members list, see `LDAP` label in screenshot.
This mechanism allows Grafana to remove an existing synchronized user from a team when its LDAP group membership changes. This mechanism also allows you to manually add
a user as member of a team, and it will not be removed when the user signs in. This gives you flexibility to combine LDAP group memberships and Grafana team memberships.
[Learn more about team sync.](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-team-sync)
<div class="clearfix"></div>
## Active LDAP synchronization
In the open source version of Grafana, user data from LDAP is synchronized only during the login process when authenticating using LDAP.
With active LDAP synchronization, you can configure Grafana to actively sync users with LDAP servers in the background. Only users that have logged into Grafana at least once are synchronized.
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.
```bash
[auth.ldap]
...
# You can use the Cron syntax or several predefined schedulers -
# @yearly (or @annually) | Run once a year, midnight, Jan. 1st | 0 0 1 1 *
# @monthly | Run once a month, midnight, first of month | 0 0 1 * *
# @weekly | Run once a week, midnight between Sat/Sun | 0 0 * * 0
# @daily (or @midnight) | Run once a day, midnight | 0 0 * * *
# @hourly | Run once an hour, beginning of hour | 0 * * * *
sync_cron = "0 1 * * *" # This is default value (At 1 am every day)
# This cron expression format uses 5 space-separated fields, for example
# sync_cron = "*/10 * * * *"
# This will run the LDAP Synchronization every 10th minute, which is also the minimal interval between the Grafana sync times i.e. you cannot set it for every 9th minute
# You can also disable active LDAP synchronization
active_sync_enabled = true # enabled by default
```
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` 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.
For example:
```
[[servers]]
search_filter = "(sAMAccountName=%s)"
[servers.attributes]
username = "sAMAccountName"
```
If the attributes aren't the same, the users' sessions will be terminated after each synchronization. That's because the search will be done using the username's value, and that value doesn't exist for the attribute used in the search filter.
docs/sources/setup-grafana/configure-access/configure-authentication/entraid/index.md
+561
View File
@@ -0,0 +1,561 @@
---
aliases:
- ../../../auth/azuread/ # /docs/grafana/next/auth/azuread/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/azuread/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/azuread/
- ../../configure-security/configure-authentication/azuread/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/azuread/
- ./azuread/ # /docs/grafana/next/setup-grafana/configure-access/configure-authentication/azuread/
description: Grafana Entra ID OAuth Guide
keywords:
- grafana
- configuration
- documentation
- oauth
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Entra ID OAuth
title: Configure Entra ID OAuth authentication
weight: 800
---
# Configure Entra ID OAuth authentication
The Entra ID 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" >}}
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 >}}
## Create the Microsoft Entra ID application
To enable the Entra ID OAuth, register your application with Entra ID.
1. Log in to [Azure Portal](https://portal.azure.com), then click **Microsoft Entra ID** in the side menu.
1. If you have access to more than one tenant, select your account in the upper right. Set your session to the Entra ID tenant you wish to use.
1. Under **Manage** in the side menu, click **App Registrations** > **New Registration**. Enter a descriptive name.
1. Under **Redirect URI**, select the app type **Web**.
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.
1. Click **Endpoints** from the top menu.
- Note the **OAuth 2.0 authorization endpoint (v2)** URL. This is the authorization URL.
- Note the **OAuth 2.0 token endpoint (v2)**. This is the token URL.
1. Click **Certificates & secrets** in the side menu, then add a new entry under the supported client authentication option you want to use. The following are the supported client authentication options with their respective configuration steps.
- **Client secrets**
1. Add a new entry under **Client secrets** with the following configuration.
- Description: Grafana OAuth 2.0
- Expires: Select an expiration period
1. Click **Add** then copy the key **Value**. This is the OAuth 2.0 client secret.
{{< admonition type="note" >}}
Make sure that you copy the string in the **Value** field, rather than the one in the **Secret ID** field.
{{< /admonition >}}
1. You must have set `client_authentication` under `[auth.azuread]` to `client_secret_post` in the Grafana server configuration for this to work.
- **Federated credentials**
- **_Managed Identity_**
1. Refer to [Configure an application to trust a managed identity (preview)](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-config-app-trust-managed-identity?tabs=microsoft-entra-admin-center) for a complete guide on setting up a managed identity as a federated credential.
Add a new entry under Federated credentials with the following configuration.
- Federated credential scenario: Select **Other issuer**.
- Issuer: The OAuth 2.0 / OIDC issuer URL of the Microsoft Entra ID authority. For example: `https://login.microsoftonline.com/{tenantID}/v2.0`.
- Subject identifier: The Object (Principal) ID GUID of the Managed Identity.
- Name: A unique descriptive name for the credential.
- Description: Grafana OAuth.
- Audience: The audience value that must appear in the external token. For Public cloud, it would be `api://AzureADTokenExchange`. See mentioned documentation for the full list of available audiences.
1. Click **Add**, and then copy the Managed Identity Client ID and the federated credential Audience values. This is your OAuth 2.0 federated credential.
1. You must have set `client_authentication` under `[auth.azuread]` to `managed_identity` in the Grafana server configuration for this to work.
{{< admonition type="note" >}}
Managed identities as federated credentials are only applicable to workloads hosted in Azure.
You can only add user-assigned managed identities as federated credentials on Entra ID applications.
{{< /admonition >}}
- **_Workload Identity (K8s/AKS)_**
1. Refer to [Federated identity credential for an Entra ID application](https://azure.github.io/azure-workload-identity/docs/topics/federated-identity-credential.html#azure-portal-ui) for a complete guide on setting up a federated credential for workload identity.
Add a new entry under Federated credentials with the following configuration.
- Federated credential scenario: Select **Kubernetes accessing Azure resources**.
- [Cluster issuer URL](https://learn.microsoft.com/en-us/azure/aks/use-oidc-issuer#get-the-oidc-issuer-url): The OIDC issuer URL that your cluster is integrated with. For example: `https://{region}.oic.prod-aks.azure.com/{tenant_id}/{uuid}`.
- Namespace: Namespace of your Grafana deployment. For example: `grafana`.
- Service account name: Service account name of your Grafana deployment. For example: `grafana`.
- Subject identifier: The expected identity (subject claim) from the OIDC token, which Azure uses to validate and authorize token issuance to the requesting workload. For example: `system:serviceaccount:grafana:grafana`.
- Name: A unique descriptive name for the credential.
- Description: Grafana OAuth.
- Audience: The audience value that must appear in the external token. For Public cloud, it would be `api://AzureADTokenExchange`. See mentioned documentation for the full list of available audiences.
1. You must have set `client_authentication` (env var `GF_AUTH_AZUREAD_CLIENT_AUTHENTICATION`) under `[auth.azuread]` to `workload_identity` in the Grafana server configuration for this to work.
1. You may optionally set `workload_identity_token_file` (env var `GF_AUTH_AZUREAD_WORKLOAD_IDENTITY_TOKEN_FILE`) under `[auth.azuread]` to `/var/run/secrets/azure/tokens/azure-identity-token` in the Grafana server configuration for this to work. (Optional, defaults to `/var/run/secrets/azure/tokens/azure-identity-token`)
1. You must have set `client_id` (env var `GF_AUTH_AZUREAD_CLIENT_ID`) under `[auth.azuread]` in the Grafana server configuration for this to work. This must match the Entra ID/Entra ID App Registration Application (client) ID.
1. You must have set `token_url` (env var `GF_AUTH_AZUREAD_TOKEN_URL`) under `[auth.azuread]` to `https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token` in the Grafana server configuration for this to work.
1. You must have set `auth_url` (env var `GF_AUTH_AZUREAD_AUTH_URL`) under `[auth.azuread]` to `https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/authorize` in the Grafana server configuration for this to work.
1. You must have set `federated_credential_audience` (env var `GF_AUTH_AZUREAD_FEDERATED_CREDENTIAL_AUDIENCE`) under `[auth.azuread]` to `api://AzureADTokenExchange` in the Grafana server configuration for this to work.
{{< admonition type="note" >}}
Managed identities as federated credentials are only applicable to workloads hosted in Azure.
You can only add user-assigned managed identities as federated credentials on Entra ID applications.
{{< /admonition >}}
1. Define the required application roles for Grafana [using the Azure Portal](#configure-application-roles-for-grafana-in-the-azure-portal) or [using the manifest file](#configure-application-roles-for-grafana-in-the-manifest-file).
1. Go to **Microsoft Entra ID** and then to **Enterprise Applications**, under **Manage**.
1. Search for your application and click it.
1. Click **Users and Groups**.
1. Click **Add user/group** to add a user or group to the Grafana roles.
{{< admonition type="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 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 >}}
### Configure application roles for Grafana in the Azure Portal
This section describes setting up basic application roles for Grafana within the Azure Portal. For more information, see [Add app roles to your application and receive them in the token](https://learn.microsoft.com/en-us/entra/identity-platform/howto-add-app-roles-in-apps).
1. Go to **App Registrations**, search for your application, and click it.
1. Click **App roles** and then **Create app role**.
1. Define a role corresponding to each Grafana role: Viewer, Editor, and Admin.
1. Choose a **Display name** for the role. For example, "Grafana Editor".
1. Set the **Allowed member types** to **Users/Groups**.
1. Ensure that the **Value** field matches the Grafana role name. For example, "Editor".
1. Choose a **Description** for the role. For example, "Grafana Editor Users".
1. Click **Apply**.
### Configure application roles for Grafana in the manifest file
If you prefer to configure the application roles for Grafana in the manifest file, complete the following steps:
1. Go to **App Registrations**, search for your application, and click it.
1. Click **Manifest**.
1. Add a Universally Unique Identifier to each role.
{{< admonition type="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 >}}
1. Replace each "SOME_UNIQUE_ID" with the generated ID in the manifest file:
```json
"appRoles": [
{
"allowedMemberTypes": [
"User"
],
"description": "Grafana org admin Users",
"displayName": "Grafana Org Admin",
"id": "SOME_UNIQUE_ID",
"isEnabled": true,
"lang": null,
"origin": "Application",
"value": "Admin"
},
{
"allowedMemberTypes": [
"User"
],
"description": "Grafana read only Users",
"displayName": "Grafana Viewer",
"id": "SOME_UNIQUE_ID",
"isEnabled": true,
"lang": null,
"origin": "Application",
"value": "Viewer"
},
{
"allowedMemberTypes": [
"User"
],
"description": "Grafana Editor Users",
"displayName": "Grafana Editor",
"id": "SOME_UNIQUE_ID",
"isEnabled": true,
"lang": null,
"origin": "Application",
"value": "Editor"
}
],
```
1. Click **Save**.
### Assign server administrator privileges
If the application role received by Grafana is `GrafanaAdmin`, Grafana grants the user server administrator privileges.
This is useful if you want to grant server administrator privileges to a subset of users.
Grafana also assigns the user the `Admin` role of the default organization.
The setting `allow_assign_grafana_admin` under `[auth.azuread]` must be set to `true` for this to work.
If the setting is set to `false`, the user is assigned the role of `Admin` of the default organization, but not server administrator privileges.
```json
{
"allowedMemberTypes": ["User"],
"description": "Grafana server admin Users",
"displayName": "Grafana Server Admin",
"id": "SOME_UNIQUE_ID",
"isEnabled": true,
"lang": null,
"origin": "Application",
"value": "GrafanaAdmin"
}
```
## Before you begin
Ensure that you have followed the steps in [Create the Microsoft Entra ID application](#create-the-microsoft-entra-id-application) before you begin.
## Configure Entra ID authentication client using the Grafana UI
As a Grafana Admin, you can configure your Entra ID OAuth client from within Grafana using the Grafana UI. To do this, navigate to the **Administration > Authentication > Entra ID** page and fill in the form. If you have a current configuration in the Grafana configuration file, the form will be pre-populated with those values. Otherwise the form will contain default values.
After you have filled in the form, click **Save** to save the configuration. If the save was successful, Grafana will apply the new configurations.
If you need to reset changes you made in the UI back to the default values, click **Reset**. After you have reset the changes, Grafana will apply the configuration from the Grafana configuration file (if there is any configuration) or the default values.
{{< admonition type="note" >}}
If you run Grafana in high availability mode, configuration changes may not get applied to all Grafana instances immediately. You may need to wait a few minutes for the configuration to propagate to all Grafana instances.
{{< /admonition >}}
## Configure Entra ID authentication client using the Terraform provider
```terraform
resource "grafana_sso_settings" "azuread_sso_settings" {
provider_name = "azuread"
oauth2_settings {
name = "Entra ID"
auth_url = "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize"
token_url = "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token"
client_authentication = "CLIENT_AUTHENTICATION_OPTION"
client_id = "APPLICATION_ID"
client_secret = "CLIENT_SECRET"
managed_identity_client_id = "MANAGED_IDENTITY_CLIENT_ID"
federated_credential_audience = "FEDERATED_CREDENTIAL_AUDIENCE"
allow_sign_up = true
auto_login = false
scopes = "openid email profile"
allowed_organizations = "TENANT_ID"
role_attribute_strict = false
allow_assign_grafana_admin = false
skip_org_role_sync = false
use_pkce = true
custom = {
domain_hint = "contoso.com"
force_use_graph_api = "true"
}
}
}
```
Refer to [Terraform Registry](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/sso_settings) for a complete reference on using the `grafana_sso_settings` resource.
## Configure Entra ID authentication client using the Grafana configuration file
Ensure that you have access to the [Grafana configuration file](../../../configure-grafana/#configuration-file-location).
### Enable Entra ID OAuth in Grafana
Add the following to the [Grafana configuration file](../../../configure-grafana/#configuration-file-location):
```
[auth.azuread]
name = Entra ID
enabled = true
allow_sign_up = true
auto_login = false
client_authentication = CLIENT_AUTHENTICATION_OPTION
client_id = APPLICATION_ID
client_secret = CLIENT_SECRET
managed_identity_client_id = MANAGED_IDENTITY_CLIENT_ID
federated_credential_audience = FEDERATED_CREDENTIAL_AUDIENCE
scopes = openid email profile
auth_url = https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize
token_url = https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token
allowed_domains =
allowed_groups =
allowed_organizations = TENANT_ID
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_authentication`, `client_id`, `client_secret`, `managed_identity_client_id`, and `federated_credential_audience`:
```
GF_AUTH_AZUREAD_CLIENT_AUTHENTICATION
GF_AUTH_AZUREAD_CLIENT_ID
GF_AUTH_AZUREAD_CLIENT_SECRET
GF_AUTH_AZUREAD_MANAGED_IDENTITY_CLIENT_ID
GF_AUTH_AZUREAD_FEDERATED_CREDENTIAL_AUDIENCE
```
{{< admonition type="note" >}}
Verify that the Grafana [root_url](../../../configure-grafana/#root_url) is set in your Azure Application Redirect URLs.
{{< /admonition >}}
### Configure refresh token
When a user logs in using an OAuth provider, Grafana verifies that the access token has not expired. When an access token expires, Grafana uses the provided refresh token (if any exists) to obtain a new access token.
Grafana uses a refresh token to obtain a new access token without requiring the user to log in again. If a refresh token doesn't exist, Grafana logs the user out of the system after the access token has expired.
Refresh token fetching and access token expiration check is enabled by default for the Entra ID 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 >}}
### 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**.
Make sure to include the tenant IDs of all the federated Users' root directory if your Entra ID contains external identities.
For example, if you want to only give access to members of the tenant `example` with an ID of `8bab1c86-8fba-33e5-2089-1d1c80ec267d`, then set the following:
```
allowed_organizations = 8bab1c86-8fba-33e5-2089-1d1c80ec267d
```
### Configure allowed groups
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.
1. To find object IDs for a specific group on the Azure portal, go to **Microsoft Entra ID > Manage > Groups**.
You can find the Object Id of a group by clicking on the group and then clicking on **Properties**. The object ID is listed under **Object ID**. If you want to only give access to members of the group `example` with an Object Id of `8bab1c86-8fba-33e5-2089-1d1c80ec267d`, then set the following:
```
allowed_groups = 8bab1c86-8fba-33e5-2089-1d1c80ec267d
```
1. You must enable adding the [group attribute](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims#configure-groups-optional-claims) to the tokens in your Entra ID App registration either [from the Azure Portal](#configure-group-membership-claims-on-the-azure-portal) or [from the manifest file](#configure-group-membership-claim-in-the-manifest-file).
#### Configure group membership claims on the Azure Portal
To ensure that the `groups` claim is included in the token, add the `groups` claim to the token configuration either through the Azure Portal UI or by editing the manifest file.
To configure group membership claims from the Azure Portal UI, complete the following steps:
1. Navigate to the **App Registrations** page and select your application.
1. Under **Manage** in the side menu, select **Token configuration**.
1. Click **Add groups claim** and select the relevant option for your use case (for example, **Security groups** and **Groups assigned to the application**).
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" >}}
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 >}}
#### Configure group membership claim in the manifest file
1. Go to **App Registrations**, search for your application, and click it.
1. Click **Manifest**.
1. Add the following to the root of the manifest file:
```
"groupMembershipClaims": "ApplicationGroup, SecurityGroup"
```
### Configure allowed domains
The `allowed_domains` option limits access to users who belong to specific domains. Separate domains with space or comma. For example,
```
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
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.
```
auto_login = true
```
### Team Sync
{{< admonition type="note" >}}
Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
With Team Sync you can map your Entra ID groups to teams in Grafana so that your users will automatically be added to
the correct teams.
You can reference Entra ID groups by group object ID, like `8bab1c86-8fba-33e5-2089-1d1c80ec267d`.
To learn more, refer to the [Team Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-team-sync) documentation.
## Common troubleshooting
Here are some common issues and particulars you can run into when
configuring Entra ID authentication in Grafana.
### Users with over 200 Group assignments
To ensure that the token size doesn't exceed HTTP header size limits,
Entra ID limits the number of object IDs that it includes in the groups claim.
If a user is member of more groups than the coverage limit (200), then Entra ID does not emit the groups claim in the token and emits a group overage claim instead.
> More information in [Groups overage claim](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#groups-overage-claim)
If Grafana receives a token with a group overage claim instead of a groups claim,
Grafana attempts to retrieve the user's group membership by calling the included endpoint.
The Entra ID `App registration` must include the following API permissions for group overage claim calls to succeed:
| Permissions name | Type | Admin consent required | Status |
| ---------------------- | --------- | ---------------------- | ------- |
| `GroupMember.Read.All` | Delegated | Yes | Granted |
| `User.Read` | Delegated | No | Granted |
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" >}}
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 >}}
#### Configure the required Graph API permissions
1. Navigate to **Microsoft Entra ID > Manage > App registrations** and select your application.
1. Select **API permissions** and then click on **Add a permission**.
1. Select **Microsoft Graph** from the list of APIs.
1. Select **Delegated permissions**.
1. Under the **GroupMember** section, select **GroupMember.Read.All**.
1. Click **Add permissions**.
1. Select **Microsoft Graph** from the list of APIs.
1. Select **Delegated permissions**.
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" >}}
Admin consent may be required for this permission.
{{< /admonition >}}
### Force fetching groups from Microsoft Graph API
To force fetching groups from Microsoft Graph API instead of the `id_token`, you can use the `force_use_graph_api` configuration option.
```ini
[auth.azuread]
force_use_graph_api = true
```
### Map roles
By default, Entra ID authentication will map users to organization roles based on the most privileged application role assigned to the user in Entra ID.
If no application role is found, the user is assigned the role specified by
[the `auto_assign_org_role` option](../../../configure-grafana/#auto_assign_org_role).
You can disable this default role assignment by setting `role_attribute_strict = true`. This setting denies user access if no role or an invalid role is returned and the `org_mapping` expression evaluates to an empty mapping.
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
their organization membership will be reset to the default organization.
#### Org roles mapping example
The Entra ID integration uses the external users' groups in the `org_mapping` configuration to map organizations and roles based on their Entra ID group membership.
In this example, the user has been granted the role of a `Viewer` in the `org_foo` organization, and the role of an `Editor` in the `org_bar` and `org_baz` orgs.
The external user is part of the following Entra ID groups: `032cb8e0-240f-4347-9120-6f33013e817a` and `bce1c492-0679-4989-941b-8de5e6789cb9`.
Config:
```ini
org_mapping = ["032cb8e0-240f-4347-9120-6f33013e817a:org_foo:Viewer", "bce1c492-0679-4989-941b-8de5e6789cb9:org_bar:Editor", "*:org_baz:Editor"]
```
## Skip organization role sync
If Entra ID authentication is not intended to sync user roles and organization membership and prevent the sync of org roles from Entra ID, 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](../../../configure-grafana/#authazuread) for more details.
```ini
[auth.azuread]
# ..
# prevents the sync of org roles from Entra ID
skip_org_role_sync = true
```
## Configuration options
The following table outlines the various Entra ID 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).
| Setting | Required | Supported on Cloud | Description | Default |
| ------------------------------- | -------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `enabled` | No | Yes | Enables Entra ID authentication. | `false` |
| `name` | No | Yes | Name that refers to the Entra ID authentication from the Grafana user interface. | `OAuth` |
| `icon` | No | Yes | Icon used for the Entra ID authentication in the Grafana user interface. | `signin` |
| `client_authentication` | Yes | Yes | Defines the client authentication method used to authenticate to the token endpoint. Supported values: `none`, `client_secret_post`, `managed_identity`, or `workload_identity`. | |
| `workload_identity_token_file` | No | Yes | The path to the token file used to authenticate to the OAuth2 provider. This is only required when `client_authentication` is set to `workload_identity`. The token file contains the service account token projected by Kubernetes. | `/var/run/secrets/azure/tokens/azure-identity-token` |
| `federated_credential_audience` | No | Yes | The audience of the federated identity credential of your OAuth2 app. Required when `client_authentication` is set to `managed_identity` or `workload_identity`. For public cloud, this is typically `api://AzureADTokenExchange`. | `api://AzureADTokenExchange` |
| `client_id` | Yes | Yes | Client ID of the App (`Application (client) ID` on the **App registration** dashboard). | |
| `client_secret` | Yes | Yes | Client secret of the App. | |
| `auth_url` | Yes | Yes | Authorization endpoint of the Entra ID OAuth2 provider. | |
| `token_url` | Yes | Yes | Endpoint used to obtain the OAuth2 access token. | |
| `auth_style` | No | Yes | Name of the [OAuth2 AuthStyle](https://pkg.go.dev/golang.org/x/oauth2#AuthStyle) to be used when ID token is requested from OAuth2 provider. It determines how `client_id` and `client_secret` are sent to Oauth2 provider. Available values are `AutoDetect`, `InParams` and `InHeader`. | `AutoDetect` |
| `scopes` | No | Yes | List of comma- or space-separated OAuth2 scopes. | `openid email profile` |
| `allow_sign_up` | No | Yes | Controls Grafana user creation through the Entra ID login. Only existing Grafana users can log in with Entra ID if set to `false`. | `true` |
| `auto_login` | No | Yes | Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login. | `false` |
| `login_prompt` | No | Yes | Indicates the type of user interaction when the user logs in with Entra ID. Available values are `login`, `consent` and `select_account`. | |
| `role_attribute_strict` | No | Yes | Set to `true` to deny user login if the Grafana org role cannot be extracted using `role_attribute_path` or `org_mapping`. For more information on user role mapping, refer to [Map roles](#map-roles). | `false` |
| `org_attribute_path` | No | No | [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana org to role lookup. Grafana will first evaluate the expression using the OAuth2 ID token. If no value is returned, the expression will be evaluated using the user information obtained from the UserInfo endpoint. The result of the evaluation will be mapped to org roles based on `org_mapping`. For more information on org to role mapping, refer to [Org roles mapping example](#org-roles-mapping-example). | |
| `org_mapping` | No | No | List of comma- or space-separated `<ExternalOrgName>:<OrgIdOrName>:<Role>` mappings. Value can be `*` meaning "All users". Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. For more information on external organization to role mapping, refer to [Org roles mapping example](#org-roles-mapping-example). | |
| `allow_assign_grafana_admin` | No | No | Set to `true` to automatically sync the Grafana server administrator role. When enabled, if the Entra ID user's App role is `GrafanaAdmin`, Grafana grants the user server administrator privileges and the organization administrator role. If disabled, the user will only receive the organization administrator role. For more details on user role mapping, refer to [Map roles](#map-roles). | `false` |
| `skip_org_role_sync` | No | Yes | Set to `true` to stop automatically syncing user roles. This will allow you to set organization roles for your users from within Grafana manually. | `false` |
| `allowed_groups` | No | Yes | List of comma- or space-separated groups. The user should be a member of at least one group to log in. If you configure `allowed_groups`, you must also configure Entra ID to include the `groups` claim following [Configure group membership claims on the Azure Portal](#configure-group-membership-claims-on-the-azure-portal). | |
| `allowed_organizations` | No | Yes | List of comma- or space-separated Azure tenant identifiers. The user should be a member of at least one tenant to log in. | |
| `allowed_domains` | No | Yes | List of comma- or space-separated domains. The user should belong to at least one domain to log in. | |
| `domain_hint` | No | Yes | The realm of the user in a federated directory. This skips the email-based discovery process that the user goes through on the Entra ID sign-in page, for a slightly more streamlined user experience. More info [here](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc#send-the-sign-in-request). | |
| `tls_skip_verify_insecure` | No | No | If set to `true`, the client accepts any certificate presented by the server and any host name in that certificate. _You should only use this for testing_, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks. | `false` |
| `tls_client_cert` | No | No | The path to the certificate. | |
| `tls_client_key` | No | No | The path to the key. | |
| `tls_client_ca` | No | No | The path to the trusted certificate authority list. | |
| `use_pkce` | No | Yes | Set to `true` to use [Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636). Grafana uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier. | `true` |
| `use_refresh_token` | No | Yes | Enables the use of refresh tokens and checks for access token expiration. When enabled, Grafana automatically adds the `offline_access` scope to the list of scopes. | `true` |
| `force_use_graph_api` | No | Yes | Set to `true` to always fetch groups from the Microsoft Graph API instead of the `id_token`. If a user belongs to more than 200 groups, the Microsoft Graph API will be used to retrieve the groups regardless of this setting. | `false` |
| `signout_redirect_url` | No | Yes | URL to redirect to after the user logs out. | |
docs/sources/setup-grafana/configure-access/configure-authentication/generic-oauth/index.md
+606
View File
@@ -0,0 +1,606 @@
---
aliases:
- ../../../auth/generic-oauth/ # /docs/grafana/next/auth/generic-oauth/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/generic-oauth/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/generic-oauth/
- ../../configure-security/configure-authentication/generic-oauth/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/generic-oauth/
description: Configure Generic OAuth authentication
keywords:
- grafana
- configuration
- documentation
- oauth
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Generic OAuth
title: Configure Generic OAuth authentication
weight: 700
---
# Configure Generic OAuth authentication
{{< docs/shared lookup="auth/intro.md" source="grafana" version="<GRAFANA VERSION>" >}}
Grafana provides OAuth2 integrations for the following auth providers:
- [Entra ID OAuth](../azuread/)
- [GitHub OAuth](../github/)
- [GitLab OAuth](../gitlab/)
- [Google OAuth](../google/)
- [Grafana Com OAuth](../grafana-cloud/)
- [Keycloak OAuth](../keycloak/)
- [Okta OAuth](../okta/)
If your OAuth2 provider is not listed, you can use Generic OAuth authentication.
This topic describes how to configure Generic OAuth authentication using different methods and includes [examples of setting up Generic OAuth](#examples-of-setting-up-generic-oauth) with specific OAuth2 providers.
## Before you begin
To follow this guide:
- Ensure you know how to create an OAuth2 application with your OAuth2 provider. Consult the documentation of your OAuth2 provider for more information.
- Ensure your identity provider returns OpenID UserInfo compatible information such as 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" >}}
If Users use the same email address in 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 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 >}}
## Configure generic OAuth authentication client using the Grafana UI
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.
After you have filled in the form, click **Save** to save the configuration. If the save was successful, Grafana will apply the new configurations.
If you need to reset changes you made in the UI back to the default values, click **Reset**. After you have reset the changes, Grafana will apply the configuration from the Grafana configuration file (if there is any configuration) or the default values.
{{< admonition type="note" >}}
If you run Grafana in high availability mode, configuration changes may not get applied to all Grafana instances immediately. You may need to wait a few minutes for the configuration to propagate to all Grafana instances.
{{< /admonition >}}
Refer to [configuration options](#configuration-options) for more information.
## Configure generic OAuth authentication client using the Terraform provider
```terraform
resource "grafana_sso_settings" "generic_sso_settings" {
provider_name = "generic_oauth"
oauth2_settings {
name = "Auth0"
auth_url = "https://<domain>/authorize"
token_url = "https://<domain>/oauth/token"
api_url = "https://<domain>/userinfo"
client_id = "<client id>"
client_secret = "<client secret>"
allow_sign_up = true
auto_login = false
scopes = "openid profile email offline_access"
use_pkce = true
use_refresh_token = true
}
}
```
Refer to [Terraform Registry](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/sso_settings) for a complete reference on using the `grafana_sso_settings` resource.
## Configure generic OAuth authentication client using the Grafana configuration file
Ensure that you have access to the [Grafana configuration file](../../../configure-grafana/#configuration-file-location).
### Steps
To integrate your OAuth2 provider with Grafana using our Generic OAuth authentication, follow these steps:
1. Create an OAuth2 application in your chosen OAuth2 provider.
1. Set the callback URL for your OAuth2 app to `http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/generic_oauth`.
Ensure that the callback URL is the complete HTTP address that you use to access Grafana via your browser, but with the appended path of `/login/generic_oauth`.
For the callback URL to be correct, it might be necessary to set the `root_url` option in the `[server]`section of the Grafana configuration file. For example, if you are serving Grafana behind a proxy.
1. Refer to the following table to update field values located in the `[auth.generic_oauth]` section of the Grafana configuration file:
| Field | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`, `client_secret` | These values must match the client ID and client secret from your OAuth2 app. |
| `auth_url` | The authorization endpoint of your OAuth2 provider. |
| `api_url` | The user information endpoint of your OAuth2 provider. Information returned by this endpoint must be compatible with [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo). |
| `enabled` | Enables Generic OAuth authentication. Set this value to `true`. |
Review the list of other Generic OAuth [configuration options](#configuration-options) and complete them, as necessary.
1. Optional: [Configure a refresh token](#configure-a-refresh-token):
a. Extend the `scopes` field of `[auth.generic_oauth]` section in Grafana configuration file with refresh token scope used by your OAuth2 provider.
b. Set `use_refresh_token` to `true` in `[auth.generic_oauth]` section in Grafana configuration file.
c. Enable the refresh token on the provider if required.
1. [Configure role mapping](#configure-role-mapping).
1. Optional: [Configure team synchronization](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-team-sync/).
1. Restart Grafana.
You should now see a Generic OAuth login button on the login page and be able to log in or sign up with your OAuth2 provider.
### Configure login
Grafana can resolve a user's login from the OAuth2 ID token, user information retrieved from the OAuth2 UserInfo endpoint, or the OAuth2 access token.
Grafana looks at these sources in the order listed until it finds a login.
If no login is found, then the user's login is set to user's email address.
{{< admonition type="important" >}}
Email is required for successful sign-up and login with Generic OAuth. Even if you map `login` from another claim (for example `sub`), Grafana still requires the user to have an email. Ensure your provider returns an email claim or configure `email_attribute_path` so Grafana can resolve it. Including the `email` scope is strongly recommended (for OIDC providers use `openid profile email`).
{{< /admonition >}}
Refer to the following table for information on what to configure based on how your Oauth2 provider returns a user's login:
| Source of login | Required configuration |
| ------------------------------------------------------------------------------- | ------------------------------------------------ |
| `login` or `username` field of the OAuth2 ID token. | N/A |
| Another field of the OAuth2 ID token. | Set `login_attribute_path` configuration option. |
| `login` or `username` field of the user information from the UserInfo endpoint. | N/A |
| Another field of the user information from the UserInfo endpoint. | Set `login_attribute_path` configuration option. |
| `login` or `username` field of the OAuth2 access token. | N/A |
| Another field of the OAuth2 access token. | Set `login_attribute_path` configuration option. |
#### Use the `sub` claim for login
Most of the OAuth2 providers expose a stable subject identifier in the `sub` claim. You can use it to populate the Grafana login by setting `login_attribute_path` to `sub`. Because email is still required, also make sure Grafana can resolve the user's email (for example by including the `email` scope or mapping a custom field via `email_attribute_path`).
Example configuration:
```ini
[auth.generic_oauth]
enabled = true
scopes = openid profile email
login_attribute_path = sub
# If your provider does not return `email` at the top level, map it explicitly
# email_attribute_path = user.email
```
### Configure display name
Grafana can resolve a user's display name from the OAuth2 ID token, user information retrieved from the OAuth2 UserInfo endpoint, or the OAuth2 access token.
Grafana looks at these sources in the order listed until it finds a display name.
If no display name is found, then user's login is displayed instead.
Refer to the following table for information on what you need to configure depending on how your Oauth2 provider returns a user's name:
| Source of display name | Required configuration |
| ---------------------------------------------------------------------------------- | ----------------------------------------------- |
| `name` or `display_name` field of the OAuth2 ID token. | N/A |
| Another field of the OAuth2 ID token. | Set `name_attribute_path` configuration option. |
| `name` or `display_name` field of the user information from the UserInfo endpoint. | N/A |
| Another field of the user information from the UserInfo endpoint. | Set `name_attribute_path` configuration option. |
| `name` or `display_name` field of the OAuth2 access token. | N/A |
| Another field of the OAuth2 access token. | Set `name_attribute_path` configuration option. |
### Configure email address
Grafana can resolve the user's email address from the OAuth2 ID token, the user information retrieved from the OAuth2 UserInfo endpoint, the OAuth2 access token, or the OAuth2 `/emails` endpoint.
Grafana looks at these sources in the order listed until an email address is found.
If no email is found, then the email address of the user is set to an empty string.
Refer to the following table for information on what to configure based on how the Oauth2 provider returns a user's email address:
| Source of email address | Required configuration |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `email` field of the OAuth2 ID token. | N/A |
| `attributes` map of the OAuth2 ID token. | Set `email_attribute_name` configuration option. By default, Grafana searches for email under `email:primary` key. |
| `upn` field of the OAuth2 ID token. | N/A |
| `email` field of the user information from the UserInfo endpoint. | N/A |
| Another field of the user information from the UserInfo endpoint. | Set `email_attribute_path` configuration option. |
| `email` field of the OAuth2 access token. | N/A |
| `attributes` map of the OAuth2 access token. | Set `email_attribute_name` configuration option. By default, Grafana searches for email under `email:primary` key. |
| `upn` field of the OAuth2 access token. | N/A |
| Another field of the OAuth2 access token. | Set `email_attribute_path` configuration option. |
| Email address marked as primary from the `/emails` endpoint of <br /> the OAuth2 provider (obtained by appending `/emails` to the URL <br /> configured with `api_url`) | N/A |
### Configure a refresh token
When a user logs in using an OAuth2 provider, Grafana verifies that the access token has not expired. When an access token expires, Grafana uses the provided refresh token (if any exists) to obtain a new access token.
Grafana uses a refresh token to obtain a new access token without requiring the user to log in again. If a refresh token doesn't exist, Grafana logs the user out of the system after the access token has expired.
To configure Generic OAuth to use a refresh token, set `use_refresh_token` configuration option to `true` and perform one or both of the following steps, if required:
1. Extend the `scopes` field of `[auth.generic_oauth]` section in Grafana configuration file with additional scopes.
1. Enable the refresh token on the provider.
{{< 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 >}}
### Configure role mapping
Unless `skip_org_role_sync` option is enabled, the user's role will be set to the role retrieved from the auth provider upon user login.
The user's role is retrieved using a [JMESPath](http://jmespath.org/examples.html) expression from the `role_attribute_path` configuration option.
Grafana will first evaluate the expression using the OAuth2 ID token. If no role is found, the expression will be evaluated using the user information obtained from the UserInfo endpoint. If still no role is found, the expression will be evaluated using the OAuth2 access token.
To map the server administrator role, use the `allow_assign_grafana_admin` configuration option.
Refer to [configuration options](#configuration-options) for more information.
If no valid role is found, the user is assigned the role specified by [the `auto_assign_org_role` option](../../../configure-grafana/#auto_assign_org_role).
You can disable this default role assignment by setting `role_attribute_strict = true`. This setting denies user access if no role or an invalid role is returned after evaluating the `role_attribute_path` and the `org_mapping` expressions.
You can use the `org_attribute_path` and `org_mapping` configuration options to assign the user to organizations and specify their role. For more information, refer to [Org roles mapping example](#org-roles-mapping-example). If both org role mapping (`org_mapping`) and the regular role mapping (`role_attribute_path`) are specified, then the user will get the highest of the two mapped roles.
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" >}}
When using `org_attribute_path`, the value returned by the JMESPath expression must be an array, not a string.
{{< /admonition >}}
#### Role mapping examples
This section includes examples of JMESPath expressions used for role mapping.
##### Map user organization role
In this example, the user has been granted the role of an `Editor`. The role assigned is based on the value of the property `role`, which must be a valid Grafana role such as `Admin`, `Editor`, `Viewer` or `None`.
Payload:
```json
{
...
"role": "Editor",
...
}
```
Config:
```bash
role_attribute_path = role
```
In the following more complex example, the user has been granted the `Admin` role. This is because they are a member of the `admin` group of their OAuth2 provider.
If the user was a member of the `editor` group, they would be granted the `Editor` role, otherwise `Viewer`.
Payload:
```json
{
...
"groups": [
"engineer",
"admin",
],
...
}
```
Config:
```bash
role_attribute_path = contains(groups[*], 'admin') && 'Admin' || contains(groups[*], 'editor') && 'Editor' || 'Viewer'
```
##### Map server administrator role
In the following example, the user is granted the Grafana server administrator role.
Payload:
```json
{
...
"roles": [
"admin",
],
...
}
```
Config:
```ini
role_attribute_path = contains(roles[*], 'admin') && 'GrafanaAdmin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'
allow_assign_grafana_admin = true
```
##### 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.
Config:
```ini
role_attribute_path = "'Viewer'"
skip_org_role_sync = false
```
#### Org roles mapping example
In this example, the user has been granted the role of a `Viewer` in the `org_foo` org, and the role of an `Editor` in the `org_bar` and `org_baz` orgs.
If the user was a member of the `admin` group, they would be granted the Grafana server administrator role.
Payload:
```json
{
"roles": ["org_foo", "org_bar", "another_org"]
}
```
Config:
```ini
role_attribute_path = contains(roles[*], 'admin') && 'GrafanaAdmin' || 'None'
allow_assign_grafana_admin = true
org_attribute_path = roles
org_mapping = org_foo:org_foo:Viewer org_bar:org_bar:Editor *:org_baz:Editor
```
## Configure team synchronization
{{< admonition type="note" >}}
Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
By using Team Sync, you can link your OAuth2 groups to teams within Grafana. This will automatically assign users to the appropriate teams.
Teams for each user are synchronized when the user logs in.
Generic OAuth groups can be referenced by group ID, such as `8bab1c86-8fba-33e5-2089-1d1c80ec267d` or `myteam`.
Group information can be extracted from the OAuth2 ID token, user information from the UserInfo endpoint, or the OAuth2 access token.
For information on configuring OAuth2 groups with Grafana using the `groups_attribute_path` configuration option, refer to [configuration options](#configuration-options).
To learn more about Team Sync, refer to [Configure team sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-team-sync/).
### Team synchronization example
Configuration:
```bash
groups_attribute_path = groups
```
Payload:
```json
{
...
"groups": [
"engineers",
"analysts",
],
...
}
```
## Configuration options
The following table outlines the various Generic 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).
{{< admonition type="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"`
{{< /admonition >}}
| Setting | Required | Supported on Cloud | Description | Default |
| ---------------------------- | -------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `enabled` | No | Yes | Enables Generic OAuth authentication. | `false` |
| `name` | No | Yes | Name that refers to the Generic OAuth authentication from the Grafana user interface. | `OAuth` |
| `icon` | No | Yes | Icon used for the Generic OAuth authentication in the Grafana user interface. | `signin` |
| `client_id` | Yes | Yes | Client ID provided by your OAuth2 app. | |
| `client_secret` | Yes | Yes | Client secret provided by your OAuth2 app. | |
| `auth_url` | Yes | Yes | Authorization endpoint of your OAuth2 provider. | |
| `token_url` | Yes | Yes | Endpoint used to obtain the OAuth2 access token. | |
| `api_url` | Yes | Yes | Endpoint used to obtain user information compatible with [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo). | |
| `auth_style` | No | Yes | Name of the [OAuth2 AuthStyle](https://pkg.go.dev/golang.org/x/oauth2#AuthStyle) to be used when ID token is requested from OAuth2 provider. It determines how `client_id` and `client_secret` are sent to Oauth2 provider. Available values are `AutoDetect`, `InParams` and `InHeader`. | `AutoDetect` |
| `scopes` | No | Yes | List of comma- or space-separated OAuth2 scopes. | `user:email` |
| `empty_scopes` | No | Yes | Set to `true` to use an empty scope during authentication. | `false` |
| `allow_sign_up` | No | Yes | Controls Grafana user creation through the Generic OAuth login. Only existing Grafana users can log in with Generic OAuth if set to `false`. | `true` |
| `auto_login` | No | Yes | Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login. | `false` |
| `login_prompt` | No | Yes | Indicates the type of user interaction when the user logs in with the IdP. Available values are `login`, `consent` and `select_account`. | |
| `id_token_attribute_name` | No | Yes | The name of the key used to extract the ID token from the returned OAuth2 token. | `id_token` |
| `login_attribute_path` | No | Yes | [JMESPath](http://jmespath.org/examples.html) expression to use for user login lookup from the user ID token. For more information on how user login is retrieved, refer to [Configure login](#configure-login). | |
| `name_attribute_path` | No | Yes | [JMESPath](http://jmespath.org/examples.html) expression to use for user name lookup from the user ID token. This name will be used as the user's display name. For more information on how user display name is retrieved, refer to [Configure display name](#configure-display-name). | |
| `email_attribute_path` | No | Yes | [JMESPath](http://jmespath.org/examples.html) expression to use for user email lookup from the user information. For more information on how user email is retrieved, refer to [Configure email address](#configure-email-address). | |
| `email_attribute_name` | No | Yes | Name of the key to use for user email lookup within the `attributes` map of OAuth2 ID token. For more information on how user email is retrieved, refer to [Configure email address](#configure-email-address). | `email:primary` |
| `role_attribute_path` | No | Yes | [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana role lookup. Grafana will first evaluate the expression using the OAuth2 ID token. If no role is found, the expression will be evaluated using the user information obtained from the UserInfo endpoint. If still no role is found, the expression will be evaluated using the OAuth2 access token. The result of the evaluation should be a valid Grafana role (`None`, `Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to [Configure role mapping](#configure-role-mapping). | |
| `role_attribute_strict` | No | Yes | Set to `true` to deny user login if the Grafana org role cannot be extracted using `role_attribute_path` or `org_mapping`. For more information on user role mapping, refer to [Configure role mapping](#configure-role-mapping). | `false` |
| `skip_org_role_sync` | No | Yes | Set to `true` to stop automatically syncing user roles. This will allow you to set organization roles for your users from within Grafana manually. | `false` |
| `org_attribute_path` | No | No | [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana org to role lookup. Grafana will first evaluate the expression using the OAuth2 ID token. If no value is returned, the expression will be evaluated using the user information obtained from the UserInfo endpoint. If still no value is returned, the expression will be evaluated using the OAuth2 access token. The result of the evaluation will be mapped to org roles based on `org_mapping`. For more information on org to role mapping, refer to [Org roles mapping example](#org-roles-mapping-example). | |
| `org_mapping` | No | No | List of comma- or space-separated `<ExternalOrgName>:<OrgIdOrName>:<Role>` mappings. Value can be `*` meaning "All users". Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. For more information on external organization to role mapping, refer to [Org roles mapping example](#org-roles-mapping-example). | |
| `allow_assign_grafana_admin` | No | No | Set to `true` to enable automatic sync of the Grafana server administrator role. If this option is set to `true` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user the server administrator privileges and organization administrator role. If this option is set to `false` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user only organization administrator role. For more information on user role mapping, refer to [Configure role mapping](#configure-role-mapping). | `false` |
| `groups_attribute_path` | No | Yes | [JMESPath](http://jmespath.org/examples.html) expression to use for user group lookup. Grafana will first evaluate the expression using the OAuth2 ID token. If no groups are found, the expression will be evaluated using the user information obtained from the UserInfo endpoint. If still no groups are found, the expression will be evaluated using the OAuth2 access token. The result of the evaluation should be a string array of groups. | |
| `allowed_groups` | No | Yes | List of comma- or space-separated groups. The user should be a member of at least one group to log in. If you configure `allowed_groups`, you must also configure `groups_attribute_path`. | |
| `allowed_organizations` | No | Yes | List of comma- or space-separated organizations. The user should be a member of at least one organization to log in. | |
| `allowed_domains` | No | Yes | List of comma- or space-separated domains. The user should belong to at least one domain to log in. | |
| `team_ids` | No | Yes | String list of team IDs. If set, the user must be a member of one of the given teams to log in. If you configure `team_ids`, you must also configure `teams_url` and `team_ids_attribute_path`. | |
| `team_ids_attribute_path` | No | Yes | The [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana team ID lookup within the results returned by the `teams_url` endpoint. | |
| `teams_url` | No | Yes | The URL used to query for team IDs. If not set, the default value is `/teams`. If you configure `teams_url`, you must also configure `team_ids_attribute_path`. | |
| `tls_skip_verify_insecure` | No | No | If set to `true`, the client accepts any certificate presented by the server and any host name in that certificate. _You should only use this for testing_, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks. | `false` |
| `tls_client_cert` | No | No | The path to the certificate. | |
| `tls_client_key` | No | No | The path to the key. | |
| `tls_client_ca` | No | No | The path to the trusted certificate authority list. | |
| `use_pkce` | No | Yes | Set to `true` to use [Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636). Grafana uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier. | `false` |
| `use_refresh_token` | No | Yes | Set to `true` to use refresh token and check access token expiration. | `false` |
| `signout_redirect_url` | No | Yes | URL to redirect to after the user logs out. | |
## Examples of setting up Generic OAuth
This section includes examples of setting up Generic OAuth integration.
### Set up OAuth2 with Descope
To set up Generic OAuth authentication with Descope, follow these steps:
1. Create a Descope Project [here](https://app.descope.com/gettingStarted), and go through the Getting Started Wizard to configure your authentication. You can skip step if you already have Descope project set up.
1. If you wish to use a flow besides `Sign Up or In`, go to the **IdP Applications** menu in the console, and select your IdP application. Then alter the **Flow Hosting URL** query parameter `?flow=sign-up-or-in` to change which flow id you wish to use.
1. Click **Save**.
1. Update the `[auth.generic_oauth]` section of the Grafana configuration file using the values from the **Settings** tab:
{{< admonition type="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 >}}
```bash
[auth.generic_oauth]
enabled = true
allow_sign_up = true
auto_login = false
team_ids =
allowed_organizations =
name = Descope
client_id = <Descope Project ID>
client_secret = <Descope Access Key>
scopes = openid profile email descope.claims descope.custom_claims
auth_url = https://api.descope.com/oauth2/v1/authorize
token_url = https://api.descope.com/oauth2/v1/token
api_url = https://api.descope.com/oauth2/v1/userinfo
use_pkce = true
use_refresh_token = true
```
### Set up OAuth2 with Auth0
{{< admonition type="note" >}}
Support for the Auth0 "audience" feature is not currently available in Grafana. For roles and permissions, the available options are described [here](../../../../administration/roles-and-permissions/).
{{< /admonition >}}
To set up Generic OAuth authentication with Auth0, follow these steps:
1. Create an Auth0 application using the following parameters:
- Name: Grafana
- Type: Regular Web Application
1. Go to the **Settings** tab of the application and set **Allowed Callback URLs** to `https://<grafana domain>/login/generic_oauth`.
1. Click **Save Changes**.
1. Update the `[auth.generic_oauth]` section of the Grafana configuration file using the values from the **Settings** tab:
```bash
[auth.generic_oauth]
enabled = true
allow_sign_up = true
auto_login = false
team_ids =
allowed_organizations =
name = Auth0
client_id = <client id>
client_secret = <client secret>
scopes = openid profile email offline_access
auth_url = https://<domain>/authorize
token_url = https://<domain>/oauth/token
api_url = https://<domain>/userinfo
use_pkce = true
use_refresh_token = true
```
### Set up OAuth2 with Bitbucket
To set up Generic OAuth authentication with Bitbucket, follow these steps:
1. Navigate to **Settings > Workspace setting > OAuth consumers** in BitBucket.
1. Create an application by selecting **Add consumer** and using the following parameters:
- Allowed Callback URLs: `https://<grafana domain>/login/generic_oauth`
1. Click **Save**.
1. Update the `[auth.generic_oauth]` section of the Grafana configuration file using the values from the `Key` and `Secret` from the consumer description:
```bash
[auth.generic_oauth]
name = BitBucket
enabled = true
allow_sign_up = true
auto_login = false
client_id = <client key>
client_secret = <client secret>
scopes = account email
auth_url = https://bitbucket.org/site/oauth2/authorize
token_url = https://bitbucket.org/site/oauth2/access_token
api_url = https://api.bitbucket.org/2.0/user
teams_url = https://api.bitbucket.org/2.0/user/permissions/workspaces
team_ids_attribute_path = values[*].workspace.slug
team_ids =
allowed_organizations =
use_refresh_token = true
```
By default, a refresh token is included in the response for the **Authorization Code Grant**.
### Set up OAuth2 with OneLogin
To set up Generic OAuth authentication with OneLogin, follow these steps:
1. Create a new Custom Connector in OneLogin with the following settings:
- Name: Grafana
- Sign On Method: OpenID Connect
- Redirect URI: `https://<grafana domain>/login/generic_oauth`
- Signing Algorithm: RS256
- Login URL: `https://<grafana domain>/login/generic_oauth`
1. Add an app to the Grafana Connector:
- Display Name: Grafana
1. Update the `[auth.generic_oauth]` section of the Grafana configuration file using the client ID and client secret from the **SSO** tab of the app details page:
Your OneLogin Domain will match the URL you use to access OneLogin.
```bash
[auth.generic_oauth]
name = OneLogin
enabled = true
allow_sign_up = true
auto_login = false
client_id = <client id>
client_secret = <client secret>
scopes = openid email name
auth_url = https://<onelogin domain>.onelogin.com/oidc/2/auth
token_url = https://<onelogin domain>.onelogin.com/oidc/2/token
api_url = https://<onelogin domain>.onelogin.com/oidc/2/me
team_ids =
allowed_organizations =
```
### Set up OAuth2 with Dex
To set up Generic OAuth authentication with [Dex IdP](https://dexidp.io/), follow these
steps:
1. Add Grafana as a client in the Dex config YAML file:
```yaml
staticClients:
- id: <client id>
name: Grafana
secret: <client secret>
redirectURIs:
- 'https://<grafana domain>/login/generic_oauth'
```
{{< admonition type="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 >}}
2. Update the `[auth.generic_oauth]` section of the Grafana configuration:
```bash
[auth.generic_oauth]
name = Dex
enabled = true
client_id = <client id>
client_secret = <client secret>
scopes = openid email profile groups offline_access
auth_url = https://<dex base uri>/auth
token_url = https://<dex base uri>/token
api_url = https://<dex base uri>/userinfo
```
`<dex base uri>` corresponds to the `issuer: ` configuration in Dex (e.g. the Dex
domain possibly including a path such as e.g. `/dex`). The `offline_access` scope is
needed when using [refresh tokens](#configure-a-refresh-token).
docs/sources/setup-grafana/configure-access/configure-authentication/github/index.md
+265
View File
@@ -0,0 +1,265 @@
---
aliases:
- ../../../auth/github/ # /docs/grafana/next/auth/github/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/github/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/github/
- ../../configure-security/configure-authentication/github/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/github/
description: Configure GitHub OAuth authentication
keywords:
- grafana
- configuration
- documentation
- oauth
labels:
products:
- cloud
- enterprise
- oss
menuTitle: GitHub OAuth
title: Configure GitHub OAuth authentication
weight: 900
---
# Configure GitHub OAuth authentication
{{< docs/shared lookup="auth/intro.md" source="grafana" version="<GRAFANA VERSION>" >}}
This topic describes how to configure GitHub OAuth authentication.
{{< admonition type="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 >}}
## Before you begin
Ensure you know how to create a GitHub OAuth app. Consult GitHub's documentation on [creating an OAuth app](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) for more information.
### Create a GitHub OAuth App
1. Log in to your GitHub account.
In **Profile > Settings > Developer settings**, select **OAuth Apps**.
1. Click **New OAuth App**.
1. Fill out the fields, using your Grafana homepage URL when appropriate.
In the **Authorization callback URL** field, enter the following: `https://<YOUR-GRAFANA-URL>/login/github` .
1. Note your client ID.
1. Generate, then note, your client secret.
## Configure GitHub authentication client using the Grafana UI
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.
After you have filled in the form, click **Save**. If the save was successful, Grafana will apply the new configurations.
If you need to reset changes you made in the UI back to the default values, click **Reset**. After you have reset the changes, Grafana will apply the configuration from the Grafana configuration file (if there is any configuration) or the default values.
{{< admonition type="note" >}}
If you run Grafana in high availability mode, configuration changes may not get applied to all Grafana instances immediately. You may need to wait a few minutes for the configuration to propagate to all Grafana instances.
{{< /admonition >}}
Refer to [configuration options](#configuration-options) for more information.
## Configure GitHub authentication client using the Terraform provider
```terraform
resource "grafana_sso_settings" "github_sso_settings" {
provider_name = "github"
oauth2_settings {
name = "Github"
client_id = "YOUR_GITHUB_APP_CLIENT_ID"
client_secret = "YOUR_GITHUB_APP_CLIENT_SECRET"
allow_sign_up = true
auto_login = false
scopes = "user:email,read:org"
team_ids = "150,300"
allowed_organizations = "[\"My Organization\", \"Octocats\"]"
allowed_domains = "mycompany.com mycompany.org"
role_attribute_path = "[login=='octocat'][0] && 'GrafanaAdmin' || 'Viewer'"
}
}
```
Go to [Terraform Registry](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/sso_settings) for a complete reference on using the `grafana_sso_settings` resource.
## Configure GitHub authentication client using the Grafana configuration file
Ensure that you have access to the [Grafana configuration file](../../../configure-grafana/#configuration-file-location).
### Configure GitHub authentication
To configure GitHub authentication with Grafana, follow these steps:
1. Create an OAuth application in GitHub.
1. Set the callback URL for your GitHub OAuth app to `http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/github`.
Ensure that the callback URL is the complete HTTP address that you use to access Grafana via your browser, but with the appended path of `/login/github`.
For the callback URL to be correct, it might be necessary to set the `root_url` option in the `[server]`section of the Grafana configuration file. For example, if you are serving Grafana behind a proxy.
1. Refer to the following table to update field values located in the `[auth.github]` section of the Grafana configuration file:
| Field | Description |
| ---------------------------- | ----------------------------------------------------------------------------------- |
| `client_id`, `client_secret` | These values must match the client ID and client secret from your GitHub OAuth app. |
| `enabled` | Enables GitHub authentication. Set this value to `true`. |
Review the list of other GitHub [configuration options](#configuration-options) and complete them, as necessary.
1. [Configure role mapping](#configure-role-mapping).
1. Optional: [Configure team synchronization](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-team-sync/).
1. Restart Grafana.
You should now see a GitHub login button on the login page and be able to log in or sign up with your GitHub accounts.
### Configure role mapping
Unless the `skip_org_role_sync` option is enabled, the user's role will be set to the role retrieved from GitHub upon user login.
The user's role is retrieved using a [JMESPath](http://jmespath.org/examples.html) expression from the `role_attribute_path` configuration option.
To map the server administrator role, use the `allow_assign_grafana_admin` configuration option.
Refer to [configuration options](#configuration-options) for more information.
If no valid role is found, the user is assigned the role specified by [the `auto_assign_org_role` option](../../../configure-grafana/#auto_assign_org_role).
You can disable this default role assignment by setting `role_attribute_strict = true`. This setting denies user access if no role or an invalid role is returned after evaluating the `role_attribute_path` and the `org_mapping` expressions.
You can use the `org_mapping` configuration options to assign the user to organizations and specify their role based on their GitHub team membership. For more information, refer to [Org roles mapping example](#org-roles-mapping-example). If both org role mapping (`org_mapping`) and the regular role mapping (`role_attribute_path`) are specified, then the user will get the highest of the two mapped roles.
To ease configuration of a proper JMESPath expression, go to [JMESPath](http://jmespath.org/) to test and evaluate expressions with custom payloads.
#### Role mapping examples
This section includes examples of JMESPath expressions used for role mapping.
##### Org roles mapping example
The GitHub integration uses the external users' teams in the `org_mapping` configuration to map organizations and roles based on their GitHub team membership.
In this example, the user has been granted the role of a `Viewer` in the `org_foo` organization, and the role of an `Editor` in the `org_bar` and `org_baz` orgs.
The external user is part of the following GitHub teams: `@my-github-organization/my-github-team-1` and `@my-github-organization/my-github-team-2`.
Config:
```ini
org_mapping = @my-github-organization/my-github-team-1:org_foo:Viewer @my-github-organization/my-github-team-2:org_bar:Editor *:org_baz:Editor
```
##### Map roles using GitHub user information
In this example, the user with login `octocat` has been granted the `Admin` role.
All other users are granted the `Viewer` role.
```bash
role_attribute_path = [login=='octocat'][0] && 'Admin' || 'Viewer'
```
##### Map roles using GitHub teams
In this example, the user from GitHub team `my-github-team` has been granted the `Editor` role.
All other users are granted the `Viewer` role.
```bash
role_attribute_path = contains(groups[*], '@my-github-organization/my-github-team') && 'Editor' || 'Viewer'
```
##### Map roles using multiple GitHub teams
In this example, the users from GitHub teams `admins` and `devops` have been granted the `Admin` role,
the users from GitHub teams `engineers` and `managers` have been granted the `Editor` role,
the users from GitHub team `qa` have been granted the `Viewer` role and
all other users are granted the `None` role.
```bash
role_attribute_path = contains(groups[*], '@my-github-organization/admins') && 'Admin' || contains(groups[*], '@my-github-organization/devops') && 'Admin' || contains(groups[*], '@my-github-organization/engineers') && 'Editor' || contains(groups[*], '@my-github-organization/managers') && 'Editor' || contains(groups[*], '@my-github-organization/qa') && 'Viewer' || 'None'
```
##### Map server administrator role
In this example, the user with login `octocat` has been granted the `Admin` organization role as well as the Grafana server admin role.
All other users are granted the `Viewer` role.
```bash
role_attribute_path = [login=='octocat'][0] && 'GrafanaAdmin' || 'Viewer'
```
##### Map one role to all users
In this example, all users will be assigned `Viewer` role regardless of the user information received from the identity provider.
```ini
role_attribute_path = "'Viewer'"
skip_org_role_sync = false
```
### Example of GitHub configuration in Grafana
This section includes an example of GitHub configuration in the Grafana configuration file.
```bash
[auth.github]
enabled = true
client_id = YOUR_GITHUB_APP_CLIENT_ID
client_secret = YOUR_GITHUB_APP_CLIENT_SECRET
scopes = user:email,read:org
auth_url = https://github.com/login/oauth/authorize
token_url = https://github.com/login/oauth/access_token
api_url = https://api.github.com/user
allow_sign_up = true
auto_login = false
team_ids = 150,300
allowed_organizations = ["My Organization", "Octocats"]
allowed_domains = mycompany.com mycompany.org
role_attribute_path = [login=='octocat'][0] && 'GrafanaAdmin' || 'Viewer'
```
## Configure team synchronization
{{< admonition type="note" >}}
Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
By using Team Sync, you can map teams from your GitHub organization to teams within Grafana. This will automatically assign users to the appropriate teams.
Teams for each user are synchronized when the user logs in.
GitHub teams can be referenced in two ways:
- `https://github.com/orgs/<org>/teams/<slug>`
- `@<org>/<slug>`
Examples: `https://github.com/orgs/grafana/teams/developers` or `@grafana/developers`.
To learn more about Team Sync, refer to [Configure team sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-team-sync/).
## Configuration options
The table below describes all GitHub 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).
{{< admonition type="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"`
{{< /admonition >}}
| Setting | Required | Supported on Cloud | Description | Default |
| ---------------------------- | -------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `enabled` | No | Yes | Whether GitHub OAuth authentication is allowed. | `false` |
| `name` | No | Yes | Name used to refer to the GitHub authentication in the Grafana user interface. | `GitHub` |
| `icon` | No | Yes | Icon used for GitHub authentication in the Grafana user interface. | `github` |
| `client_id` | Yes | Yes | Client ID provided by your GitHub OAuth app. | |
| `client_secret` | Yes | Yes | Client secret provided by your GitHub OAuth app. | |
| `auth_url` | Yes | Yes | Authorization endpoint of your GitHub OAuth provider. | `https://github.com/login/oauth/authorize` |
| `token_url` | Yes | Yes | Endpoint used to obtain GitHub OAuth access token. | `https://github.com/login/oauth/access_token` |
| `api_url` | Yes | Yes | Endpoint used to obtain GitHub user information compatible with [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo). | `https://api.github.com/user` |
| `scopes` | No | Yes | List of comma- or space-separated GitHub OAuth scopes. | `user:email,read:org` |
| `allow_sign_up` | No | Yes | Whether to allow new Grafana user creation through GitHub login. If set to `false`, then only existing Grafana users can log in with GitHub OAuth. | `true` |
| `auto_login` | No | Yes | Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login. | `false` |
| `login_prompt` | No | Yes | Indicates the type of user interaction when the user logs in with GitHub. Available values are `login`, `consent` and `select_account`. | |
| `role_attribute_path` | No | Yes | [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana role lookup. Grafana will first evaluate the expression using the user information obtained from the UserInfo endpoint. If no role is found, Grafana creates a JSON data with `groups` key that maps to GitHub teams obtained from GitHub's [`/api/user/teams`](https://docs.github.com/en/rest/teams/teams#list-teams-for-the-authenticated-user) endpoint, and evaluates the expression using this data. The result of the evaluation should be a valid Grafana role (`None`, `Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to [Configure role mapping](#org-roles-mapping-example). | |
| `role_attribute_strict` | No | Yes | Set to `true` to deny user login if the Grafana org role cannot be extracted using `role_attribute_path` or `org_mapping`. For more information on user role mapping, refer to [Configure role mapping](#org-roles-mapping-example). | `false` |
| `org_mapping` | No | No | List of comma- or space-separated `<ExternalGitHubTeamName>:<OrgIdOrName>:<Role>` mappings. Value can be `*` meaning "All users". Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. For more information on external organization to role mapping, refer to [Org roles mapping example](#org-roles-mapping-example). | |
| `skip_org_role_sync` | No | Yes | Set to `true` to stop automatically syncing user roles. | `false` |
| `allow_assign_grafana_admin` | No | No | Set to `true` to enable automatic sync of the Grafana server administrator role. If this option is set to `true` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user the server administrator privileges and organization administrator role. If this option is set to `false` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user only organization administrator role. For more information on user role mapping, refer to [Configure role mapping](#configure-role-mapping). | `false` |
| `allowed_organizations` | No | Yes | List of comma- or space-separated organizations. User must be a member of at least one organization to log in. | |
| `allowed_domains` | No | Yes | List of comma- or space-separated domains. User must belong to at least one domain to log in. | |
| `team_ids` | No | Yes | Integer list of team IDs. If set, user has to be a member of one of the given teams to log in. | |
| `tls_skip_verify_insecure` | No | No | If set to `true`, the client accepts any certificate presented by the server and any host name in that certificate. _You should only use this for testing_, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks. | `false` |
| `tls_client_cert` | No | No | The path to the certificate. | |
| `tls_client_key` | No | No | The path to the key. | |
| `tls_client_ca` | No | No | The path to the trusted certificate authority list. | |
| `signout_redirect_url` | No | Yes | URL to redirect to after the user logs out. | |
docs/sources/setup-grafana/configure-access/configure-authentication/gitlab/index.md
+288
View File
@@ -0,0 +1,288 @@
---
aliases:
- ../../../auth/gitlab/ # /docs/grafana/next/auth/gitlab/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/gitlab/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/gitlab/
- ../../configure-security/configure-authentication/gitlab/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/gitlab/
description: Grafana GitLab OAuth Guide
keywords:
- grafana
- configuration
- documentation
- oauth
labels:
products:
- cloud
- enterprise
- oss
menuTitle: GitLab OAuth
title: Configure GitLab OAuth authentication
weight: 1000
---
# Configure GitLab OAuth authentication
{{< docs/shared lookup="auth/intro.md" source="grafana" version="<GRAFANA VERSION>" >}}
This topic describes how to configure GitLab OAuth authentication.
{{< admonition type="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 >}}
## Before you begin
Ensure you know how to create a GitLab OAuth application. Consult GitLab's documentation on [creating a GitLab OAuth application](https://docs.gitlab.com/ee/integration/oauth_provider.html) for more information.
### Create a GitLab OAuth Application
1. Log in to your GitLab account and go to **Profile > Preferences > Applications**.
1. Click **Add new application**.
1. Fill out the fields.
- In the **Redirect URI** field, enter the following: `https://<YOUR-GRAFANA-URL>/login/gitlab` and check `openid`, `email`, `profile` in the **Scopes** list.
- Leave the **Confidential** checkbox checked.
1. Click **Save application**.
1. Note your **Application ID** (this is the `Client Id`) and **Secret** (this is the `Client Secret`).
## Configure GitLab authentication client using the Grafana UI
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" >}}
If you run Grafana in high availability mode, configuration changes may not get applied to all Grafana instances immediately. You may need to wait a few minutes for the configuration to propagate to all Grafana instances.
{{< /admonition >}}
Refer to [configuration options](#configuration-options) for more information.
## Configure GitLab authentication client using the Terraform provider
```terraform
resource "grafana_sso_settings" "gitlab_sso_settings" {
provider_name = "gitlab"
oauth2_settings {
name = "Gitlab"
client_id = "YOUR_GITLAB_APPLICATION_ID"
client_secret = "YOUR_GITLAB_APPLICATION_SECRET"
allow_sign_up = true
auto_login = false
scopes = "openid email profile"
allowed_domains = "mycompany.com mycompany.org"
role_attribute_path = "contains(groups[*], 'example-group') && 'Editor' || 'Viewer'"
role_attribute_strict = false
allowed_groups = "[\"admins\", \"software engineers\", \"developers/frontend\"]"
use_pkce = true
use_refresh_token = true
}
}
```
Go to [Terraform Registry](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/sso_settings) for a complete reference on using the `grafana_sso_settings` resource.
## Configure GitLab authentication client using the Grafana configuration file
Ensure that you have access to the [Grafana configuration file](../../../configure-grafana/#configuration-file-location).
### Steps
To configure GitLab authentication with Grafana, follow these steps:
1. Create an OAuth application in GitLab.
1. Set the redirect URI to `http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/gitlab`.
Ensure that the Redirect URI is the complete HTTP address that you use to access Grafana via your browser, but with the appended path of `/login/gitlab`.
For the Redirect URI to be correct, it might be necessary to set the `root_url` option in the `[server]`section of the Grafana configuration file. For example, if you are serving Grafana behind a proxy.
1. Set the OAuth2 scopes to `openid`, `email` and `profile`.
1. Refer to the following table to update field values located in the `[auth.gitlab]` section of the Grafana configuration file:
| Field | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------- |
| `client_id`, `client_secret` | These values must match the `Application ID` and `Secret` from your GitLab OAuth application. |
| `enabled` | Enables GitLab authentication. Set this value to `true`. |
Review the list of other GitLab [configuration options](#configuration-options) and complete them, as necessary.
1. Optional: [Configure a refresh token](#configure-a-refresh-token):
a. Set `use_refresh_token` to `true` in `[auth.gitlab]` section in Grafana configuration file.
1. [Configure role mapping](#configure-role-mapping).
1. Optional: [Configure team synchronization](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-team-sync/).
1. Restart Grafana.
You should now see a GitLab login button on the login page and be able to log in or sign up with your GitLab accounts.
### Configure a refresh token
When a user logs in using an OAuth provider, Grafana verifies that the access token has not expired. When an access token expires, Grafana uses the provided refresh token (if any exists) to obtain a new access token.
Grafana uses a refresh token to obtain a new access token without requiring the user to log in again. If a refresh token doesn't exist, Grafana logs the user out of the system after the access token has expired.
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. Use the `use_refresh_token` configuration value instead for configuring refresh token fetching and access token expiration check.
{{< /admonition >}}
### Configure allowed groups
To limit access to authenticated users that are members of one or more [GitLab
groups](https://docs.gitlab.com/ce/user/group/index.html), set `allowed_groups`
to a comma or space-separated list of groups.
GitLab's groups are referenced by the group name. For example, `developers`. To reference a subgroup `frontend`, use `developers/frontend`.
Note that in GitLab, the group or subgroup name does not always match its display name, especially if the display name contains spaces or special characters.
Make sure you always use the group or subgroup name as it appears in the URL of the group or subgroup.
### Configure role mapping
Unless `skip_org_role_sync` option is enabled, the user's role will be set to the role retrieved from GitLab upon user login.
The user's role is retrieved using a [JMESPath](http://jmespath.org/examples.html) expression from the `role_attribute_path` configuration option.
To map the server administrator role, use the `allow_assign_grafana_admin` configuration option.
Refer to [configuration options](#configuration-options) for more information.
You can use the `org_mapping` configuration option to assign the user to multiple organizations and specify their role based on their GitLab 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.
If no valid role is found, the user is assigned the role specified by [the `auto_assign_org_role` option](../../../configure-grafana/#auto_assign_org_role).
You can disable this default role assignment by setting `role_attribute_strict = true`. This setting denies user access if no role or an invalid role is returned 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.
### Role mapping examples
This section includes examples of JMESPath expressions used for role mapping.
##### Org roles mapping example
The GitLab integration uses the external users' groups in the `org_mapping` configuration to map organizations and roles based on their GitLab group membership.
In this example, the user has been granted the role of a `Viewer` in the `org_foo` organization, and the role of an `Editor` in the `org_bar` and `org_baz` orgs.
The external user is part of the following GitLab groups: `groupd-1` and `group-2`.
Config:
```ini
org_mapping = group-1:org_foo:Viewer groupd-1:org_bar:Editor *:org_baz:Editor
```
#### Map roles using user information from OAuth token
In this example, the user with email `admin@company.com` has been granted the `Admin` role.
All other users are granted the `Viewer` role.
```ini
role_attribute_path = email=='admin@company.com' && 'Admin' || 'Viewer'
```
#### Map roles using groups
In this example, the user from GitLab group 'example-group' have been granted the `Editor` role.
All other users are granted the `Viewer` role.
```ini
role_attribute_path = contains(groups[*], 'example-group') && 'Editor' || 'Viewer'
```
#### Map server administrator role
In this example, the user with email `admin@company.com` has been granted the `Admin` organization role as well as the Grafana server admin role.
All other users are granted the `Viewer` role.
```bash
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.
```ini
role_attribute_path = "'Viewer'"
skip_org_role_sync = false
```
### Example of GitLab configuration in Grafana
This section includes an example of GitLab configuration in the Grafana configuration file.
```bash
[auth.gitlab]
enabled = true
allow_sign_up = true
auto_login = false
client_id = YOUR_GITLAB_APPLICATION_ID
client_secret = YOUR_GITLAB_APPLICATION_SECRET
scopes = openid email profile
auth_url = https://gitlab.com/oauth/authorize
token_url = https://gitlab.com/oauth/token
api_url = https://gitlab.com/api/v4
role_attribute_path = contains(groups[*], 'example-group') && 'Editor' || 'Viewer'
role_attribute_strict = false
allow_assign_grafana_admin = false
allowed_groups = ["admins", "software engineers", "developers/frontend"]
allowed_domains = mycompany.com mycompany.org
tls_skip_verify_insecure = false
use_pkce = true
use_refresh_token = true
```
## Configure team synchronization
{{< admonition type="note" >}}
Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
By using Team Sync, you can map GitLab groups to teams within Grafana. This will automatically assign users to the appropriate teams.
Teams for each user are synchronized when the user logs in.
GitLab groups are referenced by the group name. For example, `developers`. To reference a subgroup `frontend`, use `developers/frontend`.
Note that in GitLab, the group or subgroup name does not always match its display name, especially if the display name contains spaces or special characters.
Make sure you always use the group or subgroup name as it appears in the URL of the group or subgroup.
To learn more about Team Sync, refer to [Configure team sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-team-sync/).
## Configuration options
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).
{{< admonition type="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"`
{{< /admonition >}}
| Setting | Required | Supported on Cloud | Description | Default |
| ---------------------------- | -------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `enabled` | Yes | Yes | Whether GitLab OAuth authentication is allowed. | `false` |
| `client_id` | Yes | Yes | Client ID provided by your GitLab OAuth app. | |
| `client_secret` | Yes | Yes | Client secret provided by your GitLab OAuth app. | |
| `auth_url` | Yes | Yes | Authorization endpoint of your GitLab OAuth provider. If you use your own instance of GitLab instead of gitlab.com, adjust `auth_url` by replacing the `gitlab.com` hostname with your own. | `https://gitlab.com/oauth/authorize` |
| `token_url` | Yes | Yes | Endpoint used to obtain GitLab OAuth access token. If you use your own instance of GitLab instead of gitlab.com, adjust `token_url` by replacing the `gitlab.com` hostname with your own. | `https://gitlab.com/oauth/token` |
| `api_url` | No | Yes | Grafana uses `<api_url>/user` endpoint to obtain GitLab user information compatible with [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo). | `https://gitlab.com/api/v4` |
| `name` | No | Yes | Name used to refer to the GitLab authentication in the Grafana user interface. | `GitLab` |
| `icon` | No | Yes | Icon used for GitLab authentication in the Grafana user interface. | `gitlab` |
| `scopes` | No | Yes | List of comma or space-separated GitLab OAuth scopes. | `openid email profile` |
| `allow_sign_up` | No | Yes | Whether to allow new Grafana user creation through GitLab login. If set to `false`, then only existing Grafana users can log in with GitLab OAuth. | `true` |
| `auto_login` | No | Yes | Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login. | `false` |
| `login_prompt` | No | Yes | Indicates the type of user interaction when the user logs in with GitLab. Available values are `login`, `consent` and `select_account`. | |
| `role_attribute_path` | No | Yes | [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana role lookup. Grafana will first evaluate the expression using the GitLab OAuth token. If no role is found, Grafana creates a JSON data with `groups` key that maps to groups obtained from GitLab's `/oauth/userinfo` endpoint, and evaluates the expression using this data. Finally, if a valid role is still not found, the expression is evaluated against the user information retrieved from `api_url/users` endpoint and groups retrieved from `api_url/groups` endpoint. The result of the evaluation should be a valid Grafana role (`None`, `Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to [Configure role mapping](#configure-role-mapping). | |
| `role_attribute_strict` | No | Yes | Set to `true` to deny user login if the Grafana role cannot be extracted using `role_attribute_path`. For more information on user role mapping, refer to [Configure role mapping](#configure-role-mapping). | `false` |
| `org_mapping` | No | No | List of comma- or space-separated `<ExternalGitlabGroupName>:<OrgIdOrName>:<Role>` mappings. Value can be `*` meaning "All users". Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. For more information on external organization to role mapping, refer to [Org roles mapping example](#org-roles-mapping-example). | |
| `skip_org_role_sync` | No | Yes | Set to `true` to stop automatically syncing user roles. | `false` |
| `allow_assign_grafana_admin` | No | No | Set to `true` to enable automatic sync of the Grafana server administrator role. If this option is set to `true` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user the server administrator privileges and organization administrator role. If this option is set to `false` and the result of evaluating `role_attribute_path` for a user is `GrafanaAdmin`, Grafana grants the user only organization administrator role. For more information on user role mapping, refer to [Configure role mapping](#configure-role-mapping). | `false` |
| `allowed_domains` | No | Yes | List of comma or space-separated domains. User must belong to at least one domain to log in. | |
| `allowed_groups` | No | Yes | List of comma or space-separated groups. The user should be a member of at least one group to log in. | |
| `tls_skip_verify_insecure` | No | No | If set to `true`, the client accepts any certificate presented by the server and any host name in that certificate. _You should only use this for testing_, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks. | `false` |
| `tls_client_cert` | No | No | The path to the certificate. | |
| `tls_client_key` | No | No | The path to the key. | |
| `tls_client_ca` | No | No | The path to the trusted certificate authority list. | |
| `use_pkce` | No | Yes | Set to `true` to use [Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636). Grafana uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier. | `true` |
| `use_refresh_token` | No | Yes | Set to `true` to use refresh token and check access token expiration. The `accessTokenExpirationCheck` feature toggle should also be enabled to use refresh token. | `true` |
| `signout_redirect_url` | No | Yes | URL to redirect to after the user logs out. | |
docs/sources/setup-grafana/configure-access/configure-authentication/google/index.md
+312
View File
@@ -0,0 +1,312 @@
---
aliases:
- ../../../auth/google/ # /docs/grafana/next/auth/google/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/google/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/google/
- ../../configure-security/configure-authentication/google/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/google/
description: Grafana Google OAuth Guide
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Google OAuth
title: Configure Google OAuth authentication
weight: 1100
---
# Configure Google OAuth authentication
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" >}}
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 >}}
## Create Google OAuth keys
First, you need to create a Google OAuth Client:
1. Go to https://console.developers.google.com/apis/credentials.
1. Create a new project if you don't have one already.
1. Enter a project name. The **Organization** and **Location** fields should both be set to your organization's information.
1. In **OAuth consent screen** select the **External** User Type. Click **CREATE**.
1. Fill out the requested information using the URL of your Grafana Cloud instance.
1. Accept the defaults, or customize the consent screen options.
1. Click **Create Credentials**, then click **OAuth Client ID** in the drop-down menu
1. Enter the following:
- **Application Type**: Web application
- **Name**: Grafana
- **Authorized JavaScript origins**: `https://<YOUR_GRAFANA_URL>`
- **Authorized redirect URIs**: `https://<YOUR_GRAFANA_URL>/login/google`
- Replace `<YOUR_GRAFANA_URL>` with the URL of your Grafana instance.
{{< admonition type="note" >}}
The URL you enter is the one for your Grafana instance home page, not your Grafana Cloud portal URL.
{{< /admonition >}}
1. Click Create
1. Copy the Client ID and Client Secret from the 'OAuth Client' modal
## Configure Google authentication client using the Grafana UI
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.
After you have filled in the form, click **Save**. If the save was successful, Grafana will apply the new configurations.
If you need to reset changes made in the UI back to the default values, click **Reset**. After you have reset the changes, Grafana will apply the configuration from the Grafana configuration file (if there is any configuration) or the default values.
{{< admonition type="note" >}}
If you run Grafana in high availability mode, configuration changes may not get applied to all Grafana instances immediately. You may need to wait a few minutes for the configuration to propagate to all Grafana instances.
{{< /admonition >}}
## Configure Google authentication client using the Terraform provider
```terraform
resource "grafana_sso_settings" "google_sso_settings" {
provider_name = "google"
oauth2_settings {
name = "Google"
client_id = "CLIENT_ID"
client_secret = "CLIENT_SECRET"
allow_sign_up = true
auto_login = false
scopes = "openid email profile"
allowed_domains = "mycompany.com mycompany.org"
hosted_domain = "mycompany.com"
use_pkce = true
}
}
```
Go to [Terraform Registry](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/sso_settings) for a complete reference on using the `grafana_sso_settings` resource.
## Configure Google authentication client using the Grafana configuration file
Ensure that you have access to the [Grafana configuration file](../../../configure-grafana/#configuration-file-location).
### Enable Google OAuth in Grafana
Specify the Client ID and Secret in the [Grafana configuration file](../../../configure-grafana/#configuration-file-location). For example:
```bash
[auth.google]
enabled = true
allow_sign_up = true
auto_login = false
client_id = CLIENT_ID
client_secret = CLIENT_SECRET
scopes = openid email profile
auth_url = https://accounts.google.com/o/oauth2/v2/auth
token_url = https://oauth2.googleapis.com/token
api_url = https://openidconnect.googleapis.com/v1/userinfo
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
correct. For example, in case you are serving Grafana behind a proxy.
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.
You may allow users to sign-up via Google authentication by setting the
`allow_sign_up` option to `true`. When this option is set to `true`, any
user successfully authenticating via Google authentication will be
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" >}}
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.
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 >}}
#### 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).
{{< admonition type="note" >}}
You can disable PKCE in Grafana by setting `use_pkce` to `false` in the`[auth.google]` section.
{{< /admonition >}}
#### Configure refresh token
When a user logs in using an OAuth provider, Grafana verifies that the access token has not expired. When an access token expires, Grafana uses the provided refresh token (if any exists) to obtain a new access token.
Grafana uses a refresh token to obtain a new access token without requiring the user to log in again. If a refresh token doesn't exist, Grafana logs the user out of the system after the access token has expired.
By default, Grafana includes the `access_type=offline` parameter in the authorization request to request a refresh token.
Refresh token fetching and access token expiration check is enabled by default for the Google 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 >}}
#### Configure automatic login
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.
```
auto_login = true
```
### Configure team synchronization
{{< admonition type="note" >}}
Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
With team sync, you can easily add users to teams by utilizing their Google groups. To set up team sync for Google OAuth, refer to the following example.
To set up team sync for Google OAuth:
1. Enable the Google Cloud Identity API on your [organization's dashboard](https://console.cloud.google.com/apis/api/cloudidentity.googleapis.com/).
1. Add the `https://www.googleapis.com/auth/cloud-identity.groups.readonly` scope to your Grafana `[auth.google]` configuration:
Example:
```ini
[auth.google]
# ..
scopes = openid email profile https://www.googleapis.com/auth/cloud-identity.groups.readonly
```
1. Configure team sync in your Grafana team's `External group sync` tab.
The external group ID for a Google group is the group's email address, such as `dev@grafana.com`.
To learn more about Team Sync, refer to [Configure Team Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-team-sync/).
#### Configure allowed groups
To limit access to authenticated users that are members of one or more groups, set `allowed_groups`
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" >}}
Add the `https://www.googleapis.com/auth/cloud-identity.groups.readonly` scope to your Grafana `[auth.google]` scopes configuration to retrieve groups.
{{< /admonition >}}
#### Configure role mapping
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.
If no valid role is found, the user is assigned the role specified by [the `auto_assign_org_role` option](../../../configure-grafana/#auto_assign_org_role).
You can disable this default role assignment by setting `role_attribute_strict = true`. This setting denies user access if no role or an invalid role is returned 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 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
This section includes examples of JMESPath expressions used for role mapping.
##### Org roles mapping example
The Google integration uses the external users' groups in the `org_mapping` configuration to map organizations and roles based on their Google group membership.
In this example, the user has been granted the role of a `Viewer` in the `org_foo` organization, and the role of an `Editor` in the `org_bar` and `org_baz` orgs.
The external user is part of the following Google groups: `group-1` and `group-2`.
Config:
```ini
org_mapping = group-1:org_foo:Viewer group-2:org_bar:Editor *:org_baz:Editor
```
###### Map roles using user information from OAuth token
In this example, the user with email `admin@company.com` has been granted the `Admin` role.
All other users are granted the `Viewer` role.
```ini
role_attribute_path = email=='admin@company.com' && 'Admin' || 'Viewer'
skip_org_role_sync = false
```
###### Map roles using groups
In this example, the user from Google group 'example-group@google.com' have been granted the `Editor` role.
All other users are granted the `Viewer` role.
```ini
role_attribute_path = contains(groups[*], 'example-group@google.com') && 'Editor' || 'Viewer'
skip_org_role_sync = false
```
{{< 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 >}}
###### Map server administrator 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
allow_assign_grafana_admin = true
skip_org_role_sync = false
role_attribute_path = email=='admin@company.com' && 'GrafanaAdmin' || 'Viewer'
```
###### Map one role to all users
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'"
skip_org_role_sync = false
```
## Configuration options
The following table outlines the various Google 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).
| Setting | Required | Supported on Cloud | Description | Default |
| ---------------------------- | -------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `enabled` | No | Yes | Enables Google authentication. | `false` |
| `name` | No | Yes | Name that refers to the Google authentication from the Grafana user interface. | `Google` |
| `icon` | No | Yes | Icon used for the Google authentication in the Grafana user interface. | `google` |
| `client_id` | Yes | Yes | Client ID of the App. | |
| `client_secret` | Yes | Yes | Client secret of the App. | |
| `auth_url` | Yes | Yes | Authorization endpoint of the Google OAuth provider. | `https://accounts.google.com/o/oauth2/v2/auth` |
| `token_url` | Yes | Yes | Endpoint used to obtain the OAuth2 access token. | `https://oauth2.googleapis.com/token` |
| `api_url` | Yes | Yes | Endpoint used to obtain user information compatible with [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo). | `https://openidconnect.googleapis.com/v1/userinfo` |
| `auth_style` | No | Yes | Name of the [OAuth2 AuthStyle](https://pkg.go.dev/golang.org/x/oauth2#AuthStyle) to be used when ID token is requested from OAuth2 provider. It determines how `client_id` and `client_secret` are sent to Oauth2 provider. Available values are `AutoDetect`, `InParams` and `InHeader`. | `AutoDetect` |
| `scopes` | No | Yes | List of comma- or space-separated OAuth2 scopes. | `openid email profile` |
| `allow_sign_up` | No | Yes | Controls Grafana user creation through the Google login. Only existing Grafana users can log in with Google if set to `false`. | `true` |
| `auto_login` | No | Yes | Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login. | `false` |
| `login_prompt` | No | Yes | Indicates the type of user interaction when the user logs in with Google. Available values are `login`, `consent` and `select_account`. | |
| `hosted_domain` | No | Yes | Specifies the domain to restrict access to users from that domain. This value is appended to the authorization request using the `hd` parameter. | |
| `validate_hd` | No | Yes | Set to `false` to disable the validation of the `hd` parameter from the Google ID token. For more informatiion, refer to [Enable Google OAuth in Grafana](#enable-google-oauth-in-grafana). | `true` |
| `role_attribute_strict` | No | Yes | Set to `true` to deny user login if the Grafana org role cannot be extracted using `role_attribute_path` or `org_mapping`. For more information on user role mapping, refer to [Configure role mapping](#configure-role-mapping). | `false` |
| `org_attribute_path` | No | No | [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana org to role lookup. Grafana will first evaluate the expression using the OAuth2 ID token. If no value is returned, the expression will be evaluated using the user information obtained from the UserInfo endpoint. The result of the evaluation will be mapped to org roles based on `org_mapping`. For more information on org to role mapping, refer to [Org roles mapping example](#org-roles-mapping-example). | |
| `org_mapping` | No | No | List of comma- or space-separated `<ExternalOrgName>:<OrgIdOrName>:<Role>` mappings. Value can be `*` meaning "All users". Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. For more information on external organization to role mapping, refer to [Org roles mapping example](#org-roles-mapping-example). | |
| `allow_assign_grafana_admin` | No | No | Set to `true` to automatically sync the Grafana server administrator role. When enabled, if the Google user's App role is `GrafanaAdmin`, Grafana grants the user server administrator privileges and the organization administrator role. If disabled, the user will only receive the organization administrator role. For more details on user role mapping, refer to [Map roles](#map-roles). | `false` |
| `skip_org_role_sync` | No | Yes | Set to `true` to stop automatically syncing user roles. This will allow you to set organization roles for your users from within Grafana manually. | `false` |
| `allowed_groups` | No | Yes | List of comma- or space-separated groups. The user should be a member of at least one group to log in. If you configure `allowed_groups`, you must also configure Google to include the `groups` claim following [Configure allowed groups](#configure-allowed-groups). | |
| `allowed_organizations` | No | Yes | List of comma- or space-separated Azure tenant identifiers. The user should be a member of at least one tenant to log in. | |
| `allowed_domains` | No | Yes | List of comma- or space-separated domains. The user should belong to at least one domain to log in. | |
| `tls_skip_verify_insecure` | No | No | If set to `true`, the client accepts any certificate presented by the server and any host name in that certificate. _You should only use this for testing_, because this mode leaves SSL/TLS susceptible to man-in-the-middle attacks. | `false` |
| `tls_client_cert` | No | No | The path to the certificate. | |
| `tls_client_key` | No | No | The path to the key. | |
| `tls_client_ca` | No | No | The path to the trusted certificate authority list. | |
| `use_pkce` | No | Yes | Set to `true` to use [Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636). Grafana uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier. | `true` |
| `use_refresh_token` | No | Yes | Enables the use of refresh tokens and checks for access token expiration. When enabled, Grafana automatically adds the `promp=consent` and `access_type=offline` parameters to the authorization request. | `true` |
| `signout_redirect_url` | No | Yes | URL to redirect to after the user logs out. | |
docs/sources/setup-grafana/configure-access/configure-authentication/grafana-cloud/index.md
+62
View File
@@ -0,0 +1,62 @@
---
aliases:
- ../../../auth/grafana-cloud/ # /docs/grafana/next/auth/grafana-cloud/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/grafana-cloud/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/grafana-cloud/
- ../../configure-security/configure-authentication/grafana-cloud/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/grafana-cloud/
description: Grafana Cloud Authentication
labels:
products:
- cloud
menuTitle: Grafana Cloud OAuth2
title: Configure Grafana Cloud authentication
weight: 1200
---
# Configure Grafana Cloud authentication
To enable Grafana Cloud as the Identity Provider for a Grafana instance, generate a client ID and client secret and apply the configuration to Grafana.
## Create Grafana Cloud OAuth Client Credentials
To use Grafana Cloud authentication:
1. Log in to [Grafana Cloud](/).
1. To create an OAuth client, locate your organization and click **OAuth Clients**.
1. Click **Add OAuth Client Application**.
1. Add the name and URL of your running Grafana instance.
1. Click **Add OAuth Client**.
1. Copy the client ID and client secret or the configuration that has been generated.
The following snippet shows an example configuration:
```ini
[auth.grafana_com]
enabled = true
allow_sign_up = true
auto_login = false
client_id = 450bc21c10dc2194879d
client_secret = eyJ0Ijoib2F1dGgyYyIhlmlkIjoiNzUwYmMzM2MxMGRjMjE6NDh3OWQiLCJ2IjoiZmI1YzVlYmIwYzFmN2ZhYzZmNjIwOGI1NmVkYTRlNWYxMzgwM2NkMiJ9
scopes = user:email
allowed_organizations = sampleorganization
enabled = true
```
### Configure automatic login
Set `auto_login` option to true to attempt login automatically, skipping the login screen.
This setting is ignored if multiple auth providers are configured to use auto login.
```
auto_login = true
```
## Skip organization role sync
If a user signs in with their Grafana Cloud credentials, their assigned org role overrides the role defined in the Grafana instance. To prevent Grafana Cloud roles from synchronizing, set `skip_org_role_sync` to `true`. This is useful if you want to manage the organization roles for your users from within Grafana.
```ini
[auth.grafana_com]
# ..
# prevents the sync of org roles from Grafana.com
skip_org_role_sync = true
```
docs/sources/setup-grafana/configure-access/configure-authentication/grafana/index.md
+59
View File
@@ -0,0 +1,59 @@
---
aliases:
- ../../../auth/grafana/ # /docs/grafana/next/auth/grafana/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/grafana/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/grafana/
- ../../configure-security/configure-authentication/grafana/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/grafana/
description: Learn how to configure basic authentication in Grafana
labels:
products:
- enterprise
- oss
menuTitle: Basic auth
title: Configure basic authentication
weight: 200
---
# Configure basic authentication
Grafana provides a basic authentication system with password authentication enabled by default. This document details configuration options to manage and enhance basic authentication.
## Disable basic authentication
To disable basic authentication, use the following configuration:
```bash
[auth.basic]
enabled = false
```
## Password policy
By default, Grafana’s password policy requires a minimum of four characters for basic auth users. For a stronger password policy, enable the `password_policy` configuration option.
With the `password_policy` option enabled, new and updated passwords must meet the following criteria:
- At least 12 characters
- At least one uppercase letter
- At least one lowercase letter
- At least one number
- At least one special character
```bash
[auth.basic]
password_policy = true
```
{{< admonition type="note" >}}
Existing passwords that do not comply with the new password policy will not be affected until the user updates their password.
{{< /admonition >}}
## Disable login form
To hide the Grafana login form, use the following configuration setting:
```bash
[auth]
disable_login_form = true
```
This can be helpful in setups where authentication is handled entirely through external mechanisms or single sign-on (SSO).
docs/sources/setup-grafana/configure-access/configure-authentication/jwt/index.md
+324
View File
@@ -0,0 +1,324 @@
---
aliases:
- ../../../auth/jwt/ # /docs/grafana/next/auth/jwt/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/jwt/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/jwt/
- ../../configure-security/configure-authentication/jwt/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/jwt/
description: Grafana JWT Authentication
labels:
products:
- enterprise
- oss
menuTitle: JWT
title: Configure JWT authentication
weight: 1600
---
# Configure JWT authentication
You can configure Grafana to accept a JWT token provided in the HTTP header. The token is verified using any of the following:
- PEM-encoded key file
- JSON Web Key Set (JWKS) in a local file
- JWKS provided by the configured JWKS endpoint
This method of authentication is useful for integrating with other systems that
use JWKS but can't directly integrate with Grafana or if you want to use pass-through
authentication in an app embedding Grafana.
{{< admonition type="note" >}}
Grafana does not currently support refresh tokens.
{{< /admonition >}}
## Enable JWT
To use JWT authentication:
1. Enable JWT in the [main config file](../../../configure-grafana/).
1. Specify the header name that contains a token.
```ini
[auth.jwt]
# By default, auth.jwt is disabled.
enabled = true
# HTTP header to look into to get a JWT token.
header_name = X-JWT-Assertion
```
## Configure login claim
To identify the user, some of the claims needs to be selected as a login info. The subject claim called `"sub"` is mandatory and needs to identify the principal that is the subject of the JWT.
Typically, the subject claim called `"sub"` would be used as a login but it might also be set to some application specific claim.
```ini
# [auth.jwt]
# ...
# Specify a claim to use as a username to sign in.
username_claim = sub
# Specify a claim to use as an email to sign in.
email_claim = sub
# auto-create users if they are not already matched
# auto_sign_up = true
```
If `auto_sign_up` is enabled, then the `sub` claim is used as the "external Auth ID". The `name` claim is used as the user's full name if it is present.
Additionally, if the login username or the email claims are nested inside the JWT structure, you can specify the path to the attributes using the `username_attribute_path` and `email_attribute_path` configuration options using the JMESPath syntax.
JWT structure example.
```json
{
"user": {
"UID": "1234567890",
"name": "John Doe",
"username": "johndoe",
"emails": ["personal@email.com", "professional@email.com"]
}
}
```
```ini
# [auth.jwt]
# ...
# Specify a nested attribute to use as a username to sign in.
username_attribute_path = user.username # user's login is johndoe
# Specify a nested attribute to use as an email to sign in.
email_attribute_path = user.emails[1] # user's email is professional@email.com
```
## Iframe Embedding
If you want to embed Grafana in an iframe while maintaining user identity and role checks,
you can use JWT authentication to authenticate the iframe.
{{< admonition type="note" >}}
For Grafana Cloud, or scenarios where verifying viewer identity is not required,
embed [shared dashboards](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/share-dashboards-panels/shared-dashboards/).
{{< /admonition >}}
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" >}}
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 >}}
In a scenario where it is not possible to rewrite the request headers you
can use URL login instead.
### URL login
`url_login` allows grafana to search for a JWT in the URL query parameter
`auth_token` and use it as the authentication token.
{{< admonition type="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
using HTTP over TLS.
{{< /admonition >}}
```ini
# [auth.jwt]
# ...
url_login = true # enable JWT authentication in the URL
```
An example of an URL for accessing grafana with JWT URL authentication is:
```
http://env.grafana.local/d/RciOKLR4z/board-identifier?orgId=1&kiosk&auth_token=eyJhbxxxxxxxxxxxxx
```
A sample repository using this authentication method is available
at [grafana-iframe-oauth-sample](https://github.com/grafana/grafana-iframe-oauth-sample).
## Signature verification
JSON web token integrity needs to be verified so cryptographic signature is used for this purpose. So we expect that every token must be signed with some known cryptographic key.
You have a variety of options on how to specify where the keys are located.
### Verify token using a JSON Web Key Set loaded from https endpoint
For more information on JWKS endpoints, refer to [Auth0 docs](https://auth0.com/docs/tokens/json-web-tokens/json-web-key-sets).
```ini
# [auth.jwt]
# ...
jwk_set_url = https://your-auth-provider.example.com/.well-known/jwks.json
# When the JWKS url requires an 'Authorization: Bearer <TOKEN>' header
# jwk_set_bearer_token_file = /path/to/bearer_token
# Cache duration for https endpoint response.
cache_ttl = 60m
# Path to file containing one or more custom PEM-encoded CA certificates.
# Used with jwk_set_url when the JWKS endpoint uses a certificate that is not
# trusted by the default CA bundle (e.g. self-signed certificates).
# tls_client_ca = /path/to/ca.crt
# Skip CA Verification entirely
# tls_skip_verify_insecure = false
```
{{< admonition type="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, the default of `60m` is used. `no-store` and `no-cache` cache control headers are ignored. To disable JWKS caching, set `cache_ttl = 0s`
{{< /admonition >}}
### Verify token using a JSON Web Key Set loaded from JSON file
Key set in the same format as in JWKS endpoint but located on disk.
```ini
jwk_set_file = /path/to/jwks.json
```
### Verify token using a single key loaded from PEM-encoded file
PEM-encoded key file in PKIX, PKCS #1, PKCS #8 or SEC 1 format.
```ini
key_file = /path/to/key.pem
```
If the JWT token's header specifies a `kid` (Key ID), then the Key ID must be set using the `key_id` configuration option.
```ini
key_id = my-key-id
```
## Validate claims
By default, only `"exp"`, `"nbf"` and `"iat"` claims are validated.
Consider validating that other claims match your expectations by using the `expect_claims` configuration option.
Token claims must match exactly the values set here.
```ini
# This can be seen as a required "subset" of a JWT Claims Set.
expect_claims = {"iss": "https://your-token-issuer", "your-custom-claim": "foo"}
```
## Roles
Grafana checks for the presence of a role using the [JMESPath](http://jmespath.org/examples.html) specified via the `role_attribute_path` configuration option. The JMESPath is applied to JWT token claims. The result after evaluation of the `role_attribute_path` JMESPath expression should be a valid Grafana role, for example, `None`, `Viewer`, `Editor` or `Admin`.
To assign the role to a specific organization include the `X-Grafana-Org-Id` header along with your JWT when making API requests to Grafana.
To learn more about the header, please refer to the [documentation](../../../../developers/http_api/#x-grafana-org-id-header).
### Configure role mapping
Unless `skip_org_role_sync` option is enabled, the user's role will be set to the role retrieved from the JWT.
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.
If no valid role is found, the user is assigned the role specified by [the `auto_assign_org_role` option](../../../configure-grafana/#auto_assign_org_role).
You can disable this default role assignment by setting `role_attribute_strict = true`. This setting denies user access if no role or an invalid role is returned after evaluating the `role_attribute_path` and the `org_mapping` expressions.
You can use the `org_attribute_path` and `org_mapping` configuration options to assign the user to organizations and specify their role. For more information, refer to [Org roles mapping example](#org-roles-mapping-example). If both org role mapping (`org_mapping`) and the regular role mapping (`role_attribute_path`) are specified, then the user will get the highest of the two mapped roles.
To ease configuration of a proper JMESPath expression, go to [JMESPath](http://jmespath.org/) to test and evaluate expressions with custom payloads.
**Basic example:**
In the following example user will get `Editor` as role when authenticating. The value of the property `role` will be the resulting role if the role is a proper Grafana role, i.e. `None`, `Viewer`, `Editor` or `Admin`.
Payload:
```json
{
...
"role": "Editor",
...
}
```
Configuration:
```ini
role_attribute_path = role
```
**Advanced example:**
In the following example user will get `Admin` as role when authenticating since it has a role `admin`. If a user has a role `editor` it will get `Editor` as role, otherwise `Viewer`.
Payload:
```json
{
...
"info": {
...
"roles": [
"engineer",
"admin",
],
...
},
...
}
```
Configuration:
```ini
role_attribute_path = contains(info.roles[*], 'admin') && 'Admin' || contains(info.roles[*], 'editor') && 'Editor' || 'Viewer'
```
**Org roles mapping example**
In the following example, the , the user has been granted the role of a `Viewer` in the `org_foo` organization, and the role of an `Editor` in the `org_bar` and `org_baz` organizations.
Payload:
```json
{
...
"info": {
...
"orgs": [
"engineer",
"admin",
],
...
},
...
}
```
Configuration:
```ini
org_attribute_path = info.orgs
org_mapping = engineer:org_foo:Viewer admin:org_bar:Editor *:org_baz:Editor
```
### Grafana Admin Role
If the `role_attribute_path` property returns a `GrafanaAdmin` role, Grafana Admin is not assigned by default, instead the `Admin` role is assigned. To allow `Grafana Admin` role to be assigned set `allow_assign_grafana_admin = true`.
### Skip organization role mapping
To skip the assignment of roles and permissions upon login via JWT and handle them via other mechanisms like the user interface, we can skip the organization role synchronization with the following configuration.
```ini
[auth.jwt]
# ...
skip_org_role_sync = true
```
docs/sources/setup-grafana/configure-access/configure-authentication/keycloak-multitenant/index.md
+98
View File
@@ -0,0 +1,98 @@
---
aliases:
- ../../configure-security/setup-grafana/configure-security/configure-authentication/keycloak-multitenant/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/keycloak-multitenant/
- ../../configure-security/configure-authentication/keycloak-multitenant/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/keycloak-multitenant/
description: Multiple providers with Keycloak
keywords:
- grafana
- keycloak
- configuration
- documentation
- oauth
- google
- azure
- okta
labels:
products:
- cloud
- oss
menuTitle: Multiple providers with Keycloak
title: Multiple providers with Keycloak in Grafana
weight: 1350
---
# Multiple providers with Keycloak in Grafana
While Grafana offers a variety of authentication providers, you can only configure one provider of one type at a time. However, you can configure multiple providers of the same type with the help of Keycloak.
This guide explains how to set up multiple providers of the same type with Keycloak as an authentication provider in Grafana.
The idea is to set up multiple OIDC providers in Keycloak with different tenants and configure Grafana to use the same Keycloak instance as the authentication provider.
## Entra ID configuration
For Entra ID, repeat the following steps for each tenant you want to set up in Keycloak.
### Overview
1. Register your application in Entra ID.
1. Give access to the application to the users in the tenant.
1. Create credentials for the application.
1. Configure the application in Keycloak.
1. Configure Grafana to use Keycloak.
#### Register your application in Entra ID
Registering an application in Entra ID is a one-time process. You can follow the steps in the [Entra ID documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) to register your application.
1. Go to the Azure portal and ensure you are using the correct tenant also known as directory.
1. Search for **App Registrations** and click on **New registration**.
1. Fill in the details for the application and click **Register**. You'll be redirected to the application's overview page.
#### Give access to the application to the users in the tenant
Assigning the correct access to users ensures only intended users or groups have access to the application.
1. Search for **Enterprise Applications** and look for the application you just created in the previous step.
1. Under the **Manage** section, click on **Users and groups**.
1. Click on **Add user/group** and add the users or groups that should have access to the application.
#### Create credentials for the application
To authenticate with Entra ID, the Keycloak application needs a client ID and client secret.
1. Search for **App Registrations** and look for the application ypu just created.
1. Click on **Certificates & Secrets**.
1. Click on **New client secret** and fill in the details. Make sure to copy the secret value as it will not be shown again.
#### Configure the application in Keycloak
1. Go to the Keycloak admin console.
1. Go to the Realm where you want to configure the Entra ID tenant.
1. Go to the Identity Providers section and click on **Add provider**.
1. Select **OpenID Connect v1.0**.
1. Select a unique **Alias** and **Display name**.
1. Copy the **Redirect URI**.
1. Back in Azure Portal, go to the application's **Authentication** section.
1. Add a **new platform** and select **Web**.
1. Paste the **Redirect URI** from Keycloak.
1. Save the changes.
1. Navigate to the Azure Application overview and look for the **Endpoints** tab.
1. Copy the **OpenID Connect metadata document** URL.
1. Head back to Keycloak and paste the URL in the **Discovery endpoint** field.
1. Navigate to the Azure application overview and look for the **Application (client) ID**.
1. Copy the **Application ID** and paste it in the **Client ID** field in Keycloak.
1. Paste the client secret you created in the previous step in the **Client secret** field.
1. Click Add.
{{< admonition type="note" >}}
Up to this point, you have created an App Registration in Entra ID, assigned users to the application, created credentials for the application, and configured the application in Keycloak. In the Keycloak Client's section, the client with ID `account` Home URL can be used to test the configuration. This will open a new tab where you can login into the correct Keycloak realm with the Entra ID tenant you just configured.
{{< /admonition >}}
Repeat this steps, for every Entra ID tenant you want to configure in Keycloak.
#### Configure Grafana to use Keycloak
Now that the Entra ID tenants are configured in Keycloak, you can configure Grafana to use Keycloak as the authentication provider.
Refer to the [Keycloak documentation](https://grafana.com/docs/grafana/latest/auth/keycloak/) to configure Grafana to use Keycloak as the authentication provider.
docs/sources/setup-grafana/configure-access/configure-authentication/keycloak/index.md
+184
View File
@@ -0,0 +1,184 @@
---
aliases:
- ../../../auth/keycloak/ # /docs/grafana/next/auth/keycloak/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/keycloak/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/keycloak/
- ../../configure-security/configure-authentication/keycloak/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/keycloak/
description: Grafana Keycloak Guide
keywords:
- grafana
- keycloak
- configuration
- documentation
- oauth
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Keycloak OAuth2
title: Configure Keycloak OAuth2 authentication
weight: 1300
---
# Configure Keycloak OAuth2 authentication
Keycloak OAuth2 authentication allows users to log in to Grafana using their Keycloak credentials. This guide explains how to set up Keycloak as an authentication provider in Grafana.
Refer to [Generic OAuth authentication](../generic-oauth/) for extra configuration options available for this provider.
{{< admonition type="note" >}}
If you use the same email address in Keycloak as in 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 >}}
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.
Example config:
```ini
[auth.generic_oauth]
enabled = true
name = Keycloak-OAuth
allow_sign_up = true
client_id = YOUR_APP_CLIENT_ID
client_secret = YOUR_APP_CLIENT_SECRET
scopes = openid email profile offline_access roles
email_attribute_path = email
login_attribute_path = username
name_attribute_path = full_name
auth_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/auth
token_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/token
api_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/userinfo
role_attribute_path = contains(roles[*], 'admin') && 'Admin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'
```
As an example, `<PROVIDER_DOMAIN>` can be `keycloak-demo.grafana.org`
and `<REALM_NAME>` can be `grafana`.
To configure the `kc_idp_hint` parameter for Keycloak, you need to change the `auth_url` configuration to include the `kc_idp_hint` parameter. For example if you want to hint the Google identity provider:
```ini
auth_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/auth?kc_idp_hint=google
```
{{< admonition type="note" >}}
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 >}}
## Keycloak configuration
1. Create a client in Keycloak with the following settings:
- Client ID: `grafana-oauth`
- Enabled: `ON`
- Client Protocol: `openid-connect`
- Access Type: `confidential`
- Standard Flow Enabled: `ON`
- Implicit Flow Enabled: `OFF`
- Direct Access Grants Enabled: `ON`
- Root URL: `<grafana_root_url>`
- Valid Redirect URIs: `<grafana_root_url>/login/generic_oauth`
- Web Origins: `<grafana_root_url>`
- Admin URL: `<grafana_root_url>`
- Base URL: `<grafana_root_url>`
As an example, `<grafana_root_url>` can be `https://play.grafana.org`.
Non-listed configuration options can be left at their default values.
2. In the client scopes configuration, _Assigned Default Client Scopes_ should match:
```
email
offline_access
profile
roles
```
{{< admonition type="warning" >}}
These scopes do not add group claims to the `id_token`. Without group claims, teamsync will not work. Teamsync is covered further down in this document.
{{< /admonition >}}
3. For role mapping to work with the example configuration above,
you need to create the following roles and assign them to users:
```
admin
editor
viewer
```
## Team sync
{{< admonition type="note" >}}
Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
[Team Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/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.
To enable teamsync, you need to add a `groups` mapper to the client configuration in Keycloak.
This will add the `groups` claim to the id_token. You can then use the `groups` claim to map groups to teams in Grafana.
1. In the client configuration, head to `Mappers` and create a mapper with the following settings:
- Name: `Group Mapper`
- Mapper Type: `Group Membership`
- Token Claim Name: `groups`
- Full group path: `OFF`
- Add to ID token: `ON`
- Add to access token: `OFF`
- Add to userinfo: `ON`
2. In Grafana's configuration add the following option:
```ini
[auth.generic_oauth]
groups_attribute_path = groups
```
If you use nested groups containing special characters such as quotes or colons, the JMESPath parser can perform a harmless reverse function so Grafana can properly evaluate nested groups. The following example shows a parent group named `Global` with nested group `department` that contains a list of groups:
```ini
[auth.generic_oauth]
groups_attribute_path = reverse("Global:department")
```
## Enable Single Logout
To enable Single Logout, you need to add the following option to the configuration of Grafana:
```ini
[auth.generic_oauth]
signout_redirect_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/logout?post_logout_redirect_uri=https%3A%2F%2F<GRAFANA_DOMAIN>%2Flogin
```
As an example, `<PROVIDER_DOMAIN>` can be `keycloak-demo.grafana.org`,
`<REALM_NAME>` can be `grafana` and `<GRAFANA_DOMAIN>` can be `play.grafana.org`.
{{< admonition type="note" >}}
Grafana supports ID token hints for single logout. Grafana automatically adds the `id_token_hint` parameter to the logout request if it detects OAuth as the authentication method.
{{< /admonition >}}
## Allow assigning Grafana Admin
If the application role received by Grafana is `GrafanaAdmin` , Grafana grants the user server administrator privileges.
This is useful if you want to grant server administrator privileges to a subset of users.
Grafana also assigns the user the `Admin` role of the default organization.
```ini
role_attribute_path = contains(roles[*], 'grafanaadmin') && 'GrafanaAdmin' || contains(roles[*], 'admin') && 'Admin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'
allow_assign_grafana_admin = true
```
### Configure refresh token
When a user logs in using an OAuth provider, Grafana verifies that the access token has not expired. When an access token expires, Grafana uses the provided refresh token (if any exists) to obtain a new access token.
Grafana uses a refresh token to obtain a new access token without requiring the user to log in again. If a refresh token doesn't exist, Grafana logs the user out of the system after the access token has expired.
To enable a refresh token for Keycloak, do the following:
1. Extend the `scopes` in `[auth.generic_oauth]` with `offline_access`.
1. Add `use_refresh_token = true` to `[auth.generic_oauth]` configuration.
docs/sources/setup-grafana/configure-access/configure-authentication/ldap-ui/_index.md
+122
View File
@@ -0,0 +1,122 @@
---
aliases:
- ../../../auth/enhanced-ldap/ # /docs/grafana/next/auth/enhanced-ldap/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/ldap-ui/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/ldap-ui/
- ../../configure-security/configure-authentication/ldap-ui/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/ldap-ui/
description: Learn about configuring LDAP authentication in Grafana using the Grafana UI.
labels:
products:
- cloud
- enterprise
- oss
menuTitle: LDAP user interface
title: Configure LDAP authentication using the Grafana user interface
weight: 300
---
# Configure LDAP authentication using the Grafana user interface
This page explains how to configure LDAP authentication in Grafana using the Grafana user interface. For more detailed information about configuring LDAP authentication using the configuration file, refer to [LDAP authentication](../ldap/).
Benefits of using the Grafana user interface to configure LDAP authentication include:
- No need to edit the configuration file manually.
- Quickly test the connection to the LDAP server.
- No need to restart Grafana after making changes.
{{< admonition type="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 >}}
## Before you begin
To follow these instructions, you need:
- Knowledge of LDAP authentication and how it works.
- A Grafana instance v11.3.0 or later.
- Permissions `settings:read` and `settings:write` with `settings:auth.ldap:*` scope.
- The `ssoSettingsLDAP` feature toggle enabled.
## Steps to configure LDAP authentication
Sign in to Grafana and navigate to **Administration > Authentication > LDAP**.
### 1. Complete mandatory fields
The mandatory fields have an asterisk (**\***) next to them. Complete the following fields:
1. **Server host**: Host name or IP address of the LDAP server.
1. **Search filter**: The LDAP search filter finds entries within the directory.
1. **Search base DNS**: List of base DNs to search through.
### 2. Complete optional fields
Complete the optional fields as needed:
1. **Bind DN**: Distinguished name (DN) of the user to bind to.
1. **Bind password**: Password for the server.
### 3. Advanced settings
Click the **Edit** button in the **Advanced settings** section to configure the following settings:
#### 1. Miscellaneous settings
Complementary settings for LDAP authentication.
1. **Allow sign-up**: Allows new users to register upon logging in.
1. **Port**: Port number of the LDAP server. The default is 389.
1. **Timeout**: Time in seconds to wait for a response from the LDAP server.
#### 2. Attributes
Attributes used to map LDAP user assertion to Grafana user attributes.
1. **Name**: Name of the assertion attribute to map to the Grafana user name.
1. **Surname**: Name of the assertion attribute to map to the Grafana user surname.
1. **Username**: Name of the assertion attribute to map to the Grafana user username.
1. **Member Of**: Name of the assertion attribute to map to the Grafana user membership.
1. **Email**: Name of the assertion attribute to map to the Grafana user email.
#### 3. Group mapping
Map LDAP groups to Grafana roles.
1. **Skip organization role sync**: This option avoids syncing organization roles. It is useful when you want to manage roles manually.
1. **Group search filter**: The LDAP search filter finds groups within the directory.
1. **Group search base DNS**: List of base DNS to specify the matching groups' locations.
1. **Group name attribute**: Identifies users within group entries.
1. **Manage group mappings**:
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.
1. **Add the organization ID membership mapping**: Map the group to an organization ID.
1. **Define Grafana Admin membership**: Enable Grafana Admin privileges to the group.
#### 4. Extra security settings
Additional security settings options for LDAP authentication.
1. **Enable SSL**: This option will enable SSL to connect to the LDAP server.
1. **Start TLS**: Use StartTLS to secure the connection to the LDAP server.
1. **Min TLS version**: Choose the minimum TLS version to use. TLS1.2 or TLS1.3
1. **TLS ciphers**: List the ciphers to use for the connection. For a complete list of ciphers, refer to the [Cipher Go library](https://go.dev/src/crypto/tls/cipher_suites.go).
1. **Encryption key and certificate provision specification**:
This section allows you to specify the key and certificate for the LDAP server. You can provide the key and certificate in two ways: **base-64** encoded or **path to files**.
1. **Base-64 encoded certificate**:
All values used in this section must be base-64 encoded.
1. **Root CA certificate content**: List of root CA certificates.
1. **Client certificate content**: Client certificate content.
1. **Client key content**: Client key content.
1. **Path to files**:
Path in the file system to the key and certificate files
1. **Root CA certificate path**: Path to the root CA certificate.
1. **Client certificate path**: Path to the client certificate.
1. **Client key path**: Path to the client key.
### 4. Persisting the configuration
Once you have configured the LDAP settings, click **Save** to persist the configuration.
If you want to delete all the changes made through the UI and revert to the configuration file settings, click the three dots menu icon and click **Reset to default values**.
docs/sources/setup-grafana/configure-access/configure-authentication/ldap/index.md
+407
View File
@@ -0,0 +1,407 @@
---
aliases:
- ../../../auth/ldap/ # /docs/grafana/next/auth/ldap/
- ../../../installation/ldap/ # /docs/grafana/next/installation/ldap/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/ldap/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/ldap/
- ../../configure-security/configure-authentication/ldap/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/ldap/
description: Grafana LDAP Authentication Guide
labels:
products:
- cloud
- enterprise
- oss
menuTitle: LDAP
title: Configure LDAP authentication
weight: 300
---
# Configure LDAP authentication
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" >}}
[Enhanced LDAP authentication](../enhanced-ldap/) is available in [Grafana Cloud](/docs/grafana-cloud/) and in [Grafana Enterprise](../../../../introduction/grafana-enterprise/).
{{< /admonition >}}
Refer to [Role-based access control](../../../../administration/roles-and-permissions/access-control/) to understand how you can control access with role-based permissions.
## Supported LDAP Servers
Grafana uses a [third-party LDAP library](https://github.com/go-ldap/ldap) under the hood that supports basic LDAP v3 functionality.
This means that you should be able to configure LDAP integration using any compliant LDAPv3 server, for example [OpenLDAP](#openldap) or
[Active Directory](#active-directory) among [others](https://en.wikipedia.org/wiki/Directory_service#LDAP_implementations).
## Enable LDAP
In order to use LDAP integration you'll first need to enable LDAP in the [main config file](../../../configure-grafana/) as well as specify the path to the LDAP
specific configuration file (default: `/etc/grafana/ldap.toml`).
After enabling LDAP, the default behavior is for Grafana users to be created automatically upon successful LDAP authentication. If you prefer for only existing Grafana users to be able to sign in, you can change `allow_sign_up` to `false` in the `[auth.ldap]` section.
```ini
[auth.ldap]
# Set to `true` to enable LDAP integration (default: `false`)
enabled = true
# Path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`)
config_file = /etc/grafana/ldap.toml
# Allow sign-up should be `true` (default) to allow Grafana to create users on successful LDAP authentication.
# If set to `false` only already existing Grafana users will be able to login.
allow_sign_up = true
```
## Disable org role synchronization
If you use LDAP to authenticate users but don't use role mapping, and prefer to manually assign organizations
and roles, you can use the `skip_org_role_sync` configuration option.
```ini
[auth.ldap]
# Set to `true` to enable LDAP integration (default: `false`)
enabled = true
# Path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`)
config_file = /etc/grafana/ldap.toml
# Allow sign-up should be `true` (default) to allow Grafana to create users on successful LDAP authentication.
# If set to `false` only already existing Grafana users will be able to login.
allow_sign_up = true
# Prevent synchronizing ldap users organization roles
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.
See [configuration examples](#configuration-examples) for more information.
**LDAP specific configuration file (ldap.toml) example:**
```bash
[[servers]]
# Ldap server host (specify multiple hosts space separated)
host = "ldap.my_secure_remote_server.org"
# Default port is 389 or 636 if use_ssl = true
port = 636
# Set to true if LDAP server should use an encrypted TLS connection (either with STARTTLS or LDAPS)
use_ssl = true
# If set to true, use LDAP with STARTTLS instead of LDAPS
start_tls = false
# The value of an accepted TLS cipher. By default, this value is empty. Example value: ["TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"])
# For a complete list of supported ciphers and TLS versions, refer to: https://go.dev/src/crypto/tls/cipher_suites.go
# Starting with Grafana v11.0 only ciphers with ECDHE support are accepted for TLS 1.2 connections.
tls_ciphers = []
# This is the minimum TLS version allowed. By default, this value is empty. Accepted values are: TLS1.1 (only for Grafana v10.4 or earlier), TLS1.2, TLS1.3.
min_tls_version = ""
# set to true if you want to skip SSL cert validation
ssl_skip_verify = false
# set to the path to your root CA certificate or leave unset to use system defaults
# root_ca_cert = "/path/to/certificate.crt"
# Authentication against LDAP servers requiring client certificates
# client_cert = "/path/to/client.crt"
# client_key = "/path/to/client.key"
# Search user bind dn
bind_dn = "cn=admin,dc=grafana,dc=org"
# Search user bind password
# If the password contains # or ; you have to wrap it with triple quotes. Ex """#password;"""
bind_password = "grafana"
# We recommend using variable expansion for the bind_password, for more info https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#variable-expansion
# bind_password = '$__env{LDAP_BIND_PASSWORD}'
# Timeout in seconds. Applies to each host specified in the 'host' entry (space separated).
timeout = 10
# User search filter, for example "(cn=%s)" or "(sAMAccountName=%s)" or "(uid=%s)"
# Allow login from email or username, example "(|(sAMAccountName=%s)(userPrincipalName=%s))"
search_filter = "(cn=%s)"
# An array of base dns to search through
search_base_dns = ["dc=grafana,dc=org"]
# group_search_filter = "(&(objectClass=posixGroup)(memberUid=%s))"
# group_search_filter_user_attribute = "distinguishedName"
# group_search_base_dns = ["ou=groups,dc=grafana,dc=org"]
# Specify names of the LDAP attributes your LDAP uses
[servers.attributes]
member_of = "memberOf"
email = "email"
```
{{< admonition type="note" >}}
Whenever you modify the ldap.toml file, you must restart Grafana in order for the change(s) to take effect.
{{< /admonition >}}
### Using the Grafana user interface
You can configure LDAP using the Grafana user interface by navigating to **Administration > Authentication > LDAP**. Please refer to the [LDAP user interface](../ldap-ui/) documentation for more information.
### Using environment variables
You can interpolate variables in the TOML configuration from environment variables. For instance, you could externalize your `bind_password` that way:
```bash
bind_password = "${LDAP_ADMIN_PASSWORD}"
```
### Bind and bind password
By default the configuration expects you to specify a bind DN and bind password. This should be a read only user that can perform LDAP searches.
When the user DN is found a second bind is performed with the user provided username and password (in the normal Grafana login form).
```bash
bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"
```
#### Single bind example
If you can provide a single bind expression that matches all possible users, you can skip the second bind and bind against the user DN directly.
This allows you to not specify a bind_password in the configuration file.
```bash
bind_dn = "cn=%s,o=users,dc=grafana,dc=org"
```
In this case you skip providing a `bind_password` and instead provide a `bind_dn` value with a `%s` somewhere. This will be replaced with the username entered in on the Grafana login page.
The search filter and search bases settings are still needed to perform the LDAP search to retrieve the other LDAP information (like LDAP groups and email).
### POSIX schema
If your LDAP server does not support the `memberOf` attribute, add the following options:
```bash
## Group search filter, to retrieve the groups of which the user is a member (only set if memberOf attribute is not available)
group_search_filter = "(&(objectClass=posixGroup)(memberUid=%s))"
## An array of the base DNs to search through for groups. Typically uses ou=groups
group_search_base_dns = ["ou=groups,dc=grafana,dc=org"]
## the %s in the search filter will be replaced with the attribute defined below
group_search_filter_user_attribute = "uid"
```
### Group mappings
In `[[servers.group_mappings]]` you can map an LDAP group to a Grafana organization and role. These will be synced every time the user logs in, with LDAP being the authoritative source.
The first group mapping that an LDAP user is matched to will be used for the sync. If you have LDAP users that fit multiple mappings, the topmost mapping in the TOML configuration will be used.
**LDAP specific configuration file (ldap.toml) example:**
```bash
[[servers]]
# other settings omitted for clarity
[[servers.group_mappings]]
group_dn = "cn=superadmins,dc=grafana,dc=org"
org_role = "Admin"
grafana_admin = true
[[servers.group_mappings]]
group_dn = "cn=admins,dc=grafana,dc=org"
org_role = "Admin"
[[servers.group_mappings]]
group_dn = "cn=users,dc=grafana,dc=org"
org_role = "Editor"
[[servers.group_mappings]]
group_dn = "*"
org_role = "Viewer"
```
| Setting | Required | Description | Default |
| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `group_dn` | Yes | LDAP distinguished name (DN) of LDAP group. If you want to match all (or no LDAP groups) then you can use wildcard (`"*"`) |
| `org_role` | Yes | Assign users of `group_dn` the organization role `Admin`, `Editor`, or `Viewer`. The organization role name is case sensitive. |
| `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" >}}
Commenting out a group mapping requires also commenting out the header of
said group or it will fail validation as an empty mapping.
{{< /admonition >}}
Example:
```bash
[[servers]]
# other settings omitted for clarity
[[servers.group_mappings]]
group_dn = "cn=superadmins,dc=grafana,dc=org"
org_role = "Admin"
grafana_admin = true
# [[servers.group_mappings]]
# group_dn = "cn=admins,dc=grafana,dc=org"
# org_role = "Admin"
[[servers.group_mappings]]
group_dn = "cn=users,dc=grafana,dc=org"
org_role = "Editor"
```
### Nested/recursive group membership
Users with nested/recursive group membership must have an LDAP server that supports `LDAP_MATCHING_RULE_IN_CHAIN`
and configure `group_search_filter` in a way that it returns the groups the submitted username is a member of.
To configure `group_search_filter`:
- You can set `group_search_base_dns` to specify where the matching groups are defined.
- If you do not use `group_search_base_dns`, then the previously defined `search_base_dns` is used.
**Active Directory example:**
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:
```bash
group_search_filter = "(member:1.2.840.113556.1.4.1941:=%s)"
group_search_base_dns = ["DC=mycorp,DC=mytld"]
group_search_filter_user_attribute = "dn"
```
```bash
group_search_filter = "(member:1.2.840.113556.1.4.1941:=CN=%s,[user container/OU])"
group_search_filter = "(|(member:1.2.840.113556.1.4.1941:=CN=%s,[user container/OU])(member:1.2.840.113556.1.4.1941:=CN=%s,[another user container/OU]))"
group_search_filter_user_attribute = "cn"
```
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).
## Configuration examples
The following examples describe different LDAP configuration options.
### OpenLDAP
[OpenLDAP](http://www.openldap.org/) is an open source directory service.
**LDAP specific configuration file (ldap.toml):**
```bash
[[servers]]
host = "127.0.0.1"
port = 389
use_ssl = false
start_tls = false
ssl_skip_verify = false
bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"
search_filter = "(cn=%s)"
search_base_dns = ["dc=grafana,dc=org"]
[servers.attributes]
member_of = "memberOf"
email = "email"
# [[servers.group_mappings]] omitted for clarity
```
### Multiple LDAP servers
Grafana does support receiving information from multiple LDAP servers.
**LDAP specific configuration file (ldap.toml):**
```bash
# --- First LDAP Server ---
[[servers]]
host = "10.0.0.1"
port = 389
use_ssl = false
start_tls = false
ssl_skip_verify = false
bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"
search_filter = "(cn=%s)"
search_base_dns = ["ou=users,dc=grafana,dc=org"]
[servers.attributes]
member_of = "memberOf"
email = "email"
[[servers.group_mappings]]
group_dn = "cn=admins,ou=groups,dc=grafana,dc=org"
org_role = "Admin"
grafana_admin = true
# --- Second LDAP Server ---
[[servers]]
host = "10.0.0.2"
port = 389
use_ssl = false
start_tls = false
ssl_skip_verify = false
bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"
search_filter = "(cn=%s)"
search_base_dns = ["ou=users,dc=grafana,dc=org"]
[servers.attributes]
member_of = "memberOf"
email = "email"
[[servers.group_mappings]]
group_dn = "cn=editors,ou=groups,dc=grafana,dc=org"
org_role = "Editor"
[[servers.group_mappings]]
group_dn = "*"
org_role = "Viewer"
```
### Active Directory
[Active Directory](<https://technet.microsoft.com/en-us/library/hh831484(v=ws.11).aspx>) is a directory service which is commonly used in Windows environments.
Assuming the following Active Directory server setup:
- IP address: `10.0.0.1`
- Domain: `CORP`
- DNS name: `corp.local`
**LDAP specific configuration file (ldap.toml):**
```bash
[[servers]]
host = "10.0.0.1"
port = 3269
use_ssl = true
start_tls = false
ssl_skip_verify = true
bind_dn = "CORP\\%s"
search_filter = "(sAMAccountName=%s)"
search_base_dns = ["dc=corp,dc=local"]
[servers.attributes]
member_of = "memberOf"
email = "mail"
# [[servers.group_mappings]] omitted for clarity
```
#### Port requirements
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 information, enable LDAP debug logging in the [`grafana.ini` or `custom.ini`](../../../configure-grafana/) file:
```bash
[log]
filters = ldap:debug
```
docs/sources/setup-grafana/configure-access/configure-authentication/okta/index.md
+283
View File
@@ -0,0 +1,283 @@
---
aliases:
- ../../../auth/okta/ # /docs/grafana/next/auth/okta/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/okta/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/okta/
- ../../configure-security/configure-authentication/okta/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/okta/
description: Grafana Okta OIDC Guide
labels:
products:
- cloud
- enterprise
- oss
menuTitle: Okta OIDC
title: Configure Okta OIDC authentication
weight: 1400
---
# Configure Okta OIDC authentication
{{< docs/shared lookup="auth/intro.md" source="grafana" version="<GRAFANA VERSION>" >}}
{{< admonition type="note" >}}
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 >}}
## Before you begin
To follow this guide, ensure you have permissions in your Okta workspace to create an OIDC app.
## Create an Okta app
1. From the Okta Admin Console, select **Create App Integration** from the **Applications** menu.
1. For **Sign-in method**, select **OIDC - OpenID Connect**.
1. For **Application type**, select **Web Application** and click **Next**.
1. Configure **New Web App Integration Operations**:
- **App integration name**: Choose a name for the app.
- **Logo (optional)**: Add a logo.
- **Grant type**: Select **Authorization Code** and **Refresh Token**.
- **Sign-in redirect URIs**: Replace the default setting with the Grafana Cloud Okta path, replacing <YOUR_ORG> with the name of your Grafana organization: https://<YOUR_ORG>.grafana.net/login/okta. For on-premises installation, use the Grafana server URL: http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/okta.
- **Sign-out redirect URIs (optional)**: Replace the default setting with the Grafana Cloud Okta path, replacing <YOUR_ORG> with the name of your Grafana organization: https://<YOUR_ORG>.grafana.net/logout. For on-premises installation, use the Grafana server URL: http://<my_grafana_server_name_or_ip>:<grafana_server_port>/logout.
- **Base URIs (optional)**: Add any base URIs
- **Controlled access**: Select whether to assign the app integration to everyone in your organization, or only selected groups. You can assign this option after you create the app.
1. Make a note of the following:
- **ClientID**
- **Client Secret**
- **Auth URL**
For example: https://<TENANT_ID>.okta.com/oauth2/v1/authorize
- **Token URL**
For example: https://<TENANT_ID>.okta.com/oauth2/v1/token
- **API URL**
For example: https://<TENANT_ID>.okta.com/oauth2/v1/userinfo
### Configure Okta to Grafana role mapping
1. In the **Okta Admin Console**, select **Directory > Profile Editor**.
1. Select the Okta Application Profile you created previously (the default name for this is `<App name> User`).
1. Select **Add Attribute** and fill in the following fields:
- **Data Type**: string
- **Display Name**: Meaningful name. For example, `Grafana Role`.
- **Variable Name**: Meaningful name. For example, `grafana_role`.
- **Description (optional)**: A description of the role.
- **Enum**: Select **Define enumerated list of values** and add the following:
- Display Name: Admin Value: Admin
- Display Name: Editor Value: Editor
- Display Name: Viewer Value: Viewer
The remaining attributes are optional and can be set as needed.
1. Click **Save**.
1. (Optional) You can add the role attribute to the default User profile. To do this, please follow the steps in the [Optional: Add the role attribute to the User (default) Okta profile](#optional-add-the-role-attribute-to-the-user-default-okta-profile) section.
### Configure Groups claim
1. In the **Okta Admin Console**, select **Application > Applications**.
1. Select the OpenID Connect application you created.
1. Go to the **Sign On** tab and click **Edit** in the **OpenID Connect ID Token** section.
1. In the **Group claim type** section, select **Filter**.
1. In the **Group claim filter** section, leave the default name `groups` (or add it if the box is empty), then select **Matches regex** and add the following regex: `.*`.
1. Click **Save**.
1. Click the **Back to applications** link at the top of the page.
1. From the **More** button dropdown menu, click **Refresh Application Data**.
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" >}}
If you configure the `groups` claim differently, ensure that the `groups` claim is a string array.
{{< /admonition >}}
#### Optional: Add the role attribute to the User (default) Okta profile
If you want to configure the role for all users in the Okta directory, you can add the role attribute to the User (default) Okta profile.
1. Return to the **Directory** section and select **Profile Editor**.
1. Select the User (default) Okta profile, and click **Add Attribute**.
1. Set all of the attributes in the same way you did in **Step 3**.
1. Select **Add Mapping** to add your new attributes.
For example, **user.grafana_role -> grafana_role**.
1. To add a role to a user, select the user from the **Directory**, and click **Profile -> Edit**.
1. Select an option from your new attribute and click **Save**.
1. Update the Okta integration by setting the `Role attribute path` (`role_attribute_path` in Terraform and config file) to `<YOUR_ROLE_VARIABLE>`. For example: `role_attribute_path = grafana_role` (using the configuration).
## Configure Okta authentication client using the Grafana UI
As a Grafana Admin, you can configure Okta OAuth2 client from within Grafana using the Okta UI. To do this, navigate to **Administration > Authentication > Okta** page and fill in the form. If you have a current configuration in the Grafana configuration file then the form will be pre-populated with those values otherwise the form will contain default values.
After you have filled in the form, click **Save**. If the save was successful, Grafana will apply the new configurations.
If you need to reset changes you made in the UI back to the default values, click **Reset**. After you have reset the changes, Grafana will apply the configuration from the Grafana configuration file (if there is any configuration) or the default values.
{{< admonition type="note" >}}
If you run Grafana in high availability mode, configuration changes may not get applied to all Grafana instances immediately. You may need to wait a few minutes for the configuration to propagate to all Grafana instances.
{{< /admonition >}}
Refer to [configuration options](#configuration-options) for more information.
## Configure Okta authentication client using the Terraform provider
```terraform
resource "grafana_sso_settings" "okta_sso_settings" {
provider_name = "okta"
oauth2_settings {
name = "Okta"
auth_url = "https://<okta tenant id>.okta.com/oauth2/v1/authorize"
token_url = "https://<okta tenant id>.okta.com/oauth2/v1/token"
api_url = "https://<okta tenant id>.okta.com/oauth2/v1/userinfo"
client_id = "CLIENT_ID"
client_secret = "CLIENT_SECRET"
allow_sign_up = true
auto_login = false
scopes = "openid profile email offline_access"
role_attribute_path = "contains(groups[*], 'Example::DevOps') && 'Admin' || 'None'"
role_attribute_strict = true
allowed_groups = "Example::DevOps,Example::Dev,Example::QA"
}
}
```
Go to [Terraform Registry](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/sso_settings) for a complete reference on using the `grafana_sso_settings` resource.
## Configure Okta authentication client using the Grafana configuration file
Ensure that you have access to the [Grafana configuration file](../../../configure-grafana/#configuration-file-location).
### Steps
To integrate your Okta OIDC provider with Grafana using our Okta OIDC integration, follow these steps:
1. Follow the [Create an Okta app](#create-an-okta-app) steps to create an OIDC app in Okta.
1. Refer to the following table to update field values located in the `[auth.okta]` section of the Grafana configuration file:
| Field | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `client_id` | These values must match the client ID from your Okta OIDC app. |
| `auth_url` | The authorization endpoint of your OIDC provider. `https://<okta-tenant-id>.okta.com/oauth2/v1/authorize` |
| `token_url` | The token endpoint of your Okta OIDC provider. `https://<okta-tenant-id>.okta.com/oauth2/v1/token` |
| `api_url` | The user information endpoint of your Okta OIDC provider. `https://<tenant-id>.okta.com/oauth2/v1/userinfo` |
| `enabled` | Enables Okta OIDC authentication. Set this value to `true`. |
1. Review the list of other Okta OIDC [configuration options](#configuration-options) and complete them as necessary.
1. Optional: [Configure a refresh token](#configure-a-refresh-token).
1. [Configure role mapping](#configure-role-mapping).
1. Optional: [Configure team synchronization](#configure-team-synchronization-enterprise-only).
1. Restart Grafana.
You should now see a Okta OIDC login button on the login page and be able to log in or sign up with your OIDC provider.
The following is an example of a minimally functioning integration when
configured with the instructions above:
```ini
[auth.okta]
name = Okta
icon = okta
enabled = true
allow_sign_up = true
client_id = <client id>
scopes = openid profile email offline_access
auth_url = https://<okta tenant id>.okta.com/oauth2/v1/authorize
token_url = https://<okta tenant id>.okta.com/oauth2/v1/token
api_url = https://<okta tenant id>.okta.com/oauth2/v1/userinfo
role_attribute_path = grafana_role
role_attribute_strict = true
allowed_groups = "Example::DevOps" "Example::Dev" "Example::QA"
```
### Configure a refresh token
When a user logs in using an OAuth provider, Grafana verifies that the access token has not expired. When an access token expires, Grafana uses the provided refresh token (if any exists) to obtain a new access token without requiring the user to log in again.
If a refresh token doesn't exist, Grafana logs the user out of the system after the access token has expired.
To enable the `Refresh Token` head over the Okta application settings and:
1. Under `General` tab, find the `General Settings` section.
1. Within the `Grant Type` options, enable the `Refresh Token` checkbox.
At the configuration file, extend the `scopes` in `[auth.okta]` section with `offline_access` and set `use_refresh_token` to `true`.
### Configure role mapping
{{< admonition type="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 >}}
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.
If no valid role is found, the user is assigned the role specified by [the `auto_assign_org_role` option](../../../configure-grafana/#auto_assign_org_role).
You can disable this default role assignment by setting `role_attribute_strict = true`. This setting denies user access if no role or an invalid role is returned after evaluating the `role_attribute_path` and the `org_mapping` expressions.
You can use the `org_attribute_path` and `org_mapping` configuration options to assign the user to organizations and specify their role. For more information, refer to [Org roles mapping example](#org-roles-mapping-example). If both org role mapping (`org_mapping`) and the regular role mapping (`role_attribute_path`) are specified, then the user will get the highest of the two mapped roles.
To allow mapping Grafana server administrator role, use the `allow_assign_grafana_admin` configuration option.
Refer to [configuration options](../generic-oauth/#configuration-options) for more information.
In [Create an Okta app](#create-an-okta-app), you created a custom attribute in Okta to store the role. You can use this attribute to map the role to a Grafana role by setting the `role_attribute_path` configuration option to the custom attribute name: `role_attribute_path = grafana_role`.
If you want to map the role based on the user's group, you can use the `groups` attribute from the user info endpoint. An example of this is `role_attribute_path = contains(groups[*], 'Example::DevOps') && 'Admin' || 'None'`. You can find more examples of JMESPath expressions on the Generic OAuth page for [JMESPath examples](../generic-oauth/#role-mapping-examples).
To learn about adding custom claims to the user info in Okta, refer to [add custom claims](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/main/#add-a-custom-claim-to-a-token).
#### Org roles mapping example
{{< admonition type="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.
Config:
```ini
org_attribute_path = groups
org_mapping = ["Group 1:org_foo:Viewer", "Group 2:org_bar:Editor", "*:3:Editor"]
```
### Configure team synchronization
{{< admonition type="note" >}}
Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
By using Team Sync, you can link your Okta groups to teams within Grafana. This will automatically assign users to the appropriate teams.
Map your Okta groups to teams in Grafana so that your users will automatically be added to
the correct teams.
Okta groups can be referenced by group names, like `Admins` or `Editors`.
To learn more about Team Sync, refer to [Configure Team Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-team-sync/).
## Configuration options
The following table outlines the various Okta OIDC configuration options. You can apply these options as environment variables, similar to any other configuration within Grafana. For more information, refer to [Override configuration with environment variables](../../../configure-grafana/#override-configuration-with-environment-variables).
{{< admonition type="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"`
{{< /admonition >}}
| Setting | Required | Supported on Cloud | Description | Default |
| ----------------------- | -------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `enabled` | No | Yes | Enables Okta OIDC authentication. | `false` |
| `name` | No | Yes | Name that refers to the Okta OIDC authentication from the Grafana user interface. | `Okta` |
| `icon` | No | Yes | Icon used for the Okta OIDC authentication in the Grafana user interface. | `okta` |
| `client_id` | Yes | Yes | Client ID provided by your Okta OIDC app. | |
| `client_secret` | Yes | Yes | Client secret provided by your Okta OIDC app. | |
| `auth_url` | Yes | Yes | Authorization endpoint of your Okta OIDC provider. | |
| `token_url` | Yes | Yes | Endpoint used to obtain the Okta OIDC access token. | |
| `api_url` | Yes | Yes | Endpoint used to obtain user information. | |
| `scopes` | No | Yes | List of comma- or space-separated Okta OIDC scopes. | `openid profile email groups` |
| `allow_sign_up` | No | Yes | Controls Grafana user creation through the Okta OIDC login. Only existing Grafana users can log in with Okta OIDC if set to `false`. | `true` |
| `auto_login` | No | Yes | Set to `true` to enable users to bypass the login screen and automatically log in. This setting is ignored if you configure multiple auth providers to use auto-login. | `false` |
| `role_attribute_path` | No | Yes | [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana role lookup. Grafana will first evaluate the expression using the Okta OIDC ID token. If no role is found, the expression will be evaluated using the user information obtained from the UserInfo endpoint. The result of the evaluation should be a valid Grafana role (`None`, `Viewer`, `Editor`, `Admin` or `GrafanaAdmin`). For more information on user role mapping, refer to [Configure role mapping](#configure-role-mapping). | |
| `role_attribute_strict` | No | Yes | Set to `true` to deny user login if the Grafana org role cannot be extracted using `role_attribute_path` or `org_mapping`. For more information on user role mapping, refer to [Configure role mapping](#configure-role-mapping). | `false` |
| `org_attribute_path` | No | No | [JMESPath](http://jmespath.org/examples.html) expression to use for Grafana org to role lookup. The result of the evaluation will be mapped to org roles based on `org_mapping`. For more information on org to role mapping, refer to [Org roles mapping example](#org-roles-mapping-example). | |
| `org_mapping` | No | No | List of comma- or space-separated `<ExternalOrgName>:<OrgIdOrName>:<Role>` mappings. Value can be `*` meaning "All users". Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. For more information on external organization to role mapping, refer to [Org roles mapping example](#org-roles-mapping-example). | |
| `skip_org_role_sync` | No | Yes | Set to `true` to stop automatically syncing user roles. This will allow you to set organization roles for your users from within Grafana manually. | `false` |
| `allowed_groups` | No | Yes | List of comma- or space-separated groups. The user should be a member of at least one group to log in. | |
| `allowed_domains` | No | Yes | List of comma- or space-separated domains. The user should belong to at least one domain to log in. | |
| `use_pkce` | No | Yes | Set to `true` to use [Proof Key for Code Exchange (PKCE)](https://datatracker.ietf.org/doc/html/rfc7636). Grafana uses the SHA256 based `S256` challenge method and a 128 bytes (base64url encoded) code verifier. | `true` |
| `use_refresh_token` | No | Yes | Set to `true` to use refresh token and check access token expiration. | `false` |
| `signout_redirect_url` | No | Yes | URL to redirect to after the user logs out. | |
docs/sources/setup-grafana/configure-access/configure-authentication/passwordless/index.md
+51
View File
@@ -0,0 +1,51 @@
---
aliases:
- ../../configure-security/setup-grafana/configure-security/configure-authentication/passwordless/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/passwordless/
- ../../configure-security/configure-authentication/passwordless/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/passwordless/
description: Learn how to configure passwordless authentication with magic links in Grafana
labels:
products:
- enterprise
- oss
menuTitle: Passwordless
title: Configure passwordless authentication with magic links
weight: 200
---
# Configure passwordless authentication with magic links
Passwordless authentication lets Grafana users authenticate with a magic link or one-time password (OTP) sent via email.
## Enable passwordless authentication
{{< admonition type="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 >}}
To enable passwordless authentication, use the following configuration:
```bash
[auth.passwordless]
enabled = true
```
## Code expiration
By default, the one-time password (OTP) sent to a user's email is valid for 20 minutes. Use the `code_expiration` option to change the duration that the OTP is valid.
```bash
[auth.passwordless]
enabled = true
code_expiration = 20m
```
## Enable SMTP server
The SMTP server must be enabled so that Grafana can send emails.
The following configuration enables the SMTP server.
For more information on configuring the SMTP server, refer to [SMTP](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#smtp).
```bash
[smtp]
enabled = true
```
docs/sources/setup-grafana/configure-access/configure-authentication/saml/_index.md
+257
View File
@@ -0,0 +1,257 @@
---
aliases:
- ../../../auth/saml/ # /docs/grafana/latest/auth/saml/
- ../../../enterprise/configure-saml/ # /docs/grafana/latest/enterprise/configure-saml/
- ../../../enterprise/saml/ # /docs/grafana/latest/enterprise/saml/
- ../../../enterprise/saml/about-saml/ # /docs/grafana/latest/enterprise/saml/about-saml/
- ../../../enterprise/saml/configure-saml/ # /docs/grafana/latest/enterprise/saml/configure-saml/
- ../../../enterprise/saml/enable-saml/ # /docs/grafana/latest/enterprise/saml/enable-saml/
- ../../../enterprise/saml/set-up-saml-with-okta/ # /docs/grafana/latest/enterprise/saml/set-up-saml-with-okta/
- ../../../enterprise/saml/troubleshoot-saml/ # /docs/grafana/latest/enterprise/saml/troubleshoot-saml/
- ../../configure-security/setup-grafana/configure-security/configure-authentication/saml/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-authentication/saml/
- ../../configure-security/configure-authentication/saml/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/saml/
description: Learn how to configure SAML authentication in Grafana's configuration file.
labels:
products:
- cloud
- enterprise
menuTitle: SAML
title: Configure SAML authentication in Grafana
weight: 500
---
# SAML authentication in Grafana
{{< admonition type="note" >}}
Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud).
{{< /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.
You can configure SAML authentication in Grafana through one of the following methods:
- Configure SAML using the [Grafana configuration file](#configure-saml-using-the-grafana-configuration-file)
- Configure SAML using the [SSO Settings API](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/developers/http_api/sso-settings/)
- Configure SAML using the [SAML user interface](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/saml-ui/)
- Configure SAML using the [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/<GRAFANA_VERSION>/docs/resources/sso_settings)
If you are using Okta or Entra ID as Identity Provider, see the following documentation for configuration:
- [Configure SAML with Entra ID](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/configure-saml-with-azuread/)
- [Configure SAML with Okta](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/configure-saml-with-okta/)
- [Configure SAML with Okta catalog application](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/configure-saml-with-okta/oin-application)
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" >}}
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 >}}
## SAML Bindings
Grafana supports the following SAML 2.0 bindings:
- From the Service Provider (SP) to the Identity Provider (IdP):
- `HTTP-POST` binding
- `HTTP-Redirect` binding
- From the Identity Provider (IdP) to the Service Provider (SP):
- `HTTP-POST` binding
## Request Initiation
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).
## 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`.
Refer to [Configuration](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/) for more information about configuring Grafana.
## Identity provider (IdP) registration
For the SAML integration to work correctly, you need to make the IdP aware of the SP.
The integration provides two key endpoints as part of Grafana:
- The `/saml/metadata` endpoint, which contains the SP metadata. You can either download and upload it manually, or you make the IdP request it directly from the endpoint. Some providers name it Identifier or Entity ID.
- The `/saml/acs` endpoint, which is intended to receive the ACS (Assertion Customer Service) callback. Some providers name it SSO URL or Reply URL.
## Configure SAML using the Grafana configuration file
1. In the `[auth.saml]` section in the Grafana configuration file, set [`enabled`](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/enterprise-configuration/#enabled-3) to `true`.
2. Configure SAML options:
- Review all [available configuration options](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/saml-configuration-options/)
- For IdP-specific configuration, refer to:
- [Configure SAML with Okta](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/configure-saml-with-okta/)
- [Configure SAML with Entra ID](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/configure-saml-with-azuread/)
3. Save the configuration file and then restart the Grafana server.
When you are finished, the Grafana configuration might look like this example:
```ini
[server]
root_url = https://grafana.example.com
[auth.saml]
enabled = true
name = My IdP
auto_login = false
private_key_path = "/path/to/private_key.pem"
certificate_path = "/path/to/certificate.cert"
idp_metadata_url = "https://my-org.okta.com/app/my-application/sso/saml/metadata"
assertion_attribute_name = DisplayName
assertion_attribute_login = Login
assertion_attribute_email = Email
assertion_attribute_groups = Group
```
## Assertion mapping
During the SAML SSO authentication flow, Grafana receives the ACS callback. The callback contains all the relevant information of the user under authentication embedded in the SAML response. Grafana parses the response to create (or update) the user within its internal database.
For Grafana to map the user information, it looks at the individual attributes within the assertion. You can think of these attributes as Key/Value pairs (although, they contain more information than that).
Grafana provides configuration options that let you modify which keys to look at for these values. The data we need to create the user in Grafana is Name, Login handle, and email.
### The `assertion_attribute_name` option
`assertion_attribute_name` is a special assertion mapping that can either be a simple key, indicating a mapping to a single assertion attribute on the SAML response, or a complex template with variables using the `$__saml{<attribute>}` syntax. If this property is misconfigured, Grafana will log an error message on startup and disallow SAML sign-ins. Grafana will also log errors after a login attempt if a variable in the template is missing from the SAML response.
**Examples**
```ini
#plain string mapping
assertion_attribute_name = displayName
```
```ini
#template mapping
assertion_attribute_name = $__saml{firstName} $__saml{lastName}
```
## SAML Name ID
The `name_id_format` configuration field specifies the requested format of the NameID element in the SAML assertion.
By default, this is set to `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` and does not need to be specified in the configuration file.
The following list includes valid configuration field values:
| `name_id_format` value in the configuration file or Terraform | `Name identifier format` on the UI |
| ------------------------------------------------------------- | ---------------------------------- |
| `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` | Default |
| `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified` | Unspecified |
| `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` | Email address |
| `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` | Persistent |
| `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` | Transient |
## IdP metadata
You also need to define the public part of the IdP for message verification. The SAML IdP metadata XML defines where and how Grafana exchanges user information.
Grafana supports three ways of specifying the IdP metadata.
- Without a suffix `idp_metadata`, Grafana assumes base64-encoded XML file contents.
- With the `_path` suffix, Grafana assumes a path and attempts to read the file from the file system.
- With the `_url` suffix, Grafana assumes a URL and attempts to load the metadata from the given location.
## Maximum issue delay
Prevents SAML response replay attacks and internal clock skews between the SP (Grafana) and the IdP. You can set a maximum amount of time between the SP issuing the AuthnRequest and the SP (Grafana) processing it.
The configuration options is specified as a duration, such as `max_issue_delay = 90s` or `max_issue_delay = 1h`.
## Metadata valid duration
SP metadata is likely to expire at some point, perhaps due to a certificate rotation or change of location binding. Grafana allows you to specify for how long the metadata should be valid. Leveraging the `validUntil` field, you can tell consumers until when your metadata is going to be valid. The duration is computed by adding the duration to the current time.
The configuration option is specified as a duration, such as `metadata_valid_duration = 48h`.
## Allow new user sign up
By default, new Grafana users using SAML authentication will have an account created for them automatically. To decouple authentication and account creation and ensure only users with existing accounts can log in with SAML, set the `allow_sign_up` option to false.
## Integrating with SCIM Provisioning
If you are also using SCIM provisioning for this Grafana application in Entra ID, it's crucial to align the user identifiers between SAML and SCIM for seamless operation. The unique identifier that links the SAML user to the SCIM provisioned user is determined by the `assertion_attribute_external_uid` setting in the Grafana SAML configuration. This `assertion_attribute_external_uid` should correspond to the `externalId` used in SCIM provisioning (typically set to the Entra ID `user.objectid`).
1. **Ensure Consistent Identifier in SAML Assertion:**
- The unique identifier from Entra ID (typically `user.objectid`) that you mapped to the `externalId` attribute in Grafana in your SCIM provisioning setup **must also be sent as a claim in the SAML assertion.** For more details on SCIM, refer to the [SCIM provisioning documentation](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/).
- In the Entra ID Enterprise Application, under **Single sign-on** > **Attributes & Claims**, ensure you add a claim that provides this identifier. For example, you might add a claim named `UserID` (or similar, like `externalId`) that sources its value from `user.objectid`.
2. **Configure Grafana SAML Settings for SCIM:**
- In the `[auth.saml]` section of your Grafana configuration, set `assertion_attribute_external_uid` to the name of the SAML claim you configured in the previous step (e.g., `userUID` or the full URI like `http://schemas.microsoft.com/identity/claims/objectidentifier` if that's how Entra ID sends it).
- The `assertion_attribute_login` setting should still be configured to map to the attribute your users will log in with (e.g., `userPrincipalName`, `mail`).
_Example Grafana Configuration:_
```ini
[auth.saml]
# ... other SAML settings ...
assertion_attribute_login = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier # Or other login attribute
assertion_attribute_external_uid = http://schemas.microsoft.com/identity/claims/objectidentifier # Or your custom claim name for user.objectid
```
Ensure that the value specified in `assertion_attribute_external_uid` precisely matches the name of the claim as it's sent in the SAML assertion from Entra ID.
3. **SCIM Linking Identifier and Entra ID:**
- By default (if `assertion_attribute_external_uid` is not set), Grafana uses the `userUID` attribute from the SAML assertion for SCIM linking.
- **Recommended for Entra ID:** For SCIM integration with Entra ID, it is necessary to:
1. Ensure Entra ID sends the `user.objectid` in a claim.
2. Either set this claim name in Entra ID to `userUID`, or, if you want to use a different claim name, set `assertion_attribute_external_uid` in Grafana to match the claim name you chose in Entra ID.
## Configure automatic login
Set `auto_login` option to true to attempt login automatically, skipping the login screen.
This setting is ignored if multiple auth providers are configured to use auto login.
For more information about automatic login behavior and troubleshooting, see [Automatic login](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/#automatic-oauth-login).
```
auto_login = true
```
## Configure allowed organizations
With the [`allowed_organizations`](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/enterprise-configuration/#allowed_organizations) option you can specify a list of organizations where the user must be a member of at least one of them to be able to log in to Grafana.
To get the list of user's organizations from SAML attributes, you must configure the `assertion_attribute_org` option. This option specifies which SAML attribute contains the list of organizations the user belongs to.
To put values containing spaces in the list, use the following JSON syntax:
```ini
allowed_organizations = ["org 1", "second org"]
```
## Configuring SAML with HTTP-Post binding
If multiple bindings are supported for SAML Single Sign-On (SSO) by the Identity Provider (IdP), Grafana will use the `HTTP-Redirect` binding by default. If the IdP only supports the `HTTP-Post binding` then updating the `content_security_policy_template` (in case `content_security_policy = true`) and `content_security_policy_report_only_template` (in case `content_security_policy_report_only = true`) might be required to allow Grafana to initiate a POST request to the IdP. These settings are used to define the [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) headers that are sent by Grafana.
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 identity provider 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 identity provider domain, update the `form-action` directive to include the identity provider domain, for example: `form-action 'self' https://idp.example.com`.
{{< admonition type="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 >}}
## IdP-initiated Single Sign-On (SSO)
By default, Grafana allows only service provider (SP) initiated logins (when the user logs in with SAML via the login page in Grafana). If you want users to log in into Grafana directly from your identity provider (IdP), set the `allow_idp_initiated` configuration option to `true` and configure `relay_state` with the same value specified in the IdP configuration.
IdP-initiated SSO has some security risks, so make sure you understand the risks before enabling this feature. When using IdP-initiated login, Grafana receives unsolicited SAML responses and can't verify that login flow was started by the user. This makes it hard to detect whether SAML message has been stolen or replaced. Because of this, IdP-initiated login is vulnerable to login cross-site request forgery (CSRF) and man in the middle (MITM) attacks. We do not recommend using IdP-initiated login and keeping it disabled whenever possible.
## Advanced configuration
For advanced configuration and troubleshooting, please refer to the one of the following pages:
- [Configure SAML request signing](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/configure-saml-signing-encryption/)
- [Configure SAML single logout](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/configure-saml-single-logout/)
- [Configure Organization mapping](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/configure-saml-org-mapping/)
- [Configure Role and Team sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/configure-saml-team-role-mapping/)
- [SAML configuration options](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/saml-configuration-options/)
- [Troubleshooting](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/troubleshoot-saml/)
docs/sources/setup-grafana/configure-access/configure-authentication/saml/configure-saml-org-mapping/_index.md
+67
View File
@@ -0,0 +1,67 @@
---
aliases:
- ../../../configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/configure-saml-org-mapping/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/configure-saml-org-mapping/
- ../../../configure-security/configure-authentication/saml/configure-saml-org-mapping/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/saml/configure-saml-org-mapping/
description: Learn how to configure SAML authentication in Grafana's UI.
labels:
products:
- cloud
- enterprise
menuTitle: Configure Organisation mapping for SAML
title: Configure Organisation mapping for SAML
weight: 550
---
# Configure organization mapping for SAML
Organization mapping allows you to assign users to particular organization in Grafana depending on attribute value obtained from identity provider.
1. In configuration file, set [`assertion_attribute_org`](https://grafana.com/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`](https://grafana.com/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:
```ini
[auth.saml]
assertion_attribute_org = Org
org_mapping = Engineering:2:Editor, Sales:3:Admin
```
{{< admonition type="warning" >}}
The `org_mapping` option stores mappings in the database as JSON. Size limits depend on your database. In MySQL before Grafana 12.3, the limit is 65,535 bytes. From Grafana 12.3, the column uses `MEDIUMTEXT`, raising the MySQL limit to 16,777,215 bytes (~16 MB). If you need to split users into more granular control, we suggest using [Role and Team Sync](../configure-saml-team-role-mapping/) instead.
{{< /admonition >}}
Starting from Grafana version 11.5, you can use the organization name instead of the organization ID in the `org_mapping` option. Ensure that the organization name you configure matches exactly with the organization name in Grafana, as it is case-sensitive. If the organization name is not found in Grafana, the mapping will be ignored. If the external organization or the organization name contains spaces, use the JSON syntax for the `org_mapping` option:
```ini
org_mapping = ["Org 1:2:Editor", "ExternalOrg:ACME Corp.:Admin"]
```
If one of the mappings contains a `:`, use the JSON syntax and escape the `:` with a backslash:
```ini
# Assign users from "External:Admin" to the organization with name "ACME Corp" as Admin
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:
```ini
[auth.saml]
assertion_attribute_org = Org
org_mapping = ["Engineering:ACME Corp:Editor", "Sales:3:Admin"]
```
You can specify multiple organizations both for the IdP and Grafana:
- `org_mapping = Engineering:2, Sales:2` to map users from `Engineering` and `Sales` to `2` in Grafana.
- `org_mapping = Engineering:2, Engineering:3` to assign `Engineering` to both `2` and `3` in Grafana.
You can use `*` as the SAML Organization if you want all your users to be in some Grafana organizations with a default role:
- `org_mapping = *:2:Editor` to map all users to the organization which ID is `2` in Grafana as Editors.
You can use `*` as the Grafana organization in the mapping if you want all users from a given SAML Organization to be added to all existing Grafana organizations.
- `org_mapping = Engineering:*` to map users from `Engineering` to all existing Grafana organizations.
- `org_mapping = Administration:*:Admin` to map users from `Administration` to all existing Grafana organizations as Admins.
docs/sources/setup-grafana/configure-access/configure-authentication/saml/configure-saml-signing-encryption/_index.md
+78
View File
@@ -0,0 +1,78 @@
---
aliases:
- ../../../configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/configure-saml-signing-encryption/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/configure-saml-signing-encryption/
- ../../../configure-security/configure-authentication/saml/configure-saml-signing-encryption/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/saml/configure-saml-signing-encryption/
description: Learn how to configure SAML authentication in Grafana's UI.
labels:
products:
- cloud
- enterprise
menuTitle: Configure SAML signing and encryption
title: Configure SAML signing and encryption
weight: 530
---
# Configure SAML signing and encryption
Grafana supports signed and encrypted responses, and _only_ supports signed requests.
## Certificate and private key
Commonly, the certificate and key are embedded in the IdP metadata and refreshed as needed by Grafana automatically. However, if your IdP expects signed requests, you must supply a certificate and private key.
The SAML SSO standard uses asymmetric encryption to exchange information between the SP (Grafana) and the IdP. To perform such encryption, you need a public part and a private part. In this case, the X.509 certificate provides the public part, while the private key provides the private part. The private key needs to be issued in a [PKCS#8](https://en.wikipedia.org/wiki/PKCS_8) format.
If you are directly supplying the certificate and key, Grafana supports two ways of specifying both the `certificate` and `private_key`:
- 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 path and attempts to read the file from the file system.
{{< admonition type="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 >}}
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.
## Signature algorithm
The SAML standard requires digital signatures for security-critical messages such as authentication and logout requests. When you configure the `signature_algorithm` option, Grafana automatically signs these SAML requests using your configured private key and certificate.
### Supported algorithms
- `rsa-sha1`: Legacy algorithm, not recommended for new deployments
- `rsa-sha256`: Recommended for most use cases
- `rsa-sha512`: Strongest security, but may impact performance
### Important considerations
- The signature algorithm must match your IdP configuration exactly
- Mismatched algorithms will cause signature validation failures
- Grafana uses the key and certificate specified in `private_key` and `certificate` options for signing
- We recommend using `rsa-sha256` for new SAML implementations
## Example of private key generation for SAML authentication
An example of how to generate a self-signed certificate and private key that's valid for one year:
```sh
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes​
```
Base64-encode the cert.pem and key.pem files:
(-w0 switch is not needed on Mac, only for Linux)
```sh
$ base64 -i key.pem -o key.pem.base64
$ base64 -i cert.pem -o cert.pem.base64
```
The base64-encoded values (`key.pem.base64, cert.pem.base64` files) are then used for `certificate` and `private key`.
The key you provide should look like:
```
-----BEGIN PRIVATE KEY-----
...
...
-----END PRIVATE KEY-----
```
docs/sources/setup-grafana/configure-access/configure-authentication/saml/configure-saml-single-logout/_index.md
+21
View File
@@ -0,0 +1,21 @@
---
aliases:
- ../../../configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/configure-saml-single-logout/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/configure-saml-single-logout/
- ../../../configure-security/configure-authentication/saml/configure-saml-single-logout/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/saml/configure-saml-single-logout/
description: Learn how to configure SAML authentication in Grafana's UI.
labels:
products:
- cloud
- enterprise
menuTitle: Configure SAML single logout
title: Configure SAML single logout
weight: 560
---
# Configure SAML Single Logout
The single logout feature allows users to log out from all applications associated with the current IdP session established via SAML SSO. If the `single_logout` option is set to `true` and a user logs out, Grafana requests IdP to end the user session which in turn triggers logout from all other applications the user is logged into using the same IdP session (applications should support single logout). Conversely, if another application connected to the same IdP logs out using single logout, Grafana receives a logout request from IdP and ends the user session.
{{< admonition type="note" >}}
The improved SLO features, including proper handling of the IdP's SessionIndex, are currently behind the `improvedExternalSessionHandlingSAML` feature toggle. When this feature toggle is enabled, Grafana will correctly handle session-specific logouts. If the feature toggle is not enabled, logging out will end all of the user's sessions.
{{< /admonition >}}
docs/sources/setup-grafana/configure-access/configure-authentication/saml/configure-saml-team-role-mapping/_index.md
+110
View File
@@ -0,0 +1,110 @@
---
aliases:
- ../../../configure-access/configure-authentication/saml/configure-saml-team-role-mapping/ # /docs/grafana/next/configure-access/configure-authentication/saml/configure-saml-team-role-mapping/
- ../../../configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/configure-saml-team-role-mapping/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/configure-saml-team-role-mapping/
- ../../../configure-security/configure-authentication/saml/configure-saml-team-role-mapping/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/saml/configure-saml-team-role-mapping/
description: Learn how to configure SAML authentication in Grafana's UI.
labels:
products:
- cloud
- enterprise
menuTitle: Configure Role and Team sync for SAML
title: Configure Role and Team sync for SAML
weight: 540
---
# Configure team sync for SAML
{{< admonition type="note" >}}
Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
To use SAML Team sync, set [`assertion_attribute_groups`](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/enterprise-configuration/#assertion_attribute_groups) to the attribute name where you store user groups. Then Grafana will use attribute values extracted from SAML assertion to add user into the groups with the same name configured on the External group sync tab.
{{< admonition type="warning" >}}
Grafana requires the SAML groups attribute to be configured with distinct `AttributeValue` elements for each group. Do not include multiple groups within a single `AttributeValue` delimited by a comma or any other character. Failure to do so will prevent correct group parsing. Example:
```xml
<saml2:Attribute ...>
<saml2:AttributeValue ...>admins_group</saml2:AttributeValue>
<saml2:AttributeValue ...>division_1</saml2:AttributeValue>
</saml2:Attribute>
```
{{< /admonition >}}
{{< admonition type="note" >}}
Team Sync allows you sync users from SAML to Grafana teams. It does not automatically create teams in Grafana. You need to create teams in Grafana before you can use this feature.
{{< /admonition >}}
Given the following partial SAML assertion:
```xml
<saml2:Attribute
Name="groups"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml2:AttributeValue
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:string">admins_group
</saml2:AttributeValue>
<saml2:AttributeValue
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="xs:string">division_1
</saml2:AttributeValue>
</saml2:Attribute>
```
The configuration would look like this:
```ini
[auth.saml]
# ...
assertion_attribute_groups = groups
```
The following `External Group ID`s would be valid for input in the desired team's _External group sync_ tab:
- `admins_group`
- `division_1`
[Learn more about Team Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-team-sync/)
# Configure role sync for SAML
Role sync allows you to map user roles from an identity provider to Grafana. To enable role sync, configure role attribute and possible values for the Editor, Admin, and Grafana Admin roles. For more information about user roles, refer to [Roles and permissions](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/).
1. In the configuration file, set [`assertion_attribute_role`](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/enterprise-configuration/#assertion_attribute_role) option to the attribute name where the role information will be extracted from.
1. Set the [`role_values_none`](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/enterprise-configuration/#role_values_none) option to the values mapped to the `None` role.
1. Set the [`role_values_viewer`](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/enterprise-configuration/#role_values_viewer) option to the values mapped to the `Viewer` role.
1. Set the [`role_values_editor`](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/enterprise-configuration/#role_values_editor) option to the values mapped to the `Editor` role.
1. Set the [`role_values_admin`](https://grafana.com/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`](https://grafana.com/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` configuration option will be assigned. If the `auto_assign_org_role` field is not set then the user role will default to `Viewer`.
For more information about roles and permissions in Grafana, refer to [Roles and permissions](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/).
Example configuration:
```ini
[auth.saml]
assertion_attribute_role = role
role_values_none = none
role_values_viewer = external
role_values_editor = editor, developer
role_values_admin = admin, operator
role_values_grafana_admin = superadmin
```
**Important**: When role sync is configured, any changes of user roles and organization membership made manually in Grafana will be overwritten on next user login. Assign user organizations and roles in the IdP instead.
If you don't want user organizations and roles to be synchronized with the IdP, you can use the `skip_org_role_sync` configuration option.
Example configuration:
```ini
[auth.saml]
skip_org_role_sync = true
```
docs/sources/setup-grafana/configure-access/configure-authentication/saml/configure-saml-with-entraid/_index.md
+143
View File
@@ -0,0 +1,143 @@
---
aliases:
- ../../../configure-access/configure-authentication/saml/configure-saml-with-azuread/ # /docs/grafana/next/setup-grafana/configure-access/configure-authentication/saml/configure-saml-with-azuread/
- ../../../configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/configure-saml-with-entraid/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/configure-saml-with-entraid/
- ../../../configure-security/configure-authentication/saml/configure-saml-with-azuread/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/saml/configure-saml-with-azuread/
description: Learn how to configure SAML authentication in Grafana's UI.
labels:
products:
- cloud
- enterprise
menuTitle: Configure SAML with Entra ID
title: Configure SAML authentication with Entra ID
weight: 570
---
# Configure SAML with Microsoft Entra ID
Grafana supports user authentication through Microsoft Entra ID. This topic shows you how to configure SAML authentication in Grafana with [Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id).
{{< admonition type="note" >}}
If an Entra ID user belongs to more than 150 groups, a Graph API endpoint is used 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 the Entra ID connector.
As of Grafana 11.2, the SAML integration offers a mechanism to retrieve user groups from the Graph API.
Related links:
- [Entra ID SAML limitations](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#groups-overage-claim)
- [Configure a Graph API application in Entra ID](#configure-a-graph-api-application-in-entra-id)
{{< /admonition >}}
## Before you begin
Ensure you have permission to administer SAML authentication. For more information about roles and permissions in Grafana, refer to [Roles and permissions](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/).
If you have users that belong to more than 150 groups, configure a registered application to provide an Entra ID Graph API to retrieve the groups. Refer to [Setup Entra ID Graph API applications](#configure-a-graph-api-application-in-entra-id).
## Generate self-signed certificates
Entra ID requires a certificate to verify the SAML requests' signature. You can generate a private key and a self-signed certificate using the following command (the private key used to sign the requests and the certificate contains the public key for verification):
```sh
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
```
This will generate a `key.pem` and `cert.pem` file that you can use for the `private_key_path` and `certificate_path` configuration options.
## Add Microsoft Entra SAML Toolkit from the gallery
> Taken from https://learn.microsoft.com/en-us/entra/identity/saas-apps/saml-toolkit-tutorial#add-microsoft-entra-saml-toolkit-from-the-gallery
1. Go to the [Azure portal](https://portal.azure.com/#home) and sign in with your Entra ID account.
1. Search for **Enterprise Applications**.
1. In the **Enterprise applications** pane, select **New application**.
1. In the search box, enter **SAML Toolkit**, and then select the **Microsoft Entra SAML Toolkit** from the results panel.
1. Add a descriptive name and select **Create**.
## Configure the SAML Toolkit application endpoints
In order to validate Entra ID users with Grafana, you need to configure the SAML Toolkit application endpoints by creating a new SAML integration in the Entra ID organization.
> For the following configuration, we will use `https://localhost` as the Grafana URL. Replace it with your Grafana URL.
1. In the **SAML Toolkit application**, select **Set up single sign-on**.
1. In the **Single sign-on** pane, select **SAML**.
1. In the Set up **Single Sign-On with SAML** pane, select the pencil icon for **Basic SAML Configuration** to edit the settings.
1. In the **Basic SAML Configuration** pane, click on the **Edit** button and update the following fields:
- In the **Identifier (Entity ID)** field, enter `https://localhost/saml/metadata`.
- In the **Reply URL (Assertion Consumer Service URL)** field, enter `https://localhost/saml/acs`.
- In the **Sign on URL** field, enter `https://localhost`.
- In the **Relay State** field, enter `https://localhost`.
- In the **Logout URL** field, enter `https://localhost/saml/slo`.
1. Select **Save**.
1. At the **SAML Certificate** section, copy the **App Federation Metadata Url**.
- Use this URL in the `idp_metadata_url` field in the `custom.ini` file.
### Generate a client secret
1. In the **Overview** pane, select **Certificates & secrets**.
1. Select **New client secret**.
1. In the **Add a client secret** pane, enter a description for the secret.
1. Set the expiration date for the secret.
1. Select **Add**.
1. Copy the value of the secret. This value is used in the `client_secret` field in the [SAML configuration](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/saml-configuration-options/).
## Configure SAML assertions when using SCIM provisioning
In order to verify the logged in user is the same user that was provisioned through Entra ID, you need to include the same `externalId` in the SAML assertion by mapping the SAML assertion `assertion_attribute_external_id`.
1. Open your Entra ID application.
1. Select the SAML single sign-on configuration.
1. Edit the `Attributes & Claims` section.
1. Add a new claim with the following settings:
- Name: `userUID`
- Namespace: leave blank
- Source: Attribute
- Source attribute: `user.objectId`
1. **Save** the current configuration.
## Configure a Graph API application in Entra ID
While an Entra ID tenant can be configured in Grafana via SAML, some additional information is only accessible via the Graph API. To retrieve this information, create a new application in Entra ID and grant it the necessary permissions.
> [Entra ID SAML limitations](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#groups-overage-claim)
> For the following configuration, the URL `https://localhost` will be used as the Grafana URL. Replace it with your Grafana instance URL.
### Create a new App registration
This app registration will be used as a Service Account to retrieve more information about the user from the Entra ID.
1. Go to the [Azure portal](https://portal.azure.com/#home) and sign in with your Entra ID account.
1. In the left-hand navigation pane, select the Microsoft Entra ID service, and then select **App registrations**.
1. Click the **New registration** button.
1. In the **Register an application** pane, enter a name for the application.
1. In the **Supported account types** section, select the account types that can use the application.
1. In the **Redirect URI** section, select Web and enter `https://localhost/login/azuread`.
1. Click the **Register** button.
### Set up permissions for the application
1. In the overview pane, look for **API permissions** section and select **Add a permission**.
1. In the **Request API permissions** pane, select **Microsoft Graph**, and click **Application permissions**.
1. In the **Select permissions** pane, under the **GroupMember** section, select **GroupMember.Read.All**.
1. In the **Select permissions** pane, under the **User** section, select **User.Read.All**.
1. Click the **Add permissions** button at the bottom of the page.
1. In the **Request API permissions** pane, select **Microsoft Graph**, and click **Delegated permissions**.
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.
1. In the **API permissions** section, select **Grant admin consent for `<directory-name>`**.
The following table shows what the permissions look like from the Entra ID portal:
| Permissions name | Type | Admin consent required | Status |
| ---------------------- | ----------- | ---------------------- | ------- |
| `GroupMember.Read.All` | Application | Yes | Granted |
| `User.Read` | Delegated | No | Granted |
| `User.Read.All` | Application | Yes | Granted |
{{< figure src="/media/docs/IAM/image.png" caption="Screen shot of the permissions listed in Entra ID for the App registration" >}}
To test that Graph API has the correct permissions, refer to the [Troubleshoot Graph API calls](../troubleshoot-saml/#troubleshoot-graph-api-calls) section.
docs/sources/setup-grafana/configure-access/configure-authentication/saml/configure-saml-with-okta/_index.md
+67
View File
@@ -0,0 +1,67 @@
---
aliases:
- ../../../configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/configure-saml-with-okta/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/configure-saml-with-okta/
- ../../../configure-security/configure-authentication/saml/configure-saml-with-okta/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/saml/configure-saml-with-okta/
description: Learn how to configure SAML authentication in Grafana's UI.
labels:
products:
- cloud
- enterprise
menuTitle: Configure SAML with Okta
title: Configure SAML authentication with Okta
weight: 580
---
# Configure SAML Okta
Grafana supports user authentication through Okta, which is useful when you want your users to access Grafana using single sign on. This guide will follow you through the steps of configuring SAML authentication in Grafana with [Okta](https://okta.com/). You need to be an admin in your Okta organization to access Admin Console and create SAML integration. You also need permissions to edit Grafana configuration file and restart Grafana server.
## Before you begin
- To configure SAML integration with Okta, create an app integration inside the Okta organization first. [Add app integration in Okta](https://help.okta.com/en/prod/Content/Topics/Apps/apps-overview-add-apps.htm)
- Ensure you have permission to administer SAML authentication. For more information about roles and permissions in Grafana, refer to [Roles and permissions](/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/).
## Set up SAML with Okta
1. Log in to the [Okta portal](https://login.okta.com/).
1. Go to the Admin Console in your Okta organization by clicking **Admin** in the upper-right corner. If you are in the Developer Console, then click **Developer Console** in the upper-left corner and then click **Classic UI** to switch over to the Admin Console.
1. In the Admin Console, navigate to **Applications** > **Applications**.
1. Click **Create App Integration** to start the Application Integration Wizard.
1. Choose **SAML 2.0** as the **Sign-in method**.
1. Click **Create**.
1. On the **General Settings** tab, enter a name for your Grafana integration. You can also upload a logo.
1. On the **Configure SAML** tab, enter the SAML information related to your Grafana instance:
- In the **Single sign on URL** field, use the `/saml/acs` endpoint URL of your Grafana instance, for example, `https://grafana.example.com/saml/acs`.
- In the **Audience URI (SP Entity ID)** field, use the `/saml/metadata` endpoint URL, by default it is the `/saml/metadata` endpoint of your Grafana instance (for example `https://example.grafana.com/saml/metadata`). This could be configured differently, but the value here must match the `entity_id` setting of the SAML settings of Grafana.
- Leave the default values for **Name ID format** and **Application username**.
{{< admonition type="note" >}}
If you plan to enable SAML Single Logout, consider setting the **Name ID format** to `EmailAddress` or `Persistent`. This must match the `name_id_format` setting of the Grafana instance.
{{< /admonition >}}
- In the **ATTRIBUTE STATEMENTS (REQUIRED)** section, enter the SAML attributes to be shared with Grafana. The attribute names in Okta need to match exactly what is defined within Grafana, for example:
| Attribute name (in Grafana) | Name and value (in Okta profile) | Grafana configuration (under `auth.saml`) |
| --------------------------- | ---------------------------------------------------- | ----------------------------------------- |
| Login | Login - `user.login` | `assertion_attribute_login = Login` |
| Email | Email - `user.email` | `assertion_attribute_email = Email` |
| DisplayName | DisplayName - `user.firstName + " " + user.lastName` | `assertion_attribute_name = DisplayName` |
- In the **GROUP ATTRIBUTE STATEMENTS (OPTIONAL)** section, enter a group attribute name (for example, `Group`, ensure it matches the `asssertion_attribute_groups` setting in Grafana) and set filter to `Matches regex .*` to return all user groups.
1. Click **Next**.
1. On the final Feedback tab, fill out the form and then click **Finish**.
## Configure SAML assertions when using SCIM provisioning
In order to verify the logged in user is the same user that was provisioned through Okta, you need to include the same `externalId` in the SAML assertion by mapping the SAML assertion `assertion_attribute_external_id`.
1. Open your Okta application.
1. Select the SAML single sign-on configuration.
1. Edit the `Attributes & Claims` section.
1. Add a new claim with the following settings:
- Name: `userUID`
### Example configuration
| Attribute name (in Grafana) | Name and value (in Okta profile) | Grafana default configuration (under `auth.saml`) |
| --------------------------- | ------------------------------------------ | ------------------------------------------------- |
| userUID | userUID - `user.getInternalProperty("id")` | `assertion_attribute_login = userUID` |
docs/sources/setup-grafana/configure-access/configure-authentication/saml/configure-saml-with-okta/oin-application.md
+65
View File
@@ -0,0 +1,65 @@
---
aliases:
- ../../../../configure-security/configure-authentication/saml/setup-grafana/configure-security/configure-authentication/saml/configure-saml-org-mapping/configure-saml-with-okta/oin-application/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/saml/setup-grafana/configure-security/configure-authentication/saml/configure-saml-org-mapping/configure-saml-with-okta/oin-application/
- ../../../../configure-security/configure-authentication/saml/configure-saml-with-okta/oin-application/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/saml/configure-saml-with-okta/oin-application/
description: Learn how to configure SAML authentication with Okta using the Okta Integration Network (OIN) application.
labels:
products:
- cloud
- enterprise
menuTitle: Configure SAML with Okta catalog application
title: Configure SAML with Okta catalog application
weight: 590
---
# Configure SAML with Okta catalog application
Grafana offers multiple ways to configure the SAML authentication flow. This guide focuses on configuring the authentication flow using the Okta Integration Network (OIN) application.
The Grafana Labs application can be found in the [Okta Integration Network catalog](https://www.okta.com/integrations/).
## Prerequisites
- Grafana Enterprise or a paid Grafana Cloud account.
- Admin privileges in both Grafana and Okta.
## Supported features
- SAML Single Sign-On (SSO)
- SAML Attribute Mapping
- SAML Group Mapping
- SAML External ID Mapping for SCIM provisioning
## Configure SAML using the OIN application
### At the Okta Integration Network catalog
1. Visit the [Okta Integration Network catalog](https://www.okta.com/integrations/) and search for **Grafana Labs**.
1. Within the **Grafana Labs** application page, click on **+Add Integration**.
1. Select the tenant to add the integration to.
### At the Grafana Labs application page
1. If needed, update the **Application label**.
1. Set the domain name. For example, `your-grafana-domain.grafana.net`.
1. Click on **Done**.
| Field | Description |
| --------------------- | ---------------------------------------- |
| **Application label** | The name of the application. |
| **Domain name** | The domain name of the Grafana instance. |
### At the Grafana Labs Integration page
1. At the **Assignments** tab, add the groups or users that should have access to the application.
1. At the **Sign On** tab, copy the _Metadata URL_.
## Update SAML configuration at Grafana
### At the Grafana Labs SAML settings page
1. Navigate to the **SAML settings** page within the **Authentication** section from the left-hand menu.
1. The only required step is pasting the _Metadata URL_ in the **IdP Metadata URL** field, located at the **3. Connect Grafana with Identity Provider** tab.
1. Save and apply the changes.
With this configuration, the users will be able to access Grafana using their Okta credentials.
docs/sources/setup-grafana/configure-access/configure-authentication/saml/saml-configuration-options/_index.md
+112
View File
@@ -0,0 +1,112 @@
---
aliases:
- ../../../configure-access/configure-authentication/saml/saml-configuration-options/_index.md/ # /docs/grafana/next/setup-grafana/configure-access/configure-authentication/saml/saml-configuration-options/_index.md/
- ../../../configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/saml-configuration-options/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/saml-configuration-options/
- ../../../configure-security/configure-authentication/saml/saml-configuration-options/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/saml/saml-configuration-options/
labels:
products:
- cloud
- enterprise
menuTitle: SAML configuration options
title: SAML configuration options
weight: 520
---
# SAML configuration options
This page provides a comprehensive guide to configuring SAML authentication in Grafana. You'll find detailed configuration examples, available settings, and their descriptions to help you set up and customize SAML authentication for your Grafana instance.
The table below describes all SAML configuration options. Continue reading below for details on specific options. Like any other Grafana configuration, you can apply these options as [environment variables](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#override-configuration-with-environment-variables).
| Setting | Required | Description | Default |
| ---------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| `enabled` | No | Whether SAML authentication is allowed. | `false` |
| `name` | No | Name used to refer to the SAML authentication in the Grafana user interface. | `SAML` |
| `entity_id` | No | The entity ID of the service provider. This is the unique identifier of the service provider. | `https://{Grafana URL}/saml/metadata` |
| `single_logout` | No | Whether SAML Single Logout is enabled. | `false` |
| `allow_sign_up` | No | Whether to allow new Grafana user creation through SAML login. If set to `false`, then only existing Grafana users can log in with SAML. | `true` |
| `auto_login` | No | Whether SAML auto login is enabled. | `false` |
| `allow_idp_initiated` | No | Whether SAML IdP-initiated login is allowed. | `false` |
| `certificate` or `certificate_path` | Yes | Base64-encoded string or Path for the SP X.509 certificate. | |
| `private_key` or `private_key_path` | Yes | Base64-encoded string or Path for the SP private key. | |
| `signature_algorithm` | No | Signature algorithm used for signing requests to the IdP. Supported values are rsa-sha1, rsa-sha256, rsa-sha512. | |
| `idp_metadata`, `idp_metadata_path`, or `idp_metadata_url` | Yes | Base64-encoded string, Path or URL for the IdP SAML metadata XML. | |
| `max_issue_delay` | No | Maximum time allowed between the issuance of an AuthnRequest by the SP and the processing of the Response. | `90s` |
| `metadata_valid_duration` | No | Duration for which the SP metadata remains valid. | `48h` |
| `relay_state` | No | Relay state for IdP-initiated login. This should match the relay state configured in the IdP. | |
| `assertion_attribute_name` | No | Friendly name or name of the attribute within the SAML assertion to use as the user name. Alternatively, this can be a template with variables that match the names of attributes within the SAML assertion. | `displayName` |
| `assertion_attribute_login` | No | Friendly name or name of the attribute within the SAML assertion to use as the user login handle. | `mail` |
| `assertion_attribute_email` | No | Friendly name or name of the attribute within the SAML assertion to use as the user email. | `mail` |
| `assertion_attribute_groups` | No | Friendly name or name of the attribute within the SAML assertion to use as the user groups. | |
| `assertion_attribute_role` | No | Friendly name or name of the attribute within the SAML assertion to use as the user roles. | |
| `assertion_attribute_org` | No | Friendly name or name of the attribute within the SAML assertion to use as the user organization | |
| `assertion_attribute_external_uid` | No | Friendly name or name of the attribute within the SAML assertion to use as the user external UID. | `userUID` |
| `allowed_organizations` | No | List of comma- or space-separated organizations. User should be a member of at least one organization to log in. | |
| `org_mapping` | No | List of comma- or space-separated Organization:OrgId:Role mappings. Organization can be `*` meaning "All users". Role is optional and can have the following values: `None`, `Viewer`, `Editor` or `Admin`. | |
| `role_values_none` | No | List of comma- or space-separated roles which will be mapped into the None role. | |
| `role_values_viewer` | No | List of comma- or space-separated roles which will be mapped into the Viewer role. | |
| `role_values_editor` | No | List of comma- or space-separated roles which will be mapped into the Editor role. | |
| `role_values_admin` | No | List of comma- or space-separated roles which will be mapped into the Admin role. | |
| `role_values_grafana_admin` | No | List of comma- or space-separated roles which will be mapped into the Grafana Admin (Super Admin) role. | |
| `skip_org_role_sync` | No | Whether to skip organization role synchronization. | `false` |
| `name_id_format` | No | Specifies the format of the requested NameID element in the SAML AuthnRequest. | `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` |
| `client_id` | No | Client ID of the IdP service application used to retrieve more information about the user from the IdP. (Microsoft Entra ID only) | |
| `client_secret` | No | Client secret of the IdP service application used to retrieve more information about the user from the IdP. (Microsoft Entra ID only) | |
| `token_url` | No | URL to retrieve the access token from the IdP. (Microsoft Entra ID only) | |
| `force_use_graph_api` | No | Whether to use the IdP service application retrieve more information about the user from the IdP. (Microsoft Entra ID only) | `false` |
## Example SAML configuration
```ini
[auth.saml]
enabled = true
auto_login = false
certificate_path = "/path/to/certificate.cert"
private_key_path = "/path/to/private_key.pem"
idp_metadata_path = "/my/metadata.xml"
max_issue_delay = 90s
metadata_valid_duration = 48h
assertion_attribute_name = displayName
assertion_attribute_login = mail
assertion_attribute_email = mail
assertion_attribute_groups = Group
assertion_attribute_role = Role
assertion_attribute_org = Org
role_values_viewer = external
role_values_editor = editor, developer
role_values_admin = admin, operator
role_values_grafana_admin = superadmin
org_mapping = Engineering:2:Editor, Engineering:3:Viewer, Sales:3:Editor, *:1:Editor
allowed_organizations = Engineering, Sales
```
## Example SAML configuration in Terraform
```terraform
resource "grafana_sso_settings" "saml_sso_settings" {
provider_name = "saml"
saml_settings {
name = "SAML"
auto_login = false
certificate_path = "/path/to/certificate.cert"
private_key_path = "/path/to/private_key.pem"
idp_metadata_path = "/my/metadata.xml"
max_issue_delay = "90s"
metadata_valid_duration = "48h"
assertion_attribute_name = "displayName"
assertion_attribute_login = "mail"
assertion_attribute_email = "mail"
assertion_attribute_groups = "Group"
assertion_attribute_role = "Role"
assertion_attribute_org = "Org"
role_values_editor = "editor, developer"
role_values_admin = "admin, operator"
role_values_grafana_admin = "superadmin"
org_mapping = "Engineering:2:Editor, Engineering:3:Viewer, Sales:3:Editor, *:1:Editor"
allowed_organizations = "Engineering, Sales"
}
}
```
Go to [Terraform Registry](https://registry.terraform.io/providers/grafana/grafana/<GRAFANA_VERSION>/docs/resources/sso_settings) for a complete reference on using the `grafana_sso_settings` resource.
docs/sources/setup-grafana/configure-access/configure-authentication/saml/saml-ui/_index.md
+155
View File
@@ -0,0 +1,155 @@
---
aliases:
- ../../../configure-security/configure-authentication/saml-ui/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/saml-ui/
- ../saml-ui/ # /docs/grafana/latest/setup-grafana/configure-access/configure-authentication/saml-ui/
- ../../../configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/saml-ui/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/saml-ui/
- ../../../configure-security/configure-authentication/saml/saml-ui/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/saml/saml-ui/
description: Learn how to configure SAML authentication in Grafana's UI.
labels:
products:
- cloud
- enterprise
menuTitle: SAML user interface
title: Configure SAML authentication using the Grafana user interface
weight: 510
---
# Configure SAML authentication using the Grafana user interface
{{< admonition type="note" >}}
Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) version 10.0 and later, and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
You can configure SAML authentication in Grafana through the user interface (UI) or the Grafana configuration file. For instructions on how to set up SAML using the Grafana configuration file, refer to [Configure SAML authentication using the configuration file](../#configure-saml-using-the-grafana-config-file).
The Grafana SAML UI provides the following advantages over configuring SAML in the Grafana configuration file:
- It is accessible by Grafana Cloud users
- SAML UI carries out input validation and provides useful feedback on the correctness of the configuration, making SAML setup easier
- It doesn't require Grafana to be restarted after a configuration update
- Access to the SAML UI only requires access to authentication settings, so it can be used by users with limited access to Grafana's configuration
{{< admonition type="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. This means that 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. For more information on how Grafana determines the order of precedence for its settings, please refer to the [SSO Settings API](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/developers/http_api/sso-settings/).
{{< /admonition >}}
## Before you begin
To follow this guide, you need:
- Knowledge of SAML authentication. Refer to [SAML authentication in Grafana](../) for an overview of the SAML integration in Grafana.
- Permissions `settings:read` and `settings:write` with scope `settings:auth.saml:*` that allow you to read and update SAML authentication settings.
These permissions are granted by `fixed:authentication.config:writer` role.
By default, this role is granted to Grafana server administrator in self-hosted instances and to Organization admins in Grafana Cloud instances.
- Grafana instance running Grafana version 10.0 or later with [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
## Steps To Configure SAML Authentication
Sign in to Grafana and navigate to **Administration > Authentication > Configure SAML**.
### 1. General Settings Section
1. Complete the **General settings** fields.
For assistance, consult the following table for additional guidance about certain fields:
| Field | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Allow signup** | If enabled, you can create new users through the SAML login. If disabled, then only existing Grafana users can log in with SAML. |
| **Auto login** | If enabled, Grafana will attempt to automatically log in with SAML skipping the login screen. |
| **Single logout** | The SAML single logout feature enables users to log out from all applications associated with the current IdP session established using SAML SSO. For more information, refer to [SAML single logout documentation](../configure-saml-single-logout). |
| **Identity provider initiated login** | Enables users to log in to Grafana directly from the SAML IdP. For more information, refer to [IdP initiated login documentation](../#idp-initiated-single-sign-on-sso). |
1. Click **Next: Sign requests**.
### 2. Sign Requests Section
1. In the **Sign requests** field, specify whether you want the outgoing requests to be signed, and, if so, then:
1. Provide a certificate and a private key that will be used by the service provider (Grafana) and the SAML IdP.
Use the [PKCS #8](https://en.wikipedia.org/wiki/PKCS_8) format to issue the private key.
For more information, refer to an [example on how to generate SAML credentials](../configure-saml-signing-encryption/#example-of-private-key-generation-for-saml-authentication).
Alternatively, you can generate a new private key and certificate pair directly from the UI. Click on the `Generate key and certificate` button to open a form where you enter some information you want to be embedded into the new certificate.
1. Choose which signature algorithm should be used.
The SAML standard recommends using a digital signature for some types of messages, like authentication or logout requests to avoid [man-in-the-middle attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack).
1. Click **Next: Connect Grafana with Identity Provider**.
### 3. Connect Grafana with Identity Provider Section
1. Configure IdP using Grafana Metadata
1. Copy the **Metadata URL** and provide it to your SAML IdP to establish a connection between Grafana and the IdP.
- The metadata URL contains all the necessary information for the IdP to establish a connection with Grafana.
1. Copy the **Assertion Consumer Service URL** and provide it to your SAML IdP.
- The Assertion Consumer Service URL is the endpoint where the IdP sends the SAML assertion after the user has been authenticated.
1. If you want to use the **Single Logout** feature, copy the **Single Logout Service URL** and provide it to your SAML IdP.
1. Finish configuring Grafana using IdP data
1. Provide IdP Metadata to Grafana.
- The metadata contains all the necessary information for Grafana to establish a connection with the IdP.
- This can be provided as Base64-encoded value, a path to a file, or as a URL.
1. Click **Next: User mapping**.
### 4. User Mapping Section
1. If you wish to [map user information from SAML assertions](../#assertion-mapping), complete the **Assertion attributes mappings** section.
If Azure is the Identity Provider over SAML there are caveats for the assertion attribute mappings. Due to how Azure interprets these attributes the full URL will need to be entered in the corresponding fields within the UI, which should match the URLs from the metadata XML. There are differences depending on whether it's a Role or Group claim vs other assertions which Microsoft has [documented](https://learn.microsoft.com/en-us/entra/identity-platform/reference-claims-customization#table-2-saml-restricted-claim-set).
Group and Role:
```
http://schemas.microsoft.com/ws/2008/06/identity/claims/role
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
http://schemas.microsoft.com/identity/claims/displayname
```
Other Assertions:
```
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
```
![image](https://github.com/user-attachments/assets/23910ab8-20ec-4dfd-8ef6-7dbaec51ac90)
You also need to configure the **Groups attribute** field if you want to use team sync. Team sync automatically maps users to Grafana teams based on their SAML group membership.
Learn more about [team sync](../../../configure-team-sync) and [configuring team sync for SAML](../configure-saml-team-role-mapping/#configure-team-sync).
1. If you want to automatically assign users' roles based on their SAML roles, complete the **Role mapping** section.
First, you need to configure the **Role attribute** field to specify which SAML attribute should be used to retrieve SAML role information.
Then enter the SAML roles that you want to map to Grafana roles in **Role mapping** section. If you want to map multiple SAML roles to a Grafana role, separate them by a comma and a space. For example, `Editor: editor, developer`.
Role mapping will automatically update user's [basic role](../../../../../administration/roles-and-permissions/access-control/#basic-roles) based on their SAML roles every time the user logs in to Grafana.
Learn more about [SAML role synchronization](../configure-saml-team-role-mapping/#configure-role-sync).
1. If you're setting up Grafana with Entra ID using the SAML protocol and want to fetch user groups from the Graph API, complete the **Entra ID Service Account Configuration** subsection.
1. Set up a service account in Entra ID and provide the necessary details in the **Entra ID Service Account Configuration** section.
1. Provide the **Client ID** of your Entra ID application.
1. Provide the **Client Secret** of your Entra ID application, the **Client Secret** will be used to request an access token from Entra ID.
1. Provide the Entra ID request **Access Token URL**.
1. If you don't have users with more than 150 groups, you can still force the use of the Graph API by enabling the **Force use Graph API** toggle.
1. If you have multiple organizations and want to automatically add users to organizations, complete the **Org mapping section**.
First, you need to configure the **Org attribute** field to specify which SAML attribute should be used to retrieve SAML organization information.
Now fill in the **Org mapping** field with mappings from SAML organization to Grafana organization. For example, `Org mapping: Engineering:2, Sales:2` will map users who belong to `Engineering` or `Sales` organizations in SAML to Grafana organization with ID 2.
If you want users to have different roles in different organizations, you can additionally specify a role. For example, `Org mapping: Engineering:2:Editor` will map users who belong to `Engineering` organizations in SAML to Grafana organization with ID 2 and assign them Editor role.
Organization mapping will automatically update user's organization memberships (and roles, if they have been configured) based on their SAML organization every time the user logs in to Grafana.
Learn more about [SAML organization mapping](../configure-saml-org-mapping/).
1. If you want to limit the access to Grafana based on user's SAML organization membership, fill in the **Allowed organizations** field.
1. Click **Next: Test and enable**.
### 5. Test And Enable Section
1. Click **Save and enable**
- If there are issues with your configuration, an error message will appear. Refer back to the previous steps to correct the issues and click on `Save and apply` on the top right corner once you are done.
1. If there are no configuration issues, SAML integration status will change to `Enabled`.
Your SAML configuration is now enabled.
1. To disable SAML integration, click `Disable` in the top right corner.
docs/sources/setup-grafana/configure-access/configure-authentication/saml/troubleshoot-saml/_index.md
+159
View File
@@ -0,0 +1,159 @@
---
aliases:
- ../../../configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/troublsehoot-saml/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/setup-grafana/configure-security/configure-authentication/saml/troublsehoot-saml/
- ../../../configure-security/configure-authentication/saml/troubleshoot-saml/ # /docs/grafana/next/setup-grafana/configure-security/configure-authentication/saml/troubleshoot-saml/
description: Learn how to configure SAML authentication in Grafana's UI.
labels:
products:
- cloud
- enterprise
menuTitle: Troubleshooting
title: Troubleshoot SAML configuration
weight: 590
---
## Troubleshooting
Following are common issues found in configuring SAML authentication in Grafana and how to resolve them.
### Troubleshoot SAML authentication in Grafana
To troubleshoot and get more log information, enable SAML debug logging in the configuration file. Refer to [Configuration](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#filters) for more information.
```ini
[log]
filters = saml.auth:debug
```
### Infinite redirect loop / User gets redirected to the login page after successful login on the IdP side
If you experience an infinite redirect loop when `auto_login = true` or redirected to the login page after successful login, it is likely that the `grafana_session` cookie's SameSite setting is set to `Strict`. This setting prevents the `grafana_session` cookie from being sent to Grafana during cross-site requests. To resolve this issue, set the `security.cookie_samesite` option to `Lax` in the Grafana configuration file.
### SAML authentication fails with error:
- `asn1: structure error: tags don't match`
We only support one private key format: PKCS#8.
The keys may be in a different format (PKCS#1 or PKCS#12); in that case, it may be necessary to convert the private key format.
The following command creates a pkcs8 key file.
```bash
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
```
#### **Convert** the private key format to base64
The following command converts keys to base64 format.
Base64-encode the cert.pem and key.pem files:
(-w0 switch is not needed on Mac, only for Linux)
```sh
$ base64 -w0 key.pem > key.pem.base64
$ base64 -w0 cert.pem > cert.pem.base64
```
The base64-encoded values (`key.pem.base64, cert.pem.base64` files) are then used for certificate and `private_key`.
The keys you provide should look like:
```
-----BEGIN PRIVATE KEY-----
...
...
-----END PRIVATE KEY-----
```
### SAML login attempts fail with request response `origin not allowed`
When the user logs in using SAML and gets presented with `origin not allowed`, the user might be issuing the login from an IdP (identity provider) service or the user is behind a reverse proxy. This potentially happens as the CSRF checks in Grafana deem the requests to be invalid. For more information [CSRF](https://owasp.org/www-community/attacks/csrf).
To solve this issue, you can configure either the [`csrf_trusted_origins`](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#csrf_trusted_origins) or [`csrf_additional_headers`](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#csrf_additional_headers) option in the SAML configuration.
Example of a configuration file:
```ini
# config.ini
...
[security]
csrf_trusted_origins = https://grafana.example.com
csrf_additional_headers = X-Forwarded-Host
...
```
### SAML login attempts fail with request response "login session has expired"
Accessing the Grafana login page from a URL that is not the root URL of the
Grafana server can cause the instance to return the following error: "login session has expired".
If you are accessing Grafana through a proxy server, ensure that cookies are correctly
rewritten to the root URL of Grafana.
Cookies must be set on the same URL as the `root_url` of Grafana. This is normally the reverse proxy's domain/address.
Review the cookie settings in your proxy server configuration to ensure that cookies are
not being discarded
Review the following settings in your Grafana configuration:
```ini
[security]
cookie_samesite = lax
```
This setting should be set to `lax` to allow Grafana session cookies to work correctly with redirects.
```ini
[security]
cookie_secure = true
```
For enhanced security, set `cookie_secure` to `true`, which forces cookies to be sent only via HTTPS.
### Troubleshoot Graph API calls
When setting up SAML authentication with Entra ID, you may encounter issues with Graph API calls. This can happen if the Entra ID application is not properly configured to allow Graph API access.
To help in the troubleshooting process, test the Graph API calls using the following commands:
```bash
curl -X POST "{token_url}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&scope=https://graph.microsoft.com/.default"
```
Where the following values come from your [SAML configuration](../saml-configuration-options/_index.md#saml-configuration-options):
- `token_url`: The token URL of your Entra ID application.
- `client_id`: The client ID of your Entra ID application.
- `client_secret`: The client secret of your Entra ID application.
The response should look like:
```json
{
"access_token": "...ACCESS_TOKEN...",
"token_type": "Bearer",
"expires_in": 3600
}
```
Use the `access_token` to test the Graph API calls.
```bash
curl -X GET "https://graph.microsoft.com/v1.0/groups" \
-H "Authorization: Bearer ${access_token}" \
-H "Content-Type: application/json"
```
The response should look like:
```json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(Edm.String)",
"value": ["29f2e7c8-9b9d-443c-bc62-7d8cdcfcfe59", "f0224e82-0eb8-4eda-8979-0c36e98deb00"]
}
```
If the second call fails due to 401 or 403, you may need to check the Entra ID application settings to ensure that Graph API access is enabled.
docs/sources/setup-grafana/configure-access/configure-scim-provisioning/_index.md
+201
View File
@@ -0,0 +1,201 @@
---
aliases:
- ../setup-grafana/configure-security/configure-scim-provisioning/ # /docs/grafana/next/setup-grafana/setup-grafana/configure-security/configure-scim-provisioning/
- ../configure-security/configure-scim-provisioning/ # /docs/grafana/next/setup-grafana/configure-security/configure-scim-provisioning/
description: Learn how to use SCIM provisioning to synchronize users and groups from your identity provider to Grafana. SCIM enables automated user management, team provisioning, and enhanced security through real-time synchronization with your identity provider.
keywords:
- grafana
- scim
- provisioning
- user-management
- team-management
labels:
products:
- cloud
- enterprise
menuTitle: Configure SCIM provisioning
title: Configure SCIM provisioning
weight: 200
---
# Configure SCIM provisioning
System for Cross-domain Identity Management (SCIM) is an open standard that allows automated user provisioning and management. With SCIM, you can automate the provisioning of users and groups from your identity provider to Grafana.
{{< admonition type="note" >}}
Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and select Grafana Cloud plans in [public preview](https://grafana.com/docs/release-life-cycle/).
Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.
This feature is behind the `enableSCIM` feature toggle.
You can enable feature toggles through configuration file or environment variables.
For more information, refer to the [feature toggles documentation](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#feature_toggles).
{{< /admonition >}}
{{< admonition type="warning" >}}
**Public Preview:** SCIM provisioning is currently in Public Preview. While functional, the feature is actively being refined and may undergo changes. We recommend thorough testing in non-production environments before deploying to production systems.
{{< /admonition >}}
## Benefits
{{< admonition type="note" >}}
SCIM provisioning only works with SAML authentication.
Other authentication methods aren't supported.
{{< /admonition >}}
SCIM offers several advantages for managing users and teams in Grafana:
- **Automated user provisioning**: Automatically create, update, and disable users in Grafana when changes occur in your identity provider
- **Automated team lifecycle management**: Automatically create teams when new groups are added, update team memberships, and delete teams when groups are removed from your identity provider
- **Reduced administrative overhead**: Eliminate manual user management tasks and reduce the risk of human error
- **Enhanced security**: Automatically disable access when users leave your organization
## Authentication and access requirements
{{< admonition type="warning" title="Critical: Aligning SAML Identifier with SCIM externalId" >}}
When using SAML for authentication alongside SCIM provisioning, a critical security measure is to ensure proper alignment between the the SCIM user's `externalId` and the SAML user identifier. The unique identifier used for SCIM provisioning (which becomes the `externalId` in Grafana, often sourced from a stable IdP attribute like Entra ID's `user.objectid`) **must also be sent as a claim in the SAML assertion from your Identity Provider.**
Furthermore, the Grafana SAML configuration must be correctly set up to identify and use this specific claim for linking the authenticated SAML user to their SCIM-provisioned user. This can be achieved by either ensuring the primary SAML login identifier by using the `assertion_attribute_external_uid` setting in Grafana to explicitly set the name of the SAML claim that contains the stable unique identifier attribute.
**Why is this important?**
A mismatch or inconsistent mapping between this SAML login identifier and the SCIM `externalId` creates a critical security vulnerability. If these two identifiers are not reliably and uniquely aligned for each individual user, Grafana may fail to correctly link an authenticated SAML session to the intended SCIM-provisioned user profile and its associated permissions. This can enable a malicious actor to impersonate another user—for instance, by crafting a SAML assertion that, due to the identifier misalignment, incorrectly grants them the access rights of the targeted user.
Grafana relies on this linkage to correctly associate the authenticated user from SAML with the provisioned user from SCIM. Failure to ensure a consistent and unique identifier across both systems can break this linkage, leading to incorrect user mapping and potential unauthorized access.
Always verify that your SAML identity provider is configured to send a stable, unique user identifier that your SCIM configuration maps to `externalId`. Refer to your identity provider's documentation and the specific Grafana SCIM integration guides (e.g., for [Entra ID](configure-scim-with-azuread/) or [Okta](configure-scim-with-okta/)) for detailed instructions on configuring these attributes correctly.
{{< /admonition >}}
When you enable SCIM in Grafana, the following requirements and restrictions apply:
1. **Use the same identity provider for user provisioning and for authentication flow**: You must use the same identity provider for both authentication and user provisioning.
2. **Security restriction**: When using SAML, the login authentication flow requires the SAML assertion exchange between the Identity Provider and Grafana to include the `userUID` SAML assertion with the user's unique identifier at the Identity Provider.
- Configure `userUID` SAML assertion in [Entra ID](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/configure-saml-with-azuread/#configure-saml-assertions-when-using-scim-provisioning)
- Configure `userUID` SAML assertion in [Okta](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/configure-saml-with-okta/#configure-saml-assertions-when-using-scim-provisioning)
## Configure SCIM using the Grafana user interface
You can configure SCIM in Grafana using the Grafana user interface. To do this, navigate to **Administration > Authentication > SCIM**.
The Grafana SCIM UI provides the following advantages over configuring SCIM in the Grafana configuration file:
- It is accessible by Grafana Cloud users
- It doesn't require Grafana to be restarted after a configuration update
- Using the authentication settings permission allows us to restrict Grafana’s access scope rather than relying on an overly permissive role such as Admin.
{{< admonition type="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. This means that 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 >}}
### Configure SCIM settings
Sign in to Grafana and navigate to **Administration > Authentication > SCIM**. Here you can configure the following settings:
| Setting | Required | Description | Default |
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `Enable Group Sync` | No | Enable SCIM group provisioning. When enabled, Grafana will create, update, and delete teams based on SCIM requests from your identity provider. Cannot be enabled if Team Sync is enabled. | `false` |
| `Reject Non-Provisioned Users` | No | When enabled, prevents non-SCIM provisioned users from signing in. Cloud Portal users can always sign in regardless of this setting. | `false` |
| `Enable User Sync` | Yes | Enable SCIM user provisioning. When enabled, Grafana will create, update, and deactivate users based on SCIM requests from your identity provider. | `false` |
The SCIM UI also displays information that may help you configure SCIM in your identity provider, including stack domain, stack ID, and tenant URL.
### Next steps
After configuring SCIM in Grafana, configure your identity provider:
- [Configure SCIM with Okta](configure-scim-with-okta/)
- [Configure SCIM with Entra ID](configure-scim-with-azuread/)
## Configure SCIM using the configuration file
The table below describes all SCIM configuration options. Like any other Grafana configuration, you can apply these options as [environment variables](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#override-configuration-with-environment-variables).
| Setting | Required | Description | Default |
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `user_sync_enabled` | Yes | Enable SCIM user provisioning. When enabled, Grafana will create, update, and deactivate users based on SCIM requests from your identity provider. | `false` |
| `group_sync_enabled` | No | Enable SCIM group provisioning. When enabled, Grafana will create, update, and delete teams based on SCIM requests from your identity provider. Cannot be enabled if Team Sync is enabled. | `false` |
| `reject_non_provisioned_users` | No | When enabled, prevents non-SCIM provisioned users from signing in. Cloud Portal users can always sign in regardless of this setting. | `false` |
{{< admonition type="warning" >}}
**Team Sync Compatibility**:
- SCIM group sync (`group_sync_enabled = true`) and Team Sync cannot be enabled simultaneously
- You can use SCIM user sync (`user_sync_enabled = true`) alongside Team Sync
- For more details about migration and compatibility, see [SCIM vs Team Sync](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-scim-provisioning/manage-users-teams/#scim-vs-team-sync)
{{< /admonition >}}
### Example SCIM configuration
```ini
[auth.scim]
user_sync_enabled = true
group_sync_enabled = false
reject_non_provisioned_users = false
```
## Configure SCIM using Terraform
You can also configure SCIM provisioning in Grafana using the [Grafana Terraform provider](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/scim_config). This approach is particularly useful for infrastructure-as-code deployments and automated provisioning.
### Terraform SCIM configuration example
```hcl
resource "grafana_scim_config" "scim_config" {
user_sync_enabled = true
group_sync_enabled = false
reject_non_provisioned_users = false
}
```
### Terraform SCIM configuration options
The Terraform `grafana_scim_config` resource supports the same configuration options as the manual configuration:
| Setting | Required | Description | Default |
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `user_sync_enabled` | Yes | Enable SCIM user provisioning. When enabled, Grafana will create, update, and deactivate users based on SCIM requests from your identity provider. | `false` |
| `group_sync_enabled` | No | Enable SCIM group provisioning. When enabled, Grafana will create, update, and delete teams based on SCIM requests from your identity provider. Cannot be enabled if Team Sync is enabled. | `false` |
| `reject_non_provisioned_users` | No | When enabled, prevents non-SCIM provisioned users from signing in. Cloud Portal users can always sign in regardless of this setting. | `false` |
## Supported identity providers
The following identity providers are supported:
- [Entra ID](../configure-authentication/azuread/)
- [Okta](../configure-authentication/saml/)
## How it works
The synchronization process works as follows:
1. Configure SCIM in both your identity provider and Grafana
2. Your identity provider sends SCIM requests to the Grafana SCIM API endpoint
3. Grafana processes these requests to create, update, or deactivate users and teams, and synchronize team memberships
## Comparison with other sync methods
Grafana offers several methods for synchronizing users, teams, and roles.
The following table compares SCIM with other synchronization methods to help you understand the advantages:
| Sync Method | Users | Teams | Roles | Automation | Key Benefits | Limitations | On-Prem | Cloud |
| ------------------------------------------------------------------------------ | ----- | ----- | ----- | ---------- | ------------------------------------------------------------------------ | ------------------------------------------------------------ | ------- | ----- |
| SCIM | ✅ | ✅ | ⚠️ | Full | Complete user and team lifecycle management with automatic team creation | Requires SAML authentication; uses Role Sync for basic roles | ✅ | ✅ |
| [Team Sync](../configure-team-sync/) | ❌ | ⚠️ | ❌ | Partial | Syncs team memberships to existing teams | Requires manual team creation; no team lifecycle management | ✅ | ✅ |
| [Active LDAP Sync](../configure-authentication/enhanced-ldap/) | ✅ | ❌ | ❌ | Full | Background synchronization of LDAP users | Limited to LDAP environments | ✅ | ❌ |
| [Role Sync](../configure-authentication/saml#configure-role-sync) | ❌ | ❌ | ✅ | Full | Full automation of basic role assignment | Limited to basic roles only | ✅ | ✅ |
| [Org Mapping](../configure-authentication/saml#configure-organization-mapping) | ❌ | ❌ | ⚠️ | Full | Full automation of basic role assignment per organization | Limited to basic roles only; on-premises only | ⚠️ | ❌ |
### Key advantages
- **Comprehensive user and team automation**: SCIM provides full automation for user and team provisioning, while role management is handled separately through Role Sync
- **Dynamic team creation**: Teams are created automatically based on identity provider groups
- **Near real-time synchronization**: Changes in the identity provider are reflected based on the provider synchronization schedule
- **Enterprise-ready**: Designed for large organizations with complex user management needs
## Next steps
- [Manage users and teams with SCIM provisioning](manage-users-teams/)
- [Troubleshoot SCIM provisioning](troubleshooting/)
- [Configure SCIM with Entra ID](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/configure-scim-with-azuread/)
- [Configure SCIM with Okta](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/configure-scim-with-okta/)
docs/sources/setup-grafana/configure-access/configure-scim-provisioning/configure-scim-with-entraid/_index.md
+172
View File
@@ -0,0 +1,172 @@
---
aliases:
- ../../configure-access/configure-authentication/configure-scim-with-azuread/ # /docs/grafana/next/setup-grafana/configure-access/configure-authentication/configure-scim-with-azuread/
- ../../configure-security/setup-grafana/configure-security/configure-scim-provisioning/configure-scim-with-azuread/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-scim-provisioning/configure-scim-with-azuread/
- ../../configure-security/configure-scim-provisioning/configure-scim-with-azuread/ # /docs/grafana/next/setup-grafana/configure-security/configure-scim-provisioning/configure-scim-with-azuread/
- ../../configure-access/configure-scim-with-azuread/ # /docs/grafana/next/setup-grafana/configure-access/configure-scim-provisioning/configure-scim-with-azuread/
description: Learn how to configure SCIM provisioning with Entra ID in Grafana Enterprise. This guide provides step-by-step instructions for setting up automated user and team management, including enterprise application configuration, service account creation, attribute mapping, and provisioning settings to ensure seamless integration between Entra ID and Grafana.
keywords:
- grafana
- scim
- azure
- azure ad
- entra id
- provisioning
- user-management
- team-management
labels:
products:
- cloud
- enterprise
menuTitle: Configure SCIM with Entra ID
title: Configure SCIM with Entra ID
weight: 320
---
# Configure SCIM with Entra ID
{{< admonition type="note" >}}
Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
{{< admonition type="warning" >}}
**Public Preview:** SCIM provisioning is currently in Public Preview. While functional, the feature is actively being refined and may undergo changes. We recommend thorough testing in non-production environments before deploying to production systems.
{{< /admonition >}}
This guide explains how to configure SCIM provisioning with Entra ID to automate user and team management in Grafana.
{{< admonition type="note" >}}
This feature is behind the `enableSCIM` feature toggle.
You can enable feature toggles through configuration file or environment variables.
For more information, refer to the [feature toggles documentation](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#feature_toggles).
{{< /admonition >}}
{{< admonition type="note" >}}
**Important SAML and SCIM Configuration:**
When using SAML for authentication alongside SCIM provisioning with Entra ID, it is crucial to correctly align user identifiers.
For detailed information on why this is critical for security and how to configure it, refer to the main [SCIM provisioning documentation](../).
Refer to the [SAML authentication with Entra ID documentation](../../configure-authentication/saml/configure-saml-with-azuread/) for specific instructions on how to configure SAML claims and Grafana SAML settings for your Entra ID SCIM setup.
{{< /admonition >}}
## Prerequisites
Before configuring SCIM with Entra ID, ensure you have:
- Grafana Enterprise or a paid Grafana Cloud account with SCIM provisioning enabled.
- Admin access to both Grafana and Entra ID
- SCIM feature enabled in Grafana
## Configure SCIM in Grafana
To enable SCIM provisioning in Grafana, create a service account and generate a service account token that will be used to authenticate SCIM requests from Entra ID.
### Create a service account
1. Navigate to **Administration > Users and access > Service accounts**
2. Click **Add service account**
3. Create a new service account with **Role: "None"**
4. In the service account **Permissions** tab, add these permissions:
**Allow the service account to sync users:**
- `org.users:read`
- `org.users:write`
- `org.users:add`
- `org.users:remove`
**Allow the service account to sync groups:**
- `teams:read`
- `teams:create`
- `teams:write`
- `teams:delete`
5. Create a new token for the newly created service account and save it securely
- This token will be used in the Entra ID configuration
## Configure SCIM in Entra ID
Configure the enterprise application in Entra ID to enable automated user and team synchronization with Grafana. This involves creating a new application and setting up both authentication and provisioning.
### Create the enterprise application
1. Open Azure Portal Entra ID (Entra ID)
2. Click **+ Add** dropdown
3. Click **Add Enterprise Application**
4. Click **+ Create Your Own Application**
5. Name the application and select **non-gallery**
### Configure provisioning
1. In the application overview, select **Provisioning**
2. Click **+ New Configuration**
3. Configure the following settings:
- **Tenant URL:**
You can copy the tenant URL directly from the SCIM UI at **Administration > Authentication > SCIM**. Your stack domain and stack ID can also be found in the SCIM UI.
Alternatively, you can construct the URL manually:
- For Grafana Cloud instances:
```
https://{stack-name}.grafana.net/apis/scim.grafana.app/v0alpha1/namespaces/stacks-{stack-id}
```
Replace `{stack-name}` and `{stack-id}` with your Grafana Cloud stack name and ID.
- For self-hosted instances:
```
https://{your-grafana-domain}/apis/scim.grafana.app/v0alpha1/namespaces/default
```
Replace `{your-grafana-domain}` with your Grafana instance's domain (e.g., `grafana.yourcompany.com`).
- **Secret Token:** Enter the service account token from Grafana
4. Click **Test connection** to verify the configuration
5. Click **Create** to save the settings
### Configure attribute mappings
After setting the Tenant URL and Secret Token, navigate to the **Mappings** section within the same **Provisioning** settings in your Entra ID enterprise application and then click **Provision Microsoft Entra ID Users**. This is where you will define how Entra ID attributes correspond to the SCIM attributes for Grafana, including the mandatory `externalId`.
{{< admonition type="note" >}}
- Only work email addresses are supported. Entra ID must be configured to use `emails[type eq "work"].value` for email mapping.
- The `externalId` attribute in Grafana is mandatory. Entra ID uses this to uniquely identify users and groups. You must map an attribute from Entra ID to the `externalId` attribute in Grafana. This Entra ID attribute must be **a stable and a unique identifier for each individual user** (for example, the `objectId` attribute in Entra ID is commonly used for this purpose).
{{< /admonition >}}
Configure the following required attributes:
| Entra ID Attribute | Grafana Attribute |
| ------------------------------------------------------------- | ------------------------------ |
| `userPrincipalName` | `userName` |
| `mail` | `emails[type eq "work"].value` |
| `displayName` | `displayName` |
| `objectId` | `externalId` |
| `Switch([IsSoftDeleted], , "False", "True", "True", "False")` | `active` |
{{< admonition type="note" >}}
During provisioning, if the identity provider sends user attributes that has no use in Grafana, those attributes will be gracefully ignored.
{{< /admonition >}}
### Enable provisioning
Click **Start provisioning** from the top action bar in the **Overview** page from your Entra ID enterprise application.
### Configure group provisioning
To enable group synchronization:
1. Navigate to the **Groups** tab in provisioning
2. Enable **Group provisioning**
3. Select the groups to synchronize with Grafana
4. Save the changes
## Test the integration
After completing the configuration:
1. Test the SCIM connector in Entra ID
2. Assign a test user to the application
3. Verify the user is provisioned in Grafana
4. Test group synchronization if configured
docs/sources/setup-grafana/configure-access/configure-scim-provisioning/configure-scim-with-okta/_index.md
+138
View File
@@ -0,0 +1,138 @@
---
aliases:
- ../../configure-access/configure-authentication/configure-scim-with-okta/ # /docs/grafana/next/setup-grafana/configure-access/configure-authentication/configure-scim-with-okta/
- ../../configure-security/setup-grafana/configure-security/configure-scim-provisioning/configure-scim-with-okta/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-scim-provisioning/configure-scim-with-okta/
- ../../configure-security/configure-scim-provisioning/configure-scim-with-okta/ # /docs/grafana/next/setup-grafana/configure-security/configure-scim-provisioning/configure-scim-with-okta/
description: Learn how to configure SCIM provisioning with Okta in Grafana. This guide provides step-by-step instructions for setting up automated user and team management, including SAML configuration, service account creation, attribute mapping, and provisioning settings to ensure seamless integration between Okta and Grafana.
keywords:
- grafana
- scim
- okta
- provisioning
- user-management
- team-management
labels:
products:
- cloud
- enterprise
menuTitle: Configure SCIM with Okta
title: Configure SCIM with Okta
weight: 320
---
# Configure SCIM with Okta
{{< admonition type="note" >}}
Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
{{< admonition type="warning" >}}
**Public Preview:** SCIM provisioning is currently in Public Preview. While functional, the feature is actively being refined and may undergo changes. We recommend thorough testing in non-production environments before deploying to production systems.
{{< /admonition >}}
This guide explains how to configure SCIM provisioning with Okta to automate user and team management in Grafana.
{{< admonition type="note" >}}
This feature is behind the `enableSCIM` feature toggle.
You can enable feature toggles through configuration file or environment variables.
For more information, refer to the [feature toggles documentation](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#feature_toggles).
{{< /admonition >}}
## Prerequisites
Before configuring SCIM with Okta, ensure you have:
- Grafana Enterprise or a paid Grafana Cloud account with SCIM provisioning enabled.
- Admin access to both Grafana and Okta
- [SAML authentication configured with Okta](../../configure-authentication/saml/configure-saml-with-okta/)
- SCIM feature enabled in Grafana
{{< admonition type="note" >}}
**Important SAML and SCIM Configuration:**
When using SAML for authentication alongside SCIM provisioning with Okta, it is crucial to correctly align user identifiers.
For detailed information on why this is critical for security and how to configure it, refer to the main [SCIM provisioning documentation](../).
Ensure your Okta SAML application is configured to send a stable, unique identifier (that will map to the Grafana SCIM `externalId`) as a SAML claim. Then, configure the Grafana SAML settings to use this claim. For general Okta SAML setup, refer to [Set up SAML with Okta](../../configure-authentication/saml/configure-saml-with-okta/).
{{< /admonition >}}
## Configure SCIM in Grafana
To enable SCIM provisioning in Grafana, create a service account and generate an access token that will be used to authenticate SCIM requests from Okta.
### Create a service account
1. Navigate to **Administration > Users and access > Service accounts**
2. Click **Add service account**
3. Create a new service account with **Role: "None"**
4. In the service account **Permissions** tab, add these permissions:
**Allow the service account to sync users:**
- `org.users:read`
- `org.users:write`
- `org.users:add`
- `org.users:remove`
**Allow the service account to sync groups:**
- `teams:read`
- `teams:create`
- `teams:write`
- `teams:delete`
5. Create a new token for the newly created service account and save it securely
- This token will be used in the Okta configuration
## Configure SCIM in Okta
Configure both SAML authentication and SCIM provisioning in Okta to enable automated user and team synchronization with Grafana. Start by creating a SAML application, then enable and configure SCIM provisioning for that application.
### Enable SCIM provisioning
1. Navigate to the **General** tab of your SAML App Integration in Okta
2. Enable SCIM provisioning
- A new provisioning tab will appear
### Configure provisioning settings
To enable user provisioning through SCIM, configure the SCIM integration settings in Grafana by specifying the connector URL, authentication mode, and supported provisioning actions. Follow these steps to complete the integration.
### Configure SCIM integration
In the **Integration** tab, configure:
- **SCIM Connector base URL:**
You can copy the complete SCIM Connector base URL directly from the SCIM UI at **Administration > Authentication > SCIM**. This is displayed as the Tenant URL in the UI. Your stack domain and stack ID can also be found in the SCIM UI.
Alternatively, you can construct the URL manually:
- For Grafana Cloud instances:
```
https://{stack-name}.grafana.net/apis/scim.grafana.app/v0alpha1/namespaces/stacks-{stack-id}
```
Replace `{stack-name}` and `{stack-id}` with your Grafana Cloud stack name and ID.
- For self-hosted instances:
```
https://{your-grafana-domain}/apis/scim.grafana.app/v0alpha1/namespaces/default
```
Replace `{your-grafana-domain}` with your Grafana instance's domain (e.g., `grafana.yourcompany.com`).
- **Unique identifier field:** userName
- **Supported provisioning actions:**
- Import New Users and Profile Updates
- Push New Users
- Push Profile Updates
- **Authentication Mode:** HTTP Header
- **Authorization:** Bearer {your-grafana-service-account-token}
- Click **Test Connector Configuration** and then save the configuration
In the **To App** tab, enable:
- Create Users
- Update User Attributes
- Deactivate Users
After completing the configuration:
1. Test the SCIM connector in Okta
2. Assign a test user to the application
3. Verify the user is provisioned in Grafana
docs/sources/setup-grafana/configure-access/configure-scim-provisioning/manage-users-teams/_index.md
+286
View File
@@ -0,0 +1,286 @@
---
aliases:
- ../../configure-security/setup-grafana/configure-security/configure-scim-provisioning/manage-users-teams/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-scim-provisioning/manage-users-teams/
- ../../configure-security/configure-scim-provisioning/manage-users-teams/ # /docs/grafana/next/setup-grafana/configure-security/configure-scim-provisioning/manage-users-teams/
description: Learn how to implement SCIM provisioning in Grafana for automated user and team synchronization. SCIM integrates with identity providers like Okta and Entra ID to streamline user management, automate team provisioning, and replace Team Sync.
keywords:
- grafana
- scim
- provisioning
- user-management
- team-management
labels:
products:
- cloud
- enterprise
menuTitle: Manage users and teams with SCIM
title: Manage users and teams with SCIM
weight: 310
---
# Manage users and teams with SCIM
{{< admonition type="note" >}}
Available in [Grafana Enterprise](/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and to customers on select Grafana Cloud plans. For pricing information, visit [pricing](https://grafana.com/pricing/) or contact our sales team.
{{< /admonition >}}
{{< admonition type="warning" >}}
**Public Preview:** SCIM provisioning is currently in Public Preview. While functional, the feature is actively being refined and may undergo changes. We recommend thorough testing in non-production environments before deploying to production systems.
{{< /admonition >}}
SCIM streamlines identity management in Grafana by automating user lifecycle and team membership operations. This guide explains how SCIM works with existing Grafana setups, handles user provisioning, and manages team synchronization.
With SCIM, you can:
- **Automate user lifecycle** from creation to deactivation
- **Manage existing users** by linking them with identity provider identities
- **Automate team lifecycle** by automatically creating teams when groups are added, updating team memberships, and deleting teams when groups are removed
- **Maintain security** through automated deprovisioning
- **Replace Team Sync** with more robust SCIM group synchronization
## User provisioning with SCIM
SCIM provisioning works in conjunction with existing user management methods in Grafana. While SCIM automates user provisioning from the identity provider, users can still be created through SAML just-in-time provisioning when they log in, manually through the Grafana UI, or via automation tools like Terraform and the Grafana API. For the most consistent user management experience, we recommend centralizing user provisioning through SCIM.
{{< admonition type="note" >}}
User provisioning requires `user_sync_enabled = true` in the SCIM configuration. See [Configure SCIM in Grafana](../../configure-scim-provisioning#configure-scim-in-grafana) for more information.
{{< /admonition >}}
{{< admonition type="warning" >}}
After a user is provisioned through SCIM, they cannot be deleted from Grafana - they can only be deactivated through the identity provider. This is important to consider when planning your user management strategy, especially for compliance and data retention requirements.
{{< /admonition >}}
For detailed configuration steps specific to the identity provider, see:
- [Configure SCIM with Entra ID](../configure-scim-with-azuread/)
- [Configure SCIM with Okta](../configure-scim-with-okta/)
### How SCIM identifies users
SCIM uses a specific process to establish and maintain user identity between the identity provider and Grafana:
1. **Initial user lookup:**
- The administrator configures SCIM at the Identity Provider, defining the **Unique identifier field**
- The identity provider looks up each user in Grafana using this unique identifier field as a filter
- The identity provider expects a single result from Grafana for each user
2. **Identity linking based on lookup results:**
- **If there's a single matching result:** The identity provider retrieves the user's unique ID at Grafana, saves it, confirms it can fetch the user's information, and updates the user's information in Grafana
- **If there are no matching results:** The identity provider attempts to create the user in Grafana. If successful, it retrieves and saves the user's unique ID for future operations. If a user with the same email address already exists in Grafana, the user is updated and will be managed by SCIM from that point forward.
- The identity provider learns the relationship between the found Grafana user and the Grafana internal ID
- The identity provider updates Grafana with the External ID
- Grafana updates the authentication validations to expect this External ID
3. **Matching the User During Login:**
When a user logs in via SAML, Grafana needs to securely match them to the correct user account provisioned by SCIM. This requires using a consistent, unique identifier across both processes (for example, the user's `objectId` in Entra ID).
- **Configure SAML Claims:** Set up your identity provider (e.g., Entra ID) to include this unique identifier in the information it sends during SAML login.
- **Configure Grafana SAML:** In the Grafana SAML settings, use the `assertion_attribute_login` setting to specify which incoming SAML attribute contains this unique identifier.
- **Configure SCIM Mapping:** To complete the link, ensure your SCIM attribute mapping in the identity provider sets the user's Grafana **externalId** attribute to be the _same_ unique identifier provided via SAML (for example, the user's `objectId` in Entra ID).
- See [SAML configuration details](../../configure-authentication/saml/#integrating-with-scim-provisioning) for specific configuration guidance.
This process ensures secure and consistent user identification across both systems, preventing security issues that could arise from email changes or other user attribute modifications.
{{< admonition type="note" >}}
During provisioning, if the identity provider sends user attributes that has no use in Grafana, those attributes will be gracefully ignored.
{{< /admonition >}}
### Existing Grafana users
For users who already exist in the Grafana instance:
- SCIM establishes the relationship through the External ID matching process
- Creates a secure link with the identity provider identity
- Preserves all existing settings and access
- Keeps the account active and unchanged until assigned in the identity provider
#### Handling users from other provisioning methods
To prevent conflicts and maintain consistent user management, disable or restrict other provisioning methods when implementing SCIM. This ensures that all new users are created through SCIM and prevents duplicate or conflicting user records.
- SAML Just-in-Time (JIT) provisioning:
- Disable `allow_sign_up` in SAML settings to prevent automatic user creation
- Existing JIT-provisioned users will continue to work but should be migrated to SCIM
- Terraform or API provisioning:
- Stop creating new users through these methods
- Existing users will continue to work but should be migrated to SCIM
- Consider removing or archiving Terraform user creation resources
- Manual user creation:
- Restrict UI-based user creation to administrators only
- Plan to migrate manually created users to SCIM
### New users
For users who don't yet exist in Grafana:
- SCIM creates accounts when users are assigned to Grafana in the identity provider
- Sets up initial access based on identity provider group memberships and SAML role mapping
- No manual Grafana account creation needed
### Role management
SCIM handles user synchronization but not role assignments. Role management is handled through [Role Sync](../../configure-authentication/saml#configure-role-sync), and any role changes take effect during user authentication.
## Migrating existing users to SCIM provisioning
If you have an existing Grafana instance with manually created users and want to migrate to IDP-based SCIM provisioning, you can leverage the SCIM identification mechanism to seamlessly link existing users with their IDP identities.
### Migration overview
The migration process uses the same [user identification mechanism](#how-scim-identifies-users) described earlier, but focuses on linking existing Grafana users with their corresponding IDP identities rather than creating new users.
**Key benefits of this approach:**
- Preserves all existing user settings, dashboards, and permissions
- No disruption to user access during migration
- Gradual migration possible (users can be migrated in batches)
- Maintains audit trails and historical data
### Migration steps
1. **Prepare the identity provider:**
- Ensure all existing Grafana users have corresponding accounts in your IDP
- Verify that the unique identifier field (e.g., email, username, or object ID) matches between systems
- Configure SCIM application in your IDP but don't assign users yet
2. **Configure SCIM in Grafana:**
- Set up SCIM endpoint and authentication as described in [Configure SCIM in Grafana](../../configure-scim-provisioning#configure-scim-in-grafana)
- Enable `user_sync_enabled = true`
- Configure the unique identifier field to match your IDP setup
{{< admonition type="note" >}}
To restrict login access to only SCIM-provisioned users, enable the `[auth.scim][reject_non_provisioned_users]` option. Cloud Portal users can always sign in regardless of this setting.
```ini
[auth.scim]
reject_non_provisioned_users = true
```
{{< /admonition >}}
3. **Test the matching mechanism:**
- Use the SCIM API to verify that existing users can be found using the unique identifier:
```bash
curl --location 'https://{$GRAFANA_URL}/apis/scim.grafana.app/v0alpha1/namespaces/{$STACK_ID}/Users?filter=userName eq "existing.user@company.com"' \
--header 'Authorization: Bearer glsa_xxxxxxxxxxxxxxxxxxxxxxxx'
```
- This should return exactly one user record for each existing user
4. **Assign users in the IDP:**
- Begin assigning existing users to the Grafana application in your IDP
- The SCIM identification process will automatically link existing Grafana users with their IDP identities
- Monitor the process for any conflicts or errors
5. **Verify the migration:**
- Check that users can still access Grafana with their existing permissions
- Verify that SAML/SSO login works correctly for migrated users
- Ensure External ID is properly set for each migrated user
### Migration considerations
**Before migration:**
- **Backup your Grafana database** - Always have a recovery plan
- **Audit existing users** - Document current user accounts and their access levels
- **Plan for exceptions** - Some users might need manual intervention if unique identifiers don't match
**During migration:**
- **Monitor logs** - Watch for SCIM errors or conflicts during the linking process in Grafana and your Identity Provider
- **Batch processing** - Consider migrating users in small batches to identify issues early
- **Communication** - Inform users about the migration timeline and any required actions
**After migration:**
- **Disable manual provisioning** - Prevent new users from being created outside of SCIM
- **Update documentation** - Ensure team procedures reflect the new IDP-based workflow
- **Regular audits** - Periodically verify that IDP and Grafana users remain in sync
### Troubleshooting migration issues
**Multiple users found for unique identifier:**
- Review your unique identifier field configuration
- Check for duplicate accounts in Grafana or the IDP
- Consider using a more specific identifier (e.g., object ID instead of email)
**User not found during lookup:**
- Verify the unique identifier value matches exactly between systems
- Check that the user exists in both Grafana and the IDP
**Authentication failures after migration:**
- Confirm the SAML assertion `assertion_attribute_external_uid` includes the correct unique identifier
- Verify that your SAML configuration uses the same unique identifier for both SCIM and SAML authentication
## Team provisioning with SCIM
SCIM provides automated team management capabilities that go beyond what Team Sync offers. While Team Sync only maps identity provider groups to existing Grafana teams, SCIM can automatically create and delete teams based on group changes in the identity provider.
{{< admonition type="note" >}}
Team provisioning requires `group_sync_enabled = true` in the SCIM configuration. See [Configure SCIM in Grafana](../../configure-scim-provisioning#configure-scim-in-grafana) for more information.
{{< /admonition >}}
{{< admonition type="warning" >}}
Teams provisioned through SCIM cannot be deleted manually from Grafana - they can only be deleted by removing their corresponding groups from the identity provider. Optionally, you can disable SCIM group sync to allow manual deletion of teams.
{{< /admonition >}}
For detailed configuration steps specific to the identity provider, see:
- [Configure SCIM with Entra ID](../configure-scim-with-azuread/)
- [Configure SCIM with Okta](../configure-scim-with-okta/)
### SCIM vs Team Sync
{{< admonition type="warning" >}}
Do not enable both SCIM Group Sync and Team Sync simultaneously as these methods can conflict with each other. However, you can use SCIM for user provisioning while keeping Team Sync for team management until migration support is available.
{{< /admonition >}}
Choose one team synchronization method:
- If you enable SCIM Group Sync, disable Team Sync and use SCIM for team management
- If you prefer Team Sync, do not enable SCIM Group Sync
{{< admonition type="warning" >}}
**Team Sync Migration:** Support for migrating from Team Sync to SCIM Group Sync is coming soon. Until this support is released, we recommend keeping your existing Team Sync setup for team management. You can still benefit from SCIM user provisioning capabilities while using Team Sync for team management.
{{< /admonition >}}
### Key differences
SCIM Group Sync provides several advantages over Team Sync:
- **Automatic team creation:** SCIM automatically creates Grafana teams when new groups are added to the identity provider
- **Automatic team deletion:** SCIM removes teams when their corresponding groups are deleted from the identity provider
- **Real-time updates:** Team memberships are updated immediately when group assignments change
- **Simplified management:** No need to manually create teams in Grafana before mapping them
### How team synchronization works
SCIM manages teams through the following process:
Group assignment:
- User is assigned to groups in the identity provider
- SCIM detects group membership changes
Team creation and mapping:
- Creates Grafana teams for new identity provider groups
- Maps users to appropriate teams
- Removes users from teams when group membership changes
Team membership maintenance:
- Continuously syncs team memberships
- Removes users from teams when removed from groups
- Updates team memberships when groups change
## Next steps
- [Troubleshoot SCIM provisioning](../troubleshooting/)
- [Configure SCIM with Entra ID](../configure-scim-with-azuread/)
- [Configure SCIM with Okta](../configure-scim-with-okta/)
docs/sources/setup-grafana/configure-access/configure-scim-provisioning/troubleshooting/_index.md
+78
View File
@@ -0,0 +1,78 @@
---
aliases:
- ../../configure-security/setup-grafana/configure-security/configure-scim-provisioning/troubleshooting/ # /docs/grafana/next/setup-grafana/configure-security/setup-grafana/configure-security/configure-scim-provisioning/troubleshooting/
- ../../configure-security/configure-scim-provisioning/troubleshooting/ # /docs/grafana/next/setup-grafana/configure-security/configure-scim-provisioning/troubleshooting/
description: Troubleshoot common SCIM provisioning issues in Grafana, including user provisioning, authentication, and login problems.
keywords:
- grafana
- scim
- troubleshooting
- user-provisioning
- authentication
labels:
products:
- cloud
- enterprise
menuTitle: Troubleshoot SCIM
title: Troubleshoot SCIM provisioning
weight: 400
---
# Troubleshoot SCIM provisioning
This page provides solutions for common issues you might encounter when configuring and using SCIM provisioning in Grafana.
## User provisioning issues
### Error: "invalid namespace"
**Cause:** The SCIM endpoint URL is incorrectly formatted.
**Solution:** Verify your URL follows the correct format:
```bash
https://{$GRAFANA_URL}/apis/scim.grafana.app/v0alpha1/namespaces/{$STACK_ID}/Users
```
Where:
- `{$GRAFANA_URL}` is your Grafana URL (subdomain format)
- `{$STACK_ID}` is your Grafana stack ID:
- **Grafana Cloud:** Format like `stack-123` (found in your Grafana Cloud dashboard)
- **On-premises:** Use `default` or the name of the organization
## Authentication issues
### Error: "HTTP 403 Forbidden"
**Cause:** Either incorrect token or insufficient permissions.
**Solution:**
1. **Check token:** Generate a new token from the Service Account details page
2. **Verify permissions:** Ensure the service account has `Editor` or `Admin` role in the Grafana instance
### Error: "HTTP 401 Unauthorized"
**Cause:** Invalid or expired authentication token.
**Solution:** Generate a new token from the Service Account details page in Grafana.
## Login issues
### Error: "User sync failed"
**Cause:** The user's unique identifier field is not correctly configured in SAML assertions.
**Solution:** Add the required SAML assertion based on your identity provider:
| SAML Assertion | Identity Provider | Value |
| -------------- | ----------------- | -------------------------------- |
| `userUID` | Entra ID | `objectId` |
| `userUID` | Okta | `user.getInternalProperty("id")` |
## Next steps
- [Manage users and teams with SCIM provisioning](../manage-users-teams/)
- [Configure SCIM with Entra ID](../configure-scim-with-azuread/)
- [Configure SCIM with Okta](../configure-scim-with-okta/)
docs/sources/setup-grafana/configure-access/configure-team-sync.md
+67
View File
@@ -0,0 +1,67 @@
---
aliases:
- ../setup-grafana/configure-security/configure-team-sync/ # /docs/grafana/next/setup-grafana/setup-grafana/configure-security/configure-team-sync/
- ../../auth/team-sync/ # /docs/grafana/next/auth/team-sync/
- ../../enterprise/team-sync/ # /docs/grafana/next/enterprise/team-sync/
- ../configure-security/configure-team-sync/ # /docs/grafana/next/setup-grafana/configure-security/configure-team-sync/
description: Learn how to use Team Sync to synchronize between your authentication provider teams and Grafana teams.
labels:
products:
- cloud
- enterprise
title: Configure Team Sync
weight: 600
---
# Configure Team Sync
Team sync lets you set up synchronization between your auth providers teams and teams in Grafana. This enables LDAP, OAuth, or SAML users who are members of certain teams or groups to automatically be added or removed as members of certain teams in Grafana.
{{< admonition type="note" >}}
Available in [Grafana Enterprise](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/introduction/grafana-enterprise/) and [Grafana Cloud Advanced](https://grafana.com/docs/grafana-cloud/).
{{< /admonition >}}
Grafana keeps track of all synchronized users in teams, and you can see which users have been synchronized in the team members list, see `LDAP` label in screenshot.
This mechanism allows Grafana to remove an existing synchronized user from a team when its group membership changes. This mechanism also enables you to manually add a user as member of a team, and it will not be removed when the user signs in. This gives you flexibility to combine LDAP group memberships and Grafana team memberships.
> Currently the synchronization only happens when a user logs in, unless LDAP is used with the active background synchronization.
<div class="clearfix"></div>
## Supported providers
- [Auth Proxy](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/auth-proxy/#team-sync)
- [Entra ID](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/azuread/#team-sync)
- [Generic OAuth integration](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/generic-oauth/#configure-team-synchronization)
- [GitHub OAuth](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/github/#configure-team-synchronization)
- [GitLab OAuth](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/gitlab/#configure-team-synchronization)
- [Google OAuth](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/google/#configure-team-synchronization)
- [LDAP](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/enhanced-ldap/)
- [Okta](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/okta/#configure-team-synchronization)
- [SAML](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/saml/)
## Synchronize a Grafana team with an external group
If you have already grouped some users into a team, then you can synchronize that team with an external group.
1. In Grafana, navigate to **Administration > Users and access > Teams**.
1. Select a team.
1. Go to the External group sync tab, and click **Add group**.
![External group sync](/static/img/docs/enterprise/team_add_external_group.png)
1. Insert the value of the group you want to sync with. This becomes the Grafana `GroupID`.
Examples:
- For LDAP, this is the LDAP distinguished name (DN) of LDAP group you want to synchronize with the team.
- For Auth Proxy, this is the value we receive as part of the custom `Groups` header.
1. Click **Add group** to save.
> Group matching is case insensitive.
## LDAP specific: wildcard matching
When using LDAP, you can use a wildcard (\*) in the common name attribute (CN)
to match any group in the corresponding Organizational Unit (OU).
Ex: `cn=*,ou=groups,dc=grafana,dc=org` can be matched by `cn=users,ou=groups,dc=grafana,dc=org`
docs/sources/setup-grafana/configure-access/multi-team-access.md
+161
View File
@@ -0,0 +1,161 @@
---
aliases:
- ../setup-grafana/configure-security/manage-single-access/ # /docs/grafana/next/setup-grafana/setup-grafana/configure-security/manage-single-access/
- ../../enterprise/manage-single-access/ # /docs/grafana/next/enterprise/manage-single-access/
- ../configure-security/manage-single-access/ # /docs/grafana/next/setup-grafana/configure-security/manage-single-access/
description: Manage multi-team access in a single Grafana instance
keywords:
- grafana
- rbac
- lbac
- auth
- access
- teams
labels:
products:
- cloud
- enterprise
title: Manage multi-team access in a single Grafana instance
menuTitle: Multi-team access
weight: 500
refs:
create-folder:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/manage-dashboards/#create-a-dashboard-folder
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/dashboards/manage-dashboards/#create-a-dashboard-folder
rbac:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-control
rbac-assign:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/assign-rbac-roles
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-control/assign-rbac-roles
rbac-fixed:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/rbac-fixed-basic-role-definitions/#fixed-role-definitions
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-control/rbac-fixed-basic-role-definitions/#fixed-role-definitions
drilldown:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/explore/simplified-exploration/
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/visualizations/simplified-exploration/
add-data-source:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/datasources/#add-a-data-source
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/connect-externally-hosted/data-sources/#add-a-data-source
lbac:
- pattern: /docs/grafana/
destination: /docs/grafana/<GRAFANA_VERSION>/administration/data-source-management/teamlbac
- pattern: /docs/grafana-cloud/
destination: /docs/grafana-cloud/security-and-account-management/authentication-and-permissions/access-policies/label-access-policies
---
# Manage multi-team access in a single Grafana instance
If your organization has multiple teams using Grafana, you can use a single Grafana Enterprise deployment or a single Grafana Cloud stack to manage access across teams using roles and folders. This approach reduces complexity, simplifies identity and access management, and facilitates cross-team collaboration.
## Benefits
By using a single Grafana instance to manage access, you can:
- Implement a unified SSO, establishing clear permissions.
- Reduce setup and maintenance work, avoiding multi-stack complexity.
- Centralize plugin configuration and management.
- Ensure teams can access the right dashboards and data, avoiding stepping on or overwriting each other’s work.
- Enable collaboration across teams. Teams are not isolated in silos and can discover and collaborate with each other’s work.
- Optimize resource management. With shared spaces, like an “Everyone” folder, you can publish executive dashboards or cross-team metrics that all groups can benefit from, without duplicating it across stacks.
## Example: Three teams, one stack
Consider the following setup of three teams:
- Team A builds product features and needs autonomy with their own dashboards and data sources.
- Team B handles data engineering and needs autonomy with their own dashboards.
- Team C is the observability team and the admins of the Grafana stack.
Follow these suggested steps to structure, configure, and set permissions to access data in your Grafana instance:
1. [Before you begin](#before-you-begin)
1. [Create teams and configure user access](#create-teams-and-configure-user-access)
1. [Design a folder structure to match your access needs](#design-a-folder-structure-to-match-your-access-needs)
1. [Configure data access based on each team’s requirements](#configure-data-access-based-on-team-requirements)
1. [Scale access management with Terraform and SSO](#scale-access-management-with-terraform-and-sso)
### Before you begin
For more information on how to install a Grafana instance:
- If you’re using self-managed Grafana Enterprise, refer to [Configure Grafana](../../configure-grafana/).
- If you’re using Grafana Cloud, refer to [Your Grafana Cloud stack](https://grafana.com/docs/grafana-cloud/security-and-account-management/cloud-stacks).
{{< admonition type="note" >}}
For guidance on when to use one stack versus multiple, refer to [Stack architecture guidance](https://grafana.com/docs/grafana-cloud/security-and-account-management/cloud-stacks/stack-architecture-guidance/).
{{< /admonition >}}
### Create teams and configure user access
After you’ve deployed your Grafana instance:
- To follow the example in this doc, create three [Grafana Teams](../../../administration/team-management/configure-grafana-teams/#create-a-grafana-team) and add them to the Grafana instance.
- Determine the [RBAC](ref:rbac) strategy for your organization. RBAC extends default Grafana roles, provides more granular access rights, and simplifies how to grant, modify, or revoke user access to Grafana resources, such as users and reports.
- Assign each user to the [relevant team](../../../administration/user-management/manage-org-users/). By default [new users](../../configure-grafana/#auto_assign_org) are granted the **Viewer** role.
- Assign the [**Admin** role](ref:rbac-assign) to Team C so that they can manage all resources in the instance.
### Design a folder structure to match your access needs
To design a [folder](ref:create-folder) setup that helps users quickly understand where to go, what they can access, and what they can manage:
- Create an “Everyone” folder for shared items that all teams can manage, and grant teams Admin access to that folder.
- For each team, create a folder that they can manage and grant them the `fixed:teams:read` [fixed role](ref:rbac-assign). This means they can share items in their team folder with other teams, to encourage collaboration and learning from each other.
- For Team C, create an “Admins” folder for sensitive content only Admins can access.
- Optionally, create a personal folder for each team member so that they can work on draft content before moving it into their team folder when ready.
{{< figure src="/media/docs/grafana/oac/AccessTeams01.png" max-width="750px" alt="Teams and folders in the stack, and the related admin permissions Team A and Team B have been granted" >}}
### Configure data access based on team requirements
Next, focus on how teams interact with data to decide further access needs.
#### Shared baseline data access
Grant the `datasources:explorer` fixed role to all teams so they can use the [Drilldown apps](ref:drilldown) for easily exploring data sources.
However, you may need to protect data in shared resources. For example, all teams can be forwarding metrics to a shared [data source](ref:add-data-source), but not everyone needs to see all of the data. In this case, grant each team query access to the data relevant for them, based on [label based access controls (LBAC) per team](ref:lbac). This way, you’ll maintain a central observability pipeline but still preserve data separation.
#### Autonomous team data management
If any of your teams, Team A for example, need to build and manage their own data sources for product-specific use cases, grant the `datasources:creator` fixed role so they can create and manage their own data sources independently.
{{< figure src="/media/docs/grafana/oac/AccessTeams02.png" max-width="750px" alt="Teams and data sources in the stack, and the related permissions Team A and Team B have been granted" >}}
#### Resources at an instance level
Some Grafana resources, such as service accounts, alert contact points, [Fleet Management collectors](https://grafana.com/docs/grafana-cloud/send-data/fleet-management/), and other feature resources, are not linked to teams but are managed at the stack level. For these type of resources, assign fixed roles to teams carefully.
For example, users working in [Frontend Observability](https://grafana.com/docs/grafana-cloud/monitor-applications/frontend-observability/) need a writer fixed role so that they can create and manage services.
{{< figure src="/media/docs/grafana/oac/AccessTeams03.png" max-width="750px" alt="Grafana Cloud Frontend Observability resources in the stack, and the related permissions Team A have been granted" >}}
### Scale access management with Terraform and SSO
After you've made sure the model is working, you can codify it.
You can add any new users to your Grafana instance with an Identity Provider through [SCIM](../../configure-access/configure-authentication/). Use [role sync](../../../configure-access/configure-authentication/saml/configure-saml-team-role-mapping/#configure-role-sync-for-saml) to automatically assign users the correct basic role (Viewer, Editor, or Admin) based on their mapped attributes in the IdP..
You can also use Terraform to provision teams their folders, fixed roles, and shared data source LBAC rules. For example, if you need to add a new team (Team D), you only need to add the new team to Grafana and run the Terraform script, which will automatically set them up to start using Grafana.
{{< figure src="/media/docs/grafana/oac/AccessTeams04.png" max-width="750px" alt="Add new Team D from Okta and automate the rest of their IAM setup using Terraform" >}}
## Other resources
Read on to learn more about access management:
- The [Least privilege custom role explainer](https://grafana.com/blog/2024/09/10/grafana-access-management-how-to-use-teams-for-seamless-user-and-permission-management/) blog walks through how to design roles that keep things simple and safe, so your users have just the access they need.
- See the [LBAC for metrics data sources](https://www.youtube.com/watch?v=gj27qKPSVsM) demo to learn how you can give every team a clear view of their own data while still benefiting from a shared pipeline.
- The [Introducing SCIM](https://grafana.com/blog/2025/05/14/introducing-scim-provisioning-in-grafana-enterprise-grade-user-management-made-simple/) post covers how to connect Grafana to your identity provider, making it easy to bring new users on board and keep permissions in sync as your organization grows.