Documentationbreadcrumb arrow Grafana documentationbreadcrumb arrow Set upbreadcrumb arrow Configure access managementbreadcrumb arrow Configure authenticationbreadcrumb arrow SAML
Grafana Cloud Enterprise

SAML authentication in Grafana

Note

Available in Grafana Enterprise and Grafana Cloud.

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

Set up options for SAML authentication in Grafana

You can configure SAML authentication in Grafana with different methods. While the configuration options don’t change, if you want to keep all of Grafana authentication settings in one place, use the Grafana configuration file or the Terraform provider. If you’re a Grafana Cloud user, you don’t have access to Grafana configuration file. Instead, configure SAML through the other methods.

Caution

Configuration in the API or UI 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.

For more information on how Grafana determines the order of precedence for its settings, refer to the SSO Settings API.

The available methods are:

If you’re using Okta or Entra ID as Identity Provider, see the following documentation for configuration:

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

Identity provider (IdP) registration

For the SAML integration to work correctly, you need to make your IdP aware that Grafana is 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.

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.

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.

Integrate with SCIM Provisioning

If you’re 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.
    • 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.

Advanced configuration

For advanced configuration and troubleshooting, refer to the one of the following pages: