> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK https://cognite-sdk-python.readthedocs-hosted.com/en/stable/; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Setup and administration for Grafana

> Use the Cognite Data Source for Grafana to connect a CDF project as a data source in Grafana with OpenID Connect authentication.

You can use OpenID Connect and your existing identity provider (IdP) framework to manage access to CDF data securely. We currently support Microsoft Entra ID, Microsoft's cloud-based identity and access management service.

Follow the steps below to connect to a CDF project with OpenID Connect and use CDF as a data source in Grafana.

> [!NOTE]
>
> To perform the steps below, you need to be an administrator of Microsoft Entra ID and your Grafana instance.

## Before you start

Make sure that you have administrator access to your Grafana instance. We support the [Enterprise](https://grafana.com/products/enterprise/grafana), [self-hosted](https://grafana.com/docs/grafana/latest/installation) and [Cloud Pro](https://grafana.com/auth/sign-up/create-user) editions of Grafana. We also support free cloud instances, but then you need to [set up a client credentials grant flow](#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.

**1. Register the Cognite API and CDF application**

Make sure that you have already [registered the Cognite API and the CDF application in Microsoft Entra ID](https://docs.cognite.com/cdf/access/entra/guides/configure_cdf_azure_oidc.md).

**2. Enable Microsoft Entra ID authentication in Grafana**

To enable users to sign in to Grafana with their organizational ID, follow the steps in the Grafana documentation to [register Grafana as an application in Microsoft Entra ID and enable Microsoft Entra ID authentication in Grafana](https://grafana.com/docs/grafana/latest/auth/azuread).

> [!NOTE]
>
> **Grafana Cloud**: To enable OIDC sign-in using Microsoft Entra ID with Grafana Cloud, follow the [configuration steps](https://grafana.com/docs/grafana-cloud/authentication-and-permissions/authorization#configure-oauth-with-microsoft-azure-ad).
>
> Handle the changes to the [Grafana configuration file](https://grafana.com/docs/grafana/latest/administration/configuration#config-file-locations) by using the configuration form at [Grafana Labs](https://grafana.com) > Security > Advanced Auth.

> [!NOTE]
>
> Use these permission **scopes** in the [Grafana configuration file](https://grafana.com/docs/grafana/latest/administration/configuration#config-file-locations):
> `scopes = openid email profile offline_access https://<your-cluster>.cognitedata.com/user_impersonation https://<your-cluster>.cognitedata.com/IDENTITY`

> [!TIP]
>
> If you are running Grafana locally, use `http` in the **redirect URL**. For example: `http://localhost:3000/login/azuread`.

**3. Restart the Grafana service**

Close the Grafana configuration file after updating it and restart the Grafana service.

**4. Verify configuration as administrator**

Sign in to Grafana to use the Microsoft Entra ID Global administrator role. The role lets you **verify** that the configuration is successful and enables you to grant admin consent.

**5. Grant organization consent**

Select **Consent on behalf of your organization**.

## Step 2: Decide access to CDF data

**1. Link Microsoft Entra ID and CDF groups**

To decide what access users should have to **data in CDF**, follow the steps in [Link Microsoft Entra ID and CDF groups](https://docs.cognite.com/cdf/access/entra/guides/create_groups_oidc.md).

**2. Configure required capabilities**

The account needs these capabilities:

* `timeSeriesAcl:READ:` **required** to find and plot time series.

* `groupsAcl:LIST:` **required** to verify Grafana connectivity.

* `projectsAcl:LIST:` **required** to verify Grafana connectivity.

* `assetsAcl:READ:` **optional** to use template variables and select time series from an asset.

* `eventsAcl:READ:` **optional** to use annotations.

## Step 3: Install the Cognite Data Source for Grafana

To install the Cognite Data Source for Grafana:

> [tab] Grafana Enterprise
>
> **1. Sign in as administrator**
>
> Make sure you're signed in to Grafana as an administrator in your browser.
>
> **2. Install the plugin**
>
> Navigate to the [Cognite Data Source for Grafana plugin](https://grafana.com/grafana/plugins/cognitedata-datasource) and select **Install plugin**.

> [tab] Self-hosted Grafana
>
> **1. Follow installation instructions**
>
> Follow the instructions on the [Installation](https://grafana.com/grafana/plugins/cognitedata-datasource/?tab=installation) tab to install the plugin.

## Step 4: Configure the Cognite Data Source for Grafana

To configure the Cognite Data Source for Grafana:

**1. Sign in to Grafana**

In your browser, sign in to Grafana as an administrator.

**2. Add the Cognite data source**

In Grafana, navigate to **Configuration** > **Data sources** > **Add data source** > Search for "**Cognite**".

![Select data source plugin](https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/cdf/dashboards/grafana/grafana_config_select_datasource.png)

**3. Configure the data source**

Enter your **project name**, the **API URL** and select **Forward OAuth Identity**.

![Configure data source](https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/cdf/dashboards/grafana/grafana_configure_plugin.png)

> [!NOTE]
>
> The Grafana free tier doesn't allow you to set an identity provider for the whole Grafana instance, and you can not select a **Forward OAuth Identity**. Instead, you need to [set up a client credentials grant flow](#set-up-a-client-credentials-grant-flow) for each instance of the Cognite Data Source.

**4. Save and test the configuration**

Select **Save & Test** to validate your Cognite credentials.

**5. Verify the configuration**

**Verify** that the configuration is successful: Sign in to Grafana with a non-admin identity and [create a dashboard](https://docs.cognite.com/cdf/dashboards/guides/grafana/timeseries.md#create-a-dashboard) to confirm that regular users in your Microsoft Entra ID can access Grafana and work with data from CDF.

**Learn more** about managing Grafana at [grafana.com](https://grafana.com) and [community.grafana.com](https://community.grafana.com).

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

**1. Set up application registration**

Use an application registration with capabilities to access the target CDF project. If you don't have an application registration, follow the guide: [Register a custom web app in Microsoft Entra ID](https://docs.cognite.com/cdf/access/entra/guides/register_custom_webapp.md).

**2. Register Cognite API and CDF application**

Make sure that you have [registered the Cognite API and the CDF application in Microsoft Entra ID](https://docs.cognite.com/cdf/access/entra/guides/configure_cdf_azure_oidc.md).

**3. Configure required capabilities**

Configure the [required capabilities](https://docs.cognite.com/cdf/dashboards/guides/grafana/admin_oidc.md#step-2-decide-access-to-cdf-data).

**4. Add service principal to CDF group**

[Add the service principal to a CDF group](https://docs.cognite.com/cdf/access/entra/guides/add_service_principal.md#add-the-service-principal-to-a-cdf-group).

**5. Install the plugin**

Navigate to [Cognite Data Source for Grafana plugin](https://grafana.com/grafana/plugins/cognitedata-datasource) and select **Install plugin**.

Follow these steps to set up client credentials grant flow:

**1. Navigate to data sources**

In Grafana, navigate to Configuration > Data sources > Add data source.

**2. Select Cognite data source**

Search for **Cognite** and select Cognite Data Fusion data source.

**3. Configure OAuth2 client credentials**

1. Disable **Forward OAuth identity**.
2. Enable **OAuth2 client credentials**.
3. Enter the credentials.

**4. Validate credentials**

Select **Save & Test** to validate your Cognite credentials.

![Configure client credentials](https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/cdf/dashboards/grafana/config-client-credentials.png)
