Before you start
Make sure that you have administrator access to your Grafana instance. We support the Enterprise, self-hosted and Cloud Pro editions of Grafana. We also support free cloud instances, but then you need to set up a client credentials grant flow for each instance of the Cognite Data Source.Step 1: Register Grafana as an application in Microsoft Entra ID
The Cognite Data Source for Grafana uses the credentials you use to sign in to Grafana to connect to CDF. Therefore, you need to set up the Grafana instance to authenticate the user towards the same identity provider (IdP) as your CDF project. The first step is to configure the Grafana instance to use OAuth2. The example below uses Microsoft Entra ID as the IdP.Register the Cognite API and CDF application
Enable Microsoft Entra ID authentication in Grafana
scopes = openid email profile offline_access https://<your-cluster>.cognitedata.com/user_impersonation https://<your-cluster>.cognitedata.com/IDENTITYRestart the Grafana service
Verify configuration as administrator
Grant organization consent
Step 2: Decide access to CDF data
Link Microsoft Entra ID and CDF groups
Configure required capabilities
groupsAcl:LISTandprojectsAcl:LISTto verify the connection to CDF.- Read access to the data models, views, and instances the query tabs use. See Access control for data models and Time series in data models for data points.
- Read access to records and streams for the Records tab. See Records.
- For the deprecated asset-centric features, read access to time series, assets, and events. See Capabilities.
Step 3: Install the Cognite Data Source for Grafana
To install the Cognite Data Source for Grafana:- Grafana Enterprise
- Self-hosted Grafana
Sign in as administrator
Install the plugin
Step 4: Configure the Cognite Data Source for Grafana
To configure the Cognite Data Source for Grafana:Sign in to Grafana
Add the Cognite data source

Configure the data source

Save and test the configuration
Verify the configuration
Step 5: Turn on query tabs
Feature flags on the Features tab of the data source settings decide which query tabs users see in panels, and which tabs the variable editor shows.Open the Features tab
Choose a feature group
Turn on the tabs you need

Save the settings
Set up a client credentials grant flow
In some cases, for example, if you’re using the Grafana free tier, you can not set up an identity provider for the whole Grafana instance. Instead, follow these steps to set up a client credentials grant flow for each instance of the Cognite Data Source:Before you start
Set up application registration
Register Cognite API and CDF application
Configure required capabilities
Add service principal to CDF group
Install the plugin
Navigate to data sources
Select Cognite data source
Configure OAuth2 client credentials
- Disable Forward OAuth identity.
- Enable OAuth2 client credentials.
- Enter the credentials.
Validate credentials

Troubleshooting
Bad Gateway error when setting up the Base URL
Symptom When selecting Save & test in the CDF plugin configuration, the user gets a Bad Gateway error. The developer tab in Grafana has a 502 error in the network tab. Causes The Base URL in the setup is wrong, but the user only gets the Bad Gateway error message. Fixes Check that the Base URL field has a valid Cognite hostname.- If the project uses the default multi-tenant cluster (
api.cognitedata.com), keep the default value and don’t change the hostname. - If the project uses another cluster, such as
westeurope-1.cognitedata.com, set Base URL to that cluster’s hostname. - If you’re unsure, use the default hostname.
- Do not use
https://or trailing slashes/in the Base URL field. The Token URL for client credentials is a full URL and does includehttps://.