Skip to main content
BigQuery hero Openlayer integrates with Google BigQuery so you can run data quality tests directly on your BigQuery tables.

​
Authentication methods

Openlayer supports two ways to authenticate with BigQuery:
MethodHow it worksBest for
Service Account ImpersonationOpenlayer impersonates a service account you own — no keys are exchangedOrganizations that prefer keyless, auditable access (Google-recommended)
Service Account KeyYou upload a service account key JSON file directly to OpenlayerTeams that already manage service account keys or need a quicker setup
If you are unsure which method to choose, Service Account Impersonation is Google’s recommended approach because it avoids long-lived credentials.

​
Prerequisites

Both methods require:

​
Setup Guide

​
Step 1: Create a service account and grant roles

Create a dedicated service account in your GCP project for Openlayer to use: 
# Set your project ID
export PROJECT_ID="your-project-id"

# Create the service account
gcloud iam service-accounts create openlayer-bigquery \
  --project=$PROJECT_ID \
  --description="BigQuery access for Openlayer" \
  --display-name="Openlayer BigQuery Access"
Grant the following roles to the new service account:
  • roles/bigquery.jobUser: run queries
  • roles/bigquery.dataViewer: read table data
  • roles/bigquery.metadataViewer: read metadata
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:openlayer-bigquery@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"

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

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

​
Step 2: Configure authentication and connect

In your Openlayer workspace, go to Data sources, select BigQuery, and click Connect. Choose your authentication method and follow the corresponding tab:

​
Allow Openlayer to impersonate your service account

Grant Openlayer’s service account permission to impersonate yours:
gcloud iam service-accounts add-iam-policy-binding \
  openlayer-bigquery@$PROJECT_ID.iam.gserviceaccount.com \
  --member="serviceAccount:impersonator@unbox-ai.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountTokenCreator"
This ensures Openlayer can act as your service account without exchanging keys.

​
Fill in the connection fields

  • BigQuery target principal: your service account email (e.g. openlayer-bigquery@your-project-id.iam.gserviceaccount.com)
  • BigQuery billing project: your GCP project ID (where query costs are billed)
  • Name: a descriptive label for this connection
Configure BigQuery connection with impersonation

​
Step 3: Configure your table

After the connection is created, configure the table you want to monitor:
  • Project: GCP project containing the table
  • Dataset: dataset name
  • Table: table name
  • Data source name: a descriptive name for this table in Openlayer
Configure BigQuery table

​
Optional: ML-specific settings

If the table contains ML outputs, you can provide additional context:
  • Class names
  • Feature names
  • Categorical feature names
These let Openlayer run model-aware tests, such as drift or performance monitoring.

​
Multiple connections

You can create multiple BigQuery connections in the same Openlayer workspace — each with its own authentication method, billing project, and service account. This is useful when:
  • Different teams own different GCP projects
  • You want to isolate billing across data sources
  • Different tables require different access permissions
Each connection is independent, so you can mix Service Account Impersonation and Service Account Key connections as needed.

​
Security considerations

No keys exchanged — Openlayer never holds long-lived credentials for your project.Auditable — every impersonated action is logged in Cloud Audit Logs under both the impersonator and target accounts.Revocable — remove the serviceAccountTokenCreator role to revoke access instantly.
Encrypted at rest — uploaded keys are encrypted and stored securely in Openlayer’s infrastructure.Rotate regularly — set a reminder to rotate keys at least every 90 days.Least privilege — only grant the three BigQuery roles listed above. Avoid roles/owner or roles/editor.Revoke if compromised — delete the key in the GCP console and generate a new one.

​
Troubleshooting

  • Permission errors → confirm the roles above are granted to your service account.
  • Impersonation errors → ensure roles/iam.serviceAccountTokenCreator is granted to Openlayer’s service account (impersonator@unbox-ai.iam.gserviceaccount.com).
  • Invalid key errors → verify the uploaded JSON file is the correct service account key and has not been revoked.
  • Billing errors → check that the billing project ID is correct and that the service account has bigquery.jobUser on that project.