# Setup and administration with OpenID Connect

This article explains how you can use the Cognite Data Source for Grafana to use a Cognite Data Fusion (CDF) project as a data source in Grafana to query, explore and visualize data that is stored in CDF.

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

In this article:

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 Azure AD and your Grafana instance.

# Before you start

Make sure that you have administrator access to your Grafana instance. We support the Enterprise (opens new window) and the self-hosted (opens new window) 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 Azure AD

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 Azure AD as the IdP.

  1. Make sure that you have already registered the Cognite API and the CDF portal application in Azure AD.

  2. 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 Azure AD and enable Azure AD authentication in Grafana (opens new window).

    NOTE: Use these permission scopes in the Grafana configuration file (opens new window):

    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. Make sure that you close the Grafana configuration file after you have updated it, and the restart the Grafana service.

  4. Sign in to Grafana to verify that the configuration is successful.

    Sign in to Grafana

# Step 2: Decide access to CDF data

  1. To decide what access users should have to data in CDF, follow the steps in Link Azure AD and CDF groups.

# Step 3: Install the Cognite Data Source for Grafana

To install the Cognite Data Source for Grafana:

# Step 4: Configure the Cognite Data Source for Grafana

To configure the Cognite Data Source for Grafana:

  1. In your browser, log in to Grafana as an administrator.

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

    Select data source plugin

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

    Configure data source

    NOTE

    The Grafana free tier does not 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 for each instance of the Cognite Data Source.

  4. Click Save & Test to validate your Cognite credentials.

  5. Verify that the configuration is successful: Sign in to Grafana with a non-admin identity and create a dashboard to confirm that regular users in your Azure AD can access Grafana and work with data from CDF.

Learn more about managing Grafana at grafana.com (opens new window) and community.grafana.com (opens new window).

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

  1. Navigate to your Grafana instance.

  2. Open Data Source settings.

  3. Disable Forward OAuth identity.

  4. Enable OAuth2 client credentials.

  5. Fill in the necessary credentials.

  6. Click Save & Test to validate your Cognite credentials.

    Configure client credentials

Last Updated: 8/30/2021, 12:38:55 PM