Least-Privilege Access

For most teams, the standard setup is the simplest path. It grants BigQuery User at the project level. But security-conscious organizations, especially those with shared GCP projects or compliance requirements, want to scope a third-party integration as narrowly as possible. Least-privilege access is the configuration we recommend for enterprise security reviews. With it, Detrics:

• Can fully operate transfers and schema migrations
• Has data access to only the BigQuery dataset you share with it, and nothing else
• Cannot see, list, or read any other dataset, table, or bucket in your project, not even their names

It takes a few extra steps to set up compared to the standard path, because you pre-create and share the resources yourself instead of letting Detrics provision them. Those extra steps are exactly what guarantees the scoping.

​

Before You Start

Have these ready:

• A GCP project where Detrics will load your data.
• Someone with IAM Admin on the project. Granting a project-level role requires permission to edit the project’s IAM policy (Project IAM Admin or Owner). If that isn’t you, you can email these exact steps to whoever manages the project. In Detrics, open the BigQuery destination setup and use Send setup instructions.
• The Detrics service account email. It’s shown on your destination page in Detrics. Create the BigQuery destination in Detrics first, since you’ll need this email for the grants below.

​

Why a Project-Level Grant Is Still Needed

Detrics’ write path needs two distinct kinds of permission, and it is important to understand the difference:

1. The ability to submit jobs to BigQuery. This covers queries, load jobs, and DML that actually move your marketing data into BigQuery. In BigQuery, running a job is a project-level action; it cannot be scoped to a single dataset.
2. The ability to read and write data. This can be scoped, and under least-privilege it is scoped to only the dataset you share.

So this setup does include one project-level role: roles/bigquery.jobUser. In other words: the project-level scope is a mechanical requirement for loading data, not a window into your project. All actual data access comes exclusively from the dataset-level grant you make on the dataset you share. Combining a project-level jobUser with a dataset-level dataEditor gives Detrics exactly what it needs and nothing more. Image storage, if you enable it, works the same way: a bucket-scoped grant lets Detrics write creatives to exactly one bucket and nowhere else.

​

Required Roles

Each Detrics destination writes to exactly one BigQuery dataset. If you set up multiple destinations, repeat the dataset-level grant for each one’s dataset.

​

Step-by-Step Setup

​

1. Pre-create the BigQuery Dataset

In Google Cloud Console:

1. Navigate to BigQuery
2. Click your project → Create Dataset
3. Set the Dataset ID (e.g., detrics_marketing) and Data location
4. Click Create Dataset

​

2. Grant BigQuery Job User at the Project Level

1. Go to Google Cloud Console → IAM & Admin → IAM
2. Make sure the correct project is selected in the top dropdown
3. Click Grant Access
4. In New principals, paste your Detrics service account email (shown on your destination page)
5. In Select a role, search for and select BigQuery Job User
6. Click Save

​

3. Grant BigQuery Data Editor on Your Dataset

1. In BigQuery Console, click your dataset (the one you created in step 1)
2. Click SHARING → Permissions
3. Click ADD PRINCIPAL
4. Paste the Detrics service account email
5. Select role BigQuery Data Editor
6. Click Save

If you have multiple Detrics destinations, repeat this step for each destination’s dataset. Detrics has data access to a dataset only after you complete this grant for it.

​

4. (Optional) Enable Image Persistence

If you want Detrics to store ad-creative images alongside your data, it is done with a bucket-scoped grant that keeps everything off any project-level Storage role. Skip this step entirely if you don’t use image persistence.

1. Pre-create the bucket. In Cloud Storage, click Create. Use the bucket name you’ll configure in Detrics, pick the same region as your dataset, and enable Uniform bucket-level access.
2. Grant Detrics a bucket-scoped role. On the bucket’s Permissions tab, click Grant Access, paste your Detrics service account email, select the role Storage Object User, and click Save.

​

Public or private bucket, your call

Detrics stores every creative image in your bucket the same way regardless of this choice. What changes is the URL form Detrics writes next to each row — and therefore who can see the image in a dashboard or report:

