Documentation Plugins Google BigQuery Configure

Configure the Google BigQuery data source

This document explains how to configure the Google BigQuery data source in Grafana.

Before you begin

Before configuring the data source, ensure you have:

• Grafana version: Plugin version 3.x requires Grafana 11.6.11 or later. On Grafana 12.x, the plugin also requires these minimum patch versions: 12.0.10, 12.1.7, or 12.2.5, depending on your minor release. For older Grafana versions, use plugin version 2.x (requires Grafana 10.4.8 or later) or 1.x.
• Grafana permissions: Organization administrator role to add data sources.
• Google Cloud APIs enabled: The following APIs must be enabled on each GCP project you query:
  • BigQuery API
  • Cloud Resource Manager API
• Google Cloud credentials: Depending on your authentication method, you need either a service account key file or Grafana running on Google Compute Engine with a default service account.
• Required GCP IAM roles: The service account (or impersonated service account) must have the following roles on each project it accesses:
  • BigQuery Data Viewer (roles/bigquery.dataViewer): read access to BigQuery data
  • BigQuery Job User (roles/bigquery.jobUser): permission to run BigQuery jobs
  • resourcemanager.projects.get permission: required for the project drop-down to populate in the query editor. This permission is included in the Browser role (roles/browser) or can be granted through a custom role.

Grant BigQuery Data Viewer and BigQuery Job User at the project level when you can. Those project-level roles cover querying and listing datasets in that project. They aren’t sufficient by themselves if you only grant access on individual datasets or tables:

• The query editor dataset drop-down uses the BigQuery datasets.list API, which returns only datasets the caller can get. If the service account isn’t a dataset READER (or doesn’t have bigquery.datasets.get on that dataset), the dataset doesn’t appear in the drop-down. Refer to datasets.list.
• Save & test can still succeed. For IAM details beyond these roles, refer to BigQuery access control.

Key concepts

If you’re new to Google Cloud or BigQuery, these terms appear throughout the configuration:

Add the data source

To add the Google BigQuery data source:

1. Click Connections in the left-side menu.
2. Click Add new connection.
3. Type BigQuery in the search bar.
4. Select Google BigQuery.
5. Click Add new data source.

Configure settings

Authentication

The Google BigQuery data source supports multiple authentication methods. Choose the method that best fits your deployment environment.

Google Service Account key

Use this method when running Grafana outside of Google Cloud Platform, or when you need explicit credentials.

To configure service account authentication:

1. Create a Google Cloud Platform (GCP) Service Account.
2. Assign the following roles to the service account:
   • BigQuery Data Viewer - Provides read access to BigQuery data
   • BigQuery Job User - Allows running BigQuery jobs
3. Create and download a JSON key file for the service account. Google Cloud Console provides a .json key. P12 keys aren’t supported.
4. In the data source configuration, select Google JWT File as the authentication type.
5. Upload the JSON key file or paste its contents.

GCE default service account

Use this method when running Grafana on a Google Compute Engine (GCE) virtual machine.

When Grafana runs on a GCE virtual machine, it can automatically retrieve the default project ID and authentication token from the metadata server. To use this method:

1. Ensure your virtual machine has a service account configured as the default account.
2. Assign the service account the BigQuery Data Viewer and BigQuery Job User roles.
3. In the data source configuration, select GCE Default Service Account as the authentication type.

Service account impersonation

Use service account impersonation when you need to delegate access to BigQuery without distributing service account keys with broad permissions. With impersonation, the key stored in Grafana has minimal permissions. It can only generate short-lived tokens for a separate service account that has BigQuery access. This means the stored credentials cannot directly read data, reducing risk if they are compromised. This is the recommended secure authentication method for connecting Grafana Cloud to BigQuery.

Service account impersonation involves two service accounts:

• Authenticating service account: The service account whose JSON key is uploaded to Grafana. This account’s only permission is to create access tokens for the impersonated account. It requires the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).
• Impersonated service account: The service account that has permissions to read data from BigQuery. Grafana assumes this account’s identity to run queries. It requires the BigQuery Data Viewer and BigQuery Job User roles.

Configure GCP permissions

Before configuring the data source in Grafana, set up the required permissions in GCP. Replace AUTH_SA, IMPERSONATED_SA, and PROJECT_ID with your values.

Grant the authenticating service account permission to create tokens for the impersonated service account:

Bash Copy

gcloud iam service-accounts add-iam-policy-binding \
  IMPERSONATED_SA@PROJECT_ID.iam.gserviceaccount.com \
  --member="serviceAccount:AUTH_SA@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountTokenCreator"

