Configure SAML authentication in Grafana on Grafana Labs

Configure SAML authentication using the Grafana configuration file

Fri, 03 Apr 2026 19:43:06 +0000

Configure SAML authentication using the Grafana configuration file

Note
Available in Grafana Enterprise and Grafana Cloud.

Refer to Configuration for more information about configuring Grafana.

To configure SAML authentication in Grafana using the configuration file, follow these steps:

In the [auth.saml] section in the Grafana configuration file, set enabled to true.
Configure SAML according to your requirements. Review all the available configuration options.
For IdP-specific configuration, refer to:
- Configure SAML with Okta
- Configure SAML with Entra ID
Save the configuration file and then restart the Grafana server.

Here’s an example of a Grafana configuration file with SAML:

[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

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

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.

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.

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.

auto_login = true

Configure allowed organizations

With the 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:

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) 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.

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.

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.

Assertion mapping

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.

Refer to Assertion mapping for more information.

Examples:

#plain string mapping
assertion_attribute_name = displayName

#template mapping
assertion_attribute_name = $__saml{firstName} $__saml{lastName}

Configure SAML authentication using the Grafana user interface

Fri, 03 Apr 2026 19:43:06 +0000

Configure SAML authentication using the Grafana user interface

Note
Available in Grafana Enterprise version 10.0 and later, and to customers on select Grafana Cloud plans. For pricing information, visit Pricing or contact our sales team.

You can configure SAML authentication in Grafana using the configuration file, Terraform, the API, or the UI. Refer to Set up options for SAML authentication in Grafana for more details. Configuration in the API or UI takes precedence over the configuration in the Grafana configuration file. For more information on how Grafana determines the order of precedence for its settings, refer to the SSO Settings API.

The Grafana SAML UI provides the following advantages over configuring SAML in the Grafana configuration file:

It’s accessible by Grafana Cloud users.
Access to the SAML UI only requires access to authentication settings, so users with limited access to the Grafana configuration can use it.
The SAML UI carries out input validation and gives feedback on whether the configuration works, making SAML setup easier.
It doesn’t require Grafana to be restarted after a configuration update.

To configure SAML authentication from the UI, sign in to Grafana and navigate to Administration > Authentication > Configure SAML and follow this document.

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, which 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.
A Grafana instance running Grafana version 10.0 or later with Grafana Enterprise, or a select Grafana Cloud account.

General Settings

Complete the General settings fields:

Allow signup: If enabled, you can create users through SAML login. If it’s disabled, only existing Grafana users can log in with SAML.
Auto login: If enabled, Grafana automatically logs 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.
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.

Sign Requests

Toggle Sign requests to specify whether you want the outgoing requests to be signed. Although optional, requesting signatures provides a more secure approach to SAML.

If you select to sign them:

Provide a certificate and a private key that’ll be used by the service provider (Grafana) and the SAML IdP.

Use the PKCS #8 format to issue the private key.

For more information, refer to an example on how to generate SAML credentials.

Alternatively, you can generate a new private key and certificate pair directly from the UI. Click the Generate key and certificate button to open a form where you provide information to embed in the new certificate.
Choose which signature algorithm to use. 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.

Connect Grafana with the Identity Provider

Note
You can skip this screen.

Configure IdP using Grafana metadata:

Copy the Metadata URL and provide it to your SAML IdP to establish a connection between Grafana and the IdP. The metadata URL contains the necessary information for the IdP to establish a connection with Grafana.
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.
If you want to use the Single Logout feature, copy the Single Logout Service URL and provide it to your SAML IdP.

Finish configuring Grafana using IdP data:

The metadata contains 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.

User Mapping

Assertion mapping

If you want to map user information from SAML assertions, complete the Assertion attributes mappings section.

To use team sync you need to configure the Groups attribute field. Team sync automatically maps users to Grafana teams based on their SAML group membership. Learn more about team sync and configuring team sync for SAML.

Role mapping

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 automatically updates user’s basic role based on their SAML roles every time the user logs in to Grafana. Learn more about SAML role synchronization.

Mapping with Entra ID

If you’re using Entra ID as the Identity Provider over SAML, keep in mind Azure’s interpretation of these attributes. Enter the full URLs 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.

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

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.

Set up a service account in Entra ID and provide the necessary details in the Entra ID Service Account Configuration section.
Provide the Client ID of your Entra ID application.
Provide the Client Secret of your Entra ID application, the Client Secret will be used to request an access token from Entra ID.
Provide the Entra ID request Access Token URL.
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.

Mapping organizations

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 automatically updates user’s organization memberships (and roles, if they’ve been configured) based on their SAML organization every time the user logs in to Grafana. Learn more about SAML organization mapping.

