Grafana 9.3 feature: Grafana OAuth token improvements

As part of our efforts to improve the security of Grafana, we introduced a long-awaited feature in the latest Grafana 9.3 release that enhances Grafana’s OAuth 2.0 compatibility. The new Grafana OAuth token improvements, which are available in Grafana OSS, Grafana Cloud, and Grafana Enterprise, ensure that the user is not only logged into Grafana, but they’re also authorized by the OAuth identity provider. 

With this new functionality, Grafana verifies on each request that the current user has an access token that has not expired. This means the user is authorized to access the Grafana instance. If the access token has expired, then Grafana uses the provided refresh token (if any exists) to obtain a new access token from the identity provider. This allows the user to continue working in Grafana without any interruption as opposed to having to log in again. 

Let’s take a closer look at this new capability and how it helps improve security and the user experience in Grafana.

How Grafana OAuth works in Grafana 9.3

Grafana supports different OAuth providers (such as Azure AD, Okta, Google, among others) that you can use to allow your users to log in to Grafana from identity providers. After a successful login, Grafana creates a session token that is used for authorizing subsequent requests. The session token expiration date is configured based on the Grafana config ([auth]login_maximum_lifetime_duration), and it’s usually greater than the expiration date of the provided access token. This allows users to access Grafana despite the fact that they are no longer authorized by their identity provider.

Most of the OAuth identity providers (you can find the specific configuration for all identity providers that Grafana supports in our authentication configuration documentation) include a short-lived access token with a long-lived refresh token in the authorization response. By having a long-lived refresh token, Grafana can obtain a new access token when the current access token expires. At the same time, Grafana will verify that the user is still authorized to access Grafana and authenticate on the identity provider side. If the user is no longer authorized to access Grafana, then the request to get a new access token would fail, and the user gets logged out from Grafana.

A quick guide to OAuth tokens

What are access tokens?

An OAuth access token is a credential artifact that an OAuth client uses to make requests to the resource server on behalf of a user. With an access token, the specific application has the authorization to perform certain tasks or access specific data for the user.

What are refresh tokens?

An OAuth refresh token is a credential artifact that lets an OAuth client obtain new access tokens without having to ask the user to log in again. Access tokens may have a short lifespan and once they expire, client applications can use a refresh token to get a new access token. To learn more, check out this blog post about using refresh tokens securely.

What are session tokens?

A session token is an encrypted, unique string that identifies the current session for a logged in user and is used for authenticating and authorizing requests in Grafana.

Enable access token and refresh token support in Grafana 9.3

Currently, this functionality is disabled by default for already existing Grafana setups to prevent logging out users unexpectedly when the external identity provider is not configured to use refresh tokens. 

In Grafana OSS and Grafana Enterprise, the feature can be enabled with the accessTokenExpirationCheck feature toggle. For an on-premise Grafana instance, you should add accessTokenExpirationCheck = true to the [feature_toggles] section of Grafana’s configuration file (Configure Grafana). 

Grafana Cloud users should reach out to customer support to configure and enable this feature.

Complete documentation on how to configure obtaining a refresh token can be found on the authentication configuration page, where there are instructions for different OAuth identity providers.

Please note: Enabling this functionality without configuring refresh tokens for the specific OAuth identity provider will get users logged out after their access token has expired, and they would need to log in again.

Learn more about Grafana 9.3

For a complete list of new features in Grafana 9.3, which include new navigation updates and localization, check out the changelog and our What’s New in Grafana 9.3 documentation. You can also join us on our Grafana Labs community forums to discuss any of the new features, workflows, or how to incorporate these changes into your dashboards, queries, and visualizations.

Download Grafana 9.3 today or to upgrade your Grafana installation to the latest version, refer to our Upgrade Grafana documentation

New to Grafana? Try Grafana 9.3 on Grafana Cloud, which has a generous free forever tier and plans for every use case. Sign up for free today! You can also check out our “Getting started with Grafana” webinar on demand to learn more.