Grant the impersonated service account BigQuery access:

Bash Copy

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:IMPERSONATED_SA@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:IMPERSONATED_SA@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"

Configure the data source in Grafana

To configure service account impersonation in the data source settings:

1. In the Authentication section, select Google JWT File as the authentication type.
2. Upload the JSON key file for the authenticating service account.
3. Under Service account impersonation, turn on Enable.
4. Enter the full email address of the impersonated service account in Service account to impersonate.
5. Click Save & test to verify the connection.

Workload Identity Federation

Use Google Cloud Workload Identity Federation (WIF) to let Grafana users authenticate to BigQuery with an external identity provider (such as Okta or another OIDC provider) instead of a service account key.

Configuring Workload Identity Federation involves three systems: Google Cloud, your Grafana Cloud stack, and the data source itself.

In Google Cloud

1. Create a Workload Identity Pool and Provider that trusts your OIDC identity provider. When configuring the provider, set up attribute mappings so that google.subject maps to the relevant claim from your identity provider (for example, assertion.sub; the exact mapping depends on your provider’s claim format).
2. Grant the BigQuery permissions needed to run queries. How you grant them depends on whether you use service account impersonation:
   • Without impersonation: grant the WIF pool principal directly:
     • BigQuery Data Viewer
     • BigQuery Job User
   • With impersonation: create a service account, grant it those same roles, then grant the WIF pool principal the Service Account Token Creator role on that service account.

In Grafana Cloud

1. Configure your Grafana Cloud stack’s SSO integration against the same OIDC provider, so the signed-in user’s identity is available for Grafana Cloud to exchange for a Google Cloud access token before the request reaches the plugin. Refer to Configure OAuth2 authentication for setup details.

In the data source configuration

1. Open the BigQuery data source settings and select Workload Identity Federation as the authentication type.

2. In the Workload Identity Pool Provider field, enter the full resource path of your provider: projects/<project-number>/locations/global/workloadIdentityPools/<pool-id>/providers/<provider-id>

   Note

   Use the project number (a numeric ID such as 123456789), not the project ID (such as my-project). You can find the project number on the Google Cloud Console home page.

3. If you set up service account impersonation, enter the service account email in the Service account email field. If you granted permissions directly to the WIF pool, leave this blank.

4. Enter the Default project where your BigQuery queries run.

Forward OAuth Identity

Use Forward OAuth Identity when you want to use Google OAuth authentication in Grafana with BigQuery.

To configure Forward OAuth Identity:

1. Configure Google OAuth authentication in Grafana.
2. Add the following scopes to the OAuth application:
   • https://www.googleapis.com/auth/bigquery (required)
   • https://www.googleapis.com/auth/drive (optional, for querying Google Sheets data)
3. In the data source configuration, select Forward OAuth Identity as the authentication type.
4. Enter the Default project where queries run.

Additional settings

Expand the Additional Settings section to configure optional settings.

Verify the connection

Click Save & test to verify the connection. A successful test displays the message “Data source is working”. If you encounter errors, refer to Troubleshooting.

Provision the data source

You can define the data source in YAML files as part of the Grafana provisioning system. For more information, refer to Provisioning Grafana data sources.

Service account key with private key in secure JSON

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: jwt
      clientEmail: <SERVICE_ACCOUNT_EMAIL>
      defaultProject: <DEFAULT_PROJECT_ID>
      tokenUri: https://oauth2.googleapis.com/token
    secureJsonData:
      privateKey: <PRIVATE_KEY>

Service account key with private key path

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: jwt
      clientEmail: <SERVICE_ACCOUNT_EMAIL>
      defaultProject: <DEFAULT_PROJECT_ID>
      tokenUri: https://oauth2.googleapis.com/token
      privateKeyPath: '/etc/secrets/bigquery.pem'

GCE default service account

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: gce

GCE default service account with service account impersonation

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: gce
      usingImpersonation: true
      serviceAccountToImpersonate: <SERVICE_ACCOUNT_EMAIL>
      defaultProject: <DEFAULT_PROJECT_ID>

Service account key with service account impersonation

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: jwt
      clientEmail: <AUTH_SERVICE_ACCOUNT_EMAIL>
      defaultProject: <DEFAULT_PROJECT_ID>
      tokenUri: https://oauth2.googleapis.com/token
      usingImpersonation: true
      serviceAccountToImpersonate: <IMPERSONATED_SERVICE_ACCOUNT_EMAIL>
    secureJsonData:
      privateKey: <PRIVATE_KEY>

Workload Identity Federation

Available on Grafana Cloud only.

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: workloadIdentityFederation
      workloadIdentityPoolProvider: projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL>/providers/<PROVIDER>
      wifServiceAccountEmail: <SERVICE_ACCOUNT_EMAIL> # optional
      defaultProject: <DEFAULT_PROJECT_ID>

Forward OAuth Identity

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: forwardOAuthIdentity
      defaultProject: <DEFAULT_PROJECT_ID>
      oauthPassThru: true

With additional settings

YAML Copy

apiVersion: 1
datasources:
  - name: BigQuery
    type: grafana-bigquery-datasource
    editable: true
    enabled: true
    jsonData:
      authenticationType: jwt
      clientEmail: <SERVICE_ACCOUNT_EMAIL>
      defaultProject: <DEFAULT_PROJECT_ID>
      tokenUri: https://oauth2.googleapis.com/token
      processingLocation: US
      MaxBytesBilled: 5242880
      restrictToAccessibleDatasets: true
      additionalAllowedDatasets: bigquery-public-data.samples
      serviceEndpoint: https://bigquery.googleapis.com/bigquery/v2/
    secureJsonData:
      privateKey: <PRIVATE_KEY>

Provisioning configuration reference

Provision with Terraform

You can provision the data source using the Grafana Terraform provider.

Service account key

hcl Copy

resource "grafana_data_source" "bigquery" {
  type = "grafana-bigquery-datasource"
  name = "BigQuery"

  json_data_encoded = jsonencode({
    authenticationType = "jwt"
    clientEmail        = "<SERVICE_ACCOUNT_EMAIL>"
    defaultProject     = "<DEFAULT_PROJECT_ID>"
    tokenUri           = "https://oauth2.googleapis.com/token"
  })

  secure_json_data_encoded = jsonencode({
    privateKey = file("path/to/service-account-key.pem")
  })
}

GCE default service account

hcl Copy

resource "grafana_data_source" "bigquery" {
  type = "grafana-bigquery-datasource"
  name = "BigQuery"

  json_data_encoded = jsonencode({
    authenticationType = "gce"
  })
}

With service account impersonation

hcl Copy

resource "grafana_data_source" "bigquery" {
  type = "grafana-bigquery-datasource"
  name = "BigQuery"

  json_data_encoded = jsonencode({
    authenticationType          = "gce"
    usingImpersonation          = true
    serviceAccountToImpersonate = "<SERVICE_ACCOUNT_EMAIL>"
    defaultProject              = "<DEFAULT_PROJECT_ID>"
  })
}

Workload Identity Federation

Available on Grafana Cloud only.

hcl Copy

resource "grafana_data_source" "bigquery" {
  type = "grafana-bigquery-datasource"
  name = "BigQuery"

  json_data_encoded = jsonencode({
    authenticationType           = "workloadIdentityFederation"
    workloadIdentityPoolProvider = "projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL>/providers/<PROVIDER>"
    wifServiceAccountEmail       = "<SERVICE_ACCOUNT_EMAIL>" # optional
    defaultProject               = "<DEFAULT_PROJECT_ID>"
  })
}

With additional settings

hcl Copy

resource "grafana_data_source" "bigquery" {
  type = "grafana-bigquery-datasource"
  name = "BigQuery"

  json_data_encoded = jsonencode({
    authenticationType = "jwt"
    clientEmail        = "<SERVICE_ACCOUNT_EMAIL>"
    defaultProject     = "<DEFAULT_PROJECT_ID>"
    tokenUri           = "https://oauth2.googleapis.com/token"
    processingLocation = "US"
    MaxBytesBilled               = 5242880
    restrictToAccessibleDatasets = true
    additionalAllowedDatasets    = "bigquery-public-data.samples"
    serviceEndpoint              = "https://bigquery.googleapis.com/bigquery/v2/"
  })

  secure_json_data_encoded = jsonencode({
    privateKey = var.bigquery_private_key
  })
}

For more information, refer to the Grafana Terraform provider documentation.

Import queries from DoiT International BigQuery plugin

If you previously used the DoiT International BigQuery community plugin, you can import your existing queries into the Grafana BigQuery data source.

To import queries:

1. Open the dashboard containing queries from the DoiT International plugin.
2. Edit each panel and change the data source to Grafana BigQuery.
3. Save the dashboard.

Related resources

• Google BigQuery documentation
• Create a service account
• BigQuery IAM roles
• Grafana provisioning documentation