An overview of Grafana SSO: Benefits, recent updates, and best practices to get started

Grafana began as an open and composable platform for data visualization. Today, Grafana has evolved into an all-in-one observability platform, providing everything from infrastructure and application performance monitoring to load testing and incident response.

As organizations extend their use of Grafana, efficient and secure authentication and authorization is essential. Fortunately, Grafana provides multiple ways to authenticate users, including

• Lightweight Directory Access Protocol (LDAP) authentication
• Basic authentication
• JSON Web Token (JWT) authentication
• Single sign-on (SSO)

In this post, we’ll provide an overview of Grafana SSO, including how it compares to other authentication methods, its benefits, and recent updates that make it easier to configure SSO in your environment.

A comparison of authentication methods

Before we dive into the details of SSO, specifically, let’s compare the supported authentication methods in Grafana. Note: For more information on which methods are supported in Grafana OSS, Grafana Cloud, and Grafana Enterprise, please refer to our technical documentation.

Additionally, you can configure Grafana to use Anonymous authentication, which allows users to access Grafana without requiring any login.

Ultimately, your choice of authentication type depends on your organization’s unique requirements. Most of these authentication methods also allow you to sync user permissions from external providers to Grafana and, therefore, easily control access. While this is beyond the scope of this blog post, you can read more in our technical documentation.

Why use SSO with Grafana?

While SSO might not be applicable to all types of organizations and users, it comes with several advantages compared to other forms of authentication, including:

• Enhanced security and better compliance: Centralized authentication reduces the risk of compromised credentials. It makes it easier to enforce policies and maintain audit trails, and also scales really well.
• Better user experience: Users can access Grafana resources without needing to log in separately (aka, no password fatigue), and administrators can manage user access and permissions from a centralized place (for example, their IdP).

What’s new in Grafana SSO configuration?

Historically, configuring SSO in Grafana required updating static configuration files and restarting the Grafana instance for the changes to take effect. This process could be cumbersome and disruptive.

With the Grafana 10 release, we introduced a new UI to easily configure SAML authentication. Thanks to feedback from our community, we decided to streamline the entire SSO setup process and introduced the following updates, starting with Grafana 11:

• UI configuration: Configure SSO directly through the Grafana user interface.
• API support: Automate SSO setup and management using Grafana’s API. Refer to the documentation for more information.
• Terraform integration: Manage SSO configurations as code with Terraform support. Refer to the documentation for more information.

Configuration files vs. the UI/API

Configuring SSO through Grafana configuration files is still supported and might be applicable in certain scenarios, including when there’s limited infrastructure automation. That said, using the UI or API instead of configuration files has the following advantages:

• Available in Grafana Cloud: Set up SSO inside of your Grafana Cloud instance without needing to file a support request.
• Real-time configuration validation: When using the UI or API, all settings are validated in real time, providing immediate feedback on the validity of the configuration.
• No need to restart Grafana: Using the UI or API eliminates the need to restart Grafana after making changes.
• RBAC authorization: You have the flexibility to authorize specific users to access the UI or API by using role-based access control (RBAC).

It is not recommended to mix configuration methods (for example, to define some fields in a config file and some through the API). If, for some reason, configuration has to be done using both options, Grafana will follow a specific precedence order when loading the configuration:

1. Settings that were configured using the UI/API, or Terraform.
2. Settings from environment variables.
3. Settings from the Grafana configuration file.

Exploring the Authentication user interface

To access the UI in Grafana or Grafana Cloud, navigate to Administration > Authentication in the navigation menu of your Grafana instance.

Please note that in order to access this page, a user must have the settings:read and settings:write permissions. By using the *settings:auth.{provider}:** scope with appropriate providers, you can control access by indicating which specific providers a user can set up.

Best practices to set up SSO

Setting up SSO requires knowledge of both identity providers and Grafana. With hundreds of identity providers available, offering built-in support for all of them is not feasible. This is why Grafana supports a Generic OAuth configuration, which can be used to set up SSO with any identity provider that supports OAuth 2.0.

Here are a few generic guidelines to follow when setting up SSO in Grafana:

• Understand your identity provider: Each IdP has specific requirements and quirks, so consult their documentation thoroughly before moving forward.
• Configure redirect Uniform Resource Identifier (URIs) correctly: Make sure the redirect URIs configured in your IdP match exactly with those specified in Grafana. Incorrect URIs can cause authentication failures.
• Avoid using Generic OAuth if your provider is supported by Grafana. If you are using Azure Active Directory, Okta, Google, GitHub or GitLab, use the appropriate configuration for them and avoid Generic OAuth. This approach simplifies setup and is less error-prone. Additionally, configuration is much more fine-grained, as certain functionality won’t be available with Generic OAuth.
• When using OAuth, configure allowed_domains, allowed_groups or allowed_organizations: This will reduce the attack surface for user accounts and create defense in depth (DiD) in case authentication is bypassed.
• Enable use_pkce=true for OAuth integrations: Proof Key for Code Exchange (PKCE) is an important addition to OAuth and it might be obligatory in future versions of the protocol. Enable it from the start to avoid breakage on IdP updates (it’s been enabled by default since Grafana 10.1).
• Use request signing when setting up SAML: Request signing is a critical security feature in SAML that enhances the overall security of the authentication process. It ensures SAML requests are genuine, unaltered, and originate from a trusted service provider, thereby protecting the system from various threats and ensuring compliance with security standards.
• Set up auto login: Available for OAuth and SAML, this will improve the user experience.

Troubleshooting SSO setup

Setting up SSO requires configuration in multiple places, and sometimes, it doesn’t work out the first time. Being prepared and having the right tools for debugging can streamline the process.

Be familiar with identity protocols

Most of the authentication protocols involve browser redirects and HTTP requests/responses between several components, so troubleshooting will be easier if you are familiar with the expected sequence of interaction for a particular scenario. Specifically, it will be helpful to know:

• The parameters expected by each protocol endpoint
• The responses and error codes returned by each endpoint
• The identity provider APIs

Have the right tools

Tools to capture and view HTTP traces are especially helpful to troubleshoot during SSO setup. Most internet browsers offer dev tools with built-in capabilities to capture an HTTP trace in the “Network” tab. It is also convenient to be able to dump the HTTP trace to an HTTP Archive format (.har file), which will capture everything, including the cleartext value of any secret.

Other examples of tools for SSO debugging and troubleshooting include:

• Postman or Insomnia to test API calls
• Fiddler or Charlesproxy to capture and view network traces of backend API calls
• https://jwt.io/ to view and create JWTs
• SAML-tracer, available for Firefox and Chrome, to inspect SAML requests

Know these debugging basics

When something is not working as expected, especially when it comes to authentication, it’s best to start checking the simple things. For example:

• Check that the identity provider is accessible and not experiencing any issues
• Ensure the supplied credentials are correct for the environment
• Check that the login account and credentials are not disabled or expired
• Make sure Grafana is using the correct URL for the identity provider
• Verify the client ID matches the one registered in identity provider
• Check the redirect/callback URL
• Read all error messages to see if they provide valuable clues

What’s next?

We hope the recent updates we’ve made related to the UI, API, and Terraform enhance your experience with Grafana and simplify the SSO setup process. Looking ahead, we plan to introduce a new UI and API for configuring LDAP, which will make authentication setup even easier.

In the meantime, if you want to learn more about how to organize your users and teams in Grafana to ensure optimal security, please refer to this blog post.

Grafana Cloud is the easiest way to get started with metrics, logs, traces, dashboards, and more. We have a generous forever-free tier and plans for every use case. Sign up for free now!