If you want to limit the access to Grafana based on user’s SAML organization membership, fill in the Allowed organizations field.

Test And Enable

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.
If there are no configuration issues, the SAML integration status will change to Enabled. Your SAML configuration is now enabled.
To disable SAML integration, click Disable in the top right corner.

SAML configuration options

Fri, 03 Apr 2026 19:43:06 +0000

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.

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

[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

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 for a complete reference on using the grafana_sso_settings resource.

Configure SAML signing and encryption

Fri, 03 Apr 2026 19:43:06 +0000

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 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.

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.

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 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:

$ 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)

$ 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-----

Configure Role and Team sync for SAML

Fri, 03 Apr 2026 19:43:06 +0000

Configure team sync for SAML

Note
Available in Grafana Enterprise and to customers on select Grafana Cloud plans. For pricing information, visit pricing or contact our sales team.

To use SAML Team sync, set 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.

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>

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.

Given the following partial SAML assertion:

<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:

[auth.saml]
# ...
assertion_attribute_groups = groups

The following External Group IDs would be valid for input in the desired team’s External group sync tab:

admins_group
division_1

Learn more about 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.

In the configuration file, set assertion_attribute_role option to the attribute name where the role information will be extracted from.
Set the role_values_none option to the values mapped to the None role.
Set the role_values_viewer option to the values mapped to the Viewer role.
Set the role_values_editor option to the values mapped to the Editor role.
Set the role_values_admin option to the values mapped to the organization Admin role.
Set the 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.

Example configuration:

[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:

[auth.saml]
skip_org_role_sync = true

Configure organization mapping for SAML

Fri, 03 Apr 2026 19:43:06 +0000

Configure organization mapping for SAML

Organization mapping allows you to assign users to a particular organization in Grafana depending on attribute value obtained from the identity provider.

In configuration file, set 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.
Set 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:

[auth.saml]
assertion_attribute_org = Org
org_mapping = Engineering:2:Editor, Sales:3:Admin

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 instead.

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:

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:

# 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:

[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.

Configure SAML single logout

Fri, 03 Apr 2026 19:43:06 +0000

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.

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.

Configure SAML authentication with Microsoft Entra ID

Fri, 03 Apr 2026 19:43:06 +0000

Configure SAML with Microsoft Entra ID

Grafana supports user authentication through Microsoft Entra ID.

Note
Starting in Grafana v11.2, the SAML integration offers a mechanism to retrieve user groups from the Graph API.

Grafana versions 11.1 and below do not support fetching groups from the Graph API endpoint. As a result, users with more than 150 groups will not be able to retrieve their groups. Instead, use the Entra ID connector.

Related links:

Entra ID SAML limitations

Configure a Graph API application in Entra ID

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.

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.

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):

$ 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 the 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

Go to the Azure portal and sign in with your Entra ID account.
Search for Enterprise Applications.
In the Enterprise applications pane, select New application.
In the search box, enter SAML Toolkit, and then select the Microsoft Entra SAML Toolkit from the results panel.
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.

In the SAML Toolkit application, select Set up single sign-on.
In the Single sign-on pane, select SAML.
In the Set up Single Sign-On with SAML pane, select the pencil icon for Basic SAML Configuration to edit the settings.
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.
Select Save.
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

In the Overview pane, select Certificates & secrets.
Select New client secret.
In the Add a client secret pane, enter a description for the secret.
Set the expiration date for the secret.
Select Add.
Copy the value of the secret. This value is used in the client_secret field in the SAML configuration.

Configure SAML assertions to use 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.

Open your Entra ID application.
Select the SAML single sign-on configuration.
Edit the Attributes & Claims section.
Add a new claim with the following settings:
- Name: userUID
- Namespace: leave blank
- Source: Attribute
- Source attribute: user.objectId
Save the current configuration.

Adjust your user mapping configuration to use the Entra ID URI

If the default URI claims don’t work, adjust your user mapping to the following:

Name attribute = http://schemas.microsoft.com/identity/claims/displayname
Login attribute = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Email attribute = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Configure a Graph API application in Entra ID

While you can configure an Entra ID tenant 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. To learn more refer to Entra ID SAML limitations.

The following configuration example uses the URL https://localhost as the Grafana URL. Replace it with your Grafana instance URL.

Create a new App registration

This app registration is used as a Service Account to retrieve more information about the Entra ID user.

Go to the Azure portal and sign in with your Entra ID account.
In the left-hand navigation pane, select the Microsoft Entra ID service, and then select App registrations.
Click the New registration button.
In the Register an application pane, enter a name for the application.
In the Supported account types section, select the account types that can use the application.
In the Redirect URI section, select Web and enter https://localhost/login/azuread.
Click the Register button.

Set up permissions for the application

In the overview pane, look for API permissions section and select Add a permission.
In the Request API permissions pane, select Microsoft Graph, and click Application permissions.
In the Select permissions pane, under the GroupMember section, select GroupMember.Read.All.
In the Select permissions pane, under the User section, select User.Read.All.
Click the Add permissions button at the bottom of the page.
In the Request API permissions pane, select Microsoft Graph, and click Delegated permissions.
In the Select permissions pane, under the User section, select User.Read.
Click the Add permissions button at the bottom of the page.
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

To test that Graph API has the correct permissions, refer to the Troubleshoot Graph API calls section.

Configure SAML authentication with Okta

Fri, 03 Apr 2026 19:43:06 +0000

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. 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
Ensure you have permission to administer SAML authentication. For more information about roles and permissions in Grafana, refer to Roles and permissions.

Set up SAML with Okta

Caution
These steps are for assistance only, refer to the official Okta documentation for the up-to-date instructions.

Log in to the Okta portal.
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.
In the Admin Console, navigate to Applications > Applications.
Click Create App Integration to start the Application Integration Wizard.
Choose SAML 2.0 as the Sign-in method.
Click Create.
On the General Settings tab, enter a name for your Grafana integration. You can also upload a logo.

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.
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.

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.

Click Next.
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.

Open your Okta application.
Select the SAML single sign-on configuration.
Edit the Attributes & Claims section.
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`

Troubleshoot SAML configuration

Fri, 03 Apr 2026 19:43:06 +0000

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 for more information.

[log]
filters = saml.auth:debug

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.

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)

$ 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.

To solve this issue, you can configure either the csrf_trusted_origins or csrf_additional_headers option in the SAML configuration.

Example of a configuration file:

# config.ini
...
[security]
csrf_trusted_origins = https://grafana.example.com
csrf_additional_headers = X-Forwarded-Host
...

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:

[security]
cookie_samesite = lax

This setting should be set to lax to allow Grafana session cookies to work correctly with redirects.

[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:

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:

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:

{
  "access_token": "...ACCESS_TOKEN...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use the access_token to test the Graph API calls.

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:

{
  "@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.

Configure SAML authentication in Grafana on Grafana Labs

Configure SAML authentication using the Grafana configuration file

Configure SAML authentication using the Grafana configuration file

SAML Name ID

Maximum issue delay

Metadata valid duration

Allow new user sign up

Configure automatic login

Configure allowed organizations

Configuring SAML with HTTP-Post binding

IdP-initiated Single Sign-On (SSO)

Assertion mapping

Configure SAML authentication using the Grafana user interface

Configure SAML authentication using the Grafana user interface

Before you begin

General Settings

Sign Requests

Connect Grafana with the Identity Provider

User Mapping

Assertion mapping

Role mapping

Mapping with Entra ID

Mapping organizations

Test And Enable

SAML configuration options

SAML configuration options

Example SAML configuration

Example SAML configuration in Terraform

Configure SAML signing and encryption

Configure SAML signing and encryption

Certificate and private key

Signature algorithm

Supported algorithms

Important considerations

Example of private key generation for SAML authentication

Configure Role and Team sync for SAML

Configure team sync for SAML

Configure role sync for SAML

Configure organization mapping for SAML

Configure organization mapping for SAML

Configure SAML single logout

Configure SAML Single Logout

Configure SAML authentication with Microsoft Entra ID

Configure SAML with Microsoft Entra ID

Before you begin

Generate self-signed certificates

Add the Microsoft Entra SAML Toolkit from the gallery

Configure the SAML Toolkit application endpoints

Generate a client secret

Configure SAML assertions to use SCIM provisioning

Adjust your user mapping configuration to use the Entra ID URI

Configure a Graph API application in Entra ID

Create a new App registration

Set up permissions for the application

Configure SAML authentication with Okta

Configure SAML Okta

Before you begin

Set up SAML with Okta

Configure SAML assertions when using SCIM provisioning

Example configuration

Troubleshoot SAML configuration

Troubleshooting

Troubleshoot SAML authentication in Grafana

Infinite redirect loop / User gets redirected to the login page after successful login on the IdP side

SAML authentication fails with error:

Convert the private key format to base64

SAML login attempts fail with request response origin not allowed

SAML login attempts fail with request response “login session has expired”

Troubleshoot Graph API calls

SAML login attempts fail with request response `origin not allowed`