• Public bucket → Detrics writes a public URL (https://storage.googleapis.com/…). The image renders for anyone viewing the report, including external or shared viewers. Make it public on the bucket’s Permissions tab: click Grant Access, add the principal allUsers, and assign the role Storage Object Viewer.
• Private bucket → Detrics writes an authenticated URL (https://storage.cloud.google.com/…). The image renders only for viewers signed into Google with IAM read access to the bucket — typically your own team inside BigQuery or Looker. Everyone else gets a Google sign-in screen instead of the image.

We recommend public: a public bucket exposes nothing sensitive (it holds only ad creatives, which are already public in each platform’s ad library) and is the only option that renders images for external report viewers. Choose private only if your org policy forbids public buckets and your audience is your internal team.

​

Bucket access mode

On the destination’s Image Storage card you control which URL form Detrics writes:

• Auto (default) — Detrics detects whether the bucket is publicly readable (when you create the destination, on every Test Connection, and at the start of each sync) and picks the matching URL form for you. If you grant or revoke allUsers later, it follows on the next sync.
• Public — always write the public URL. Use when you know the bucket is public.
• Private — always write the authenticated URL. Use when your bucket is intentionally private.

​

5. Test the Connection

In Detrics, open your destination and click Test Connection. The test runs through these stages:

• BigQuery Connectivity
• Project Access
• Dataset Permissions (verifies your pre-created dataset)
• Table Permissions (creates and deletes a test table inside the dataset)
• Job Permissions (loads and reads a test row)

If you enabled image persistence, the test also verifies it can write to your pre-created bucket. If any stage fails, see Troubleshooting below.

​

What Detrics Can and Cannot Do

With this configuration, Detrics has access to a precise, verifiable subset of your project.

​

Can do (within the dataset and bucket you shared, only)

• Create, alter, and drop tables
• Insert, update, and delete rows
• Read data from tables it created
• Run queries that reference only the dataset you shared
• Run schema migrations using its safe temp-table-then-rename pattern
• Upload, replace, and remove ad-creative images in the granted bucket (only if image persistence is enabled)

​

Cannot do (anywhere else in your project)

• See the existence or names of datasets you did not share
• List tables or read metadata in datasets you did not share
• Query data from any dataset you did not share
• Create or delete datasets
• Access any other Cloud Storage bucket
• Read IAM policies, billing data, or any other GCP resource

The project-level BigQuery Job User role does not change any of this. It grants the ability to run jobs, not to read data. You can confirm exactly what permissions the service account has at any time using the IAM Policy Troubleshooter in the GCP Console.

​

Pre-creating the Resources

In the standard setup, Detrics auto-creates the dataset (and the image bucket) on first use. Under least-privilege, those creation permissions are intentionally not granted, because the ability to create datasets is project-wide and would broaden Detrics’ reach. So you create the dataset yourself once during setup, and the bucket too if you use image persistence. This is the main reason least-privilege has a few extra steps. Day-to-day operation needs no further intervention from you: Detrics manages tables and rows within the dataset, and image objects within the bucket, on its own. Each Detrics destination uses its own dataset. If you add another destination later, pre-create its dataset and repeat the dataset-level grant.

​

Revoking Access

To disconnect Detrics, remove the role bindings you granted:

1. Project: go to IAM & Admin → IAM, find the Detrics service account, and remove its BigQuery Job User binding.
2. Dataset: open the dataset → SHARING → Permissions, and remove the BigQuery Data Editor binding for the service account.
3. Bucket (only if you set up image persistence): open the bucket → Permissions, and remove the Storage Object User binding for the service account.

Once the grants are removed, Detrics can no longer run jobs or touch your data.

​

Troubleshooting

​

When to Use This Setup

Choose least-privilege when:

• Your GCP project is shared with other workloads or contains sensitive data
• Your security or compliance team requires least-privilege access for third-party integrations
• You want a defense-in-depth posture even if Detrics’ credentials were ever compromised

Choose the standard setup when:

• The GCP project is dedicated to Detrics (no other data lives there)
• You’d rather not pre-create the dataset (and bucket) yourself
• Convenience matters more than scope-limited access in your context

Both setups are fully supported, and both support image persistence. You can also start with the standard setup and move to least-privilege later: remove the broader project role, pre-create the resources, and add the scoped grants.