## VPC Service Controls & allowlisting

URL: https://docs.atlan.com/apps/connectors/data-warehouses/google-bigquery/references/vpc-service-controls-and-allowlisting

> The Google services and VPC Service Controls ingress rules your security team must allow for Atlan to reach Google BigQuery.

BigQuery needs no IP allowlist - but if your organization wraps its projects in a VPC Service Controls perimeter, that fence blocks Atlan until your security team adds ingress rules. This page is written to be handed to that team.

## Do I need this page?

- **Yes**, if your Google Cloud organization uses VPC Service Controls (ask your security team). This is the largest source of hard-to-diagnose BigQuery failures.
- **No**, if there is no perimeter - Atlan connects with no allowlisting at all.
- The telltale error, anywhere it appears:

```
403 VPC Service Controls: Request is prohibited by organization's policy.
vpcServiceControlsUniqueIdentifier: <identifier>
```

## What to allow, by auth method

Have your security team adapt the rules below to your perimeter design.

| Google service | Needed for | Ingress rule identity |
|---|---|---|
| `bigquery.googleapis.com` | All crawling and mining (both auth methods) | Your Atlan **service account** (e.g. `atlan-user@example-project.iam.gserviceaccount.com`) |
| `sts.googleapis.com` | WIF only - token exchange | The **WIF principal** (`principalSet://iam.googleapis.com/…`) - *not* the service account |
| `iamcredentials.googleapis.com` | WIF only - service account impersonation | The **WIF principal** - *not* the service account |
| `cloudresourcemanager.googleapis.com` | Preflight permission checks (both methods) | Your Atlan service account; API must also be **enabled** in the project |

:::danger The WIF principal mistake

The most-repeated VPC-SC failure: writing the STS/IAM-Credentials ingress rules for the *service account*. Google evaluates those two calls against the **WIF principal** - the service account doesn't exist yet at that point in the handshake - so the rule never matches and WIF fails with `GCP STS error: status 403` even though "everything is allowlisted".

:::

## Restricting by method?

If your perimeter rules restrict individual API methods, these are the BigQuery methods Atlan's crawler needs:

```
bigquery.datasets.get bigquery.tables.get bigquery.tables.list
bigquery.routines.get bigquery.routines.list
bigquery.jobs.create bigquery.jobs.list
```

## Every project must be allowlisted - by project ID

VPC-SC ingress rules name specific projects. Two consequences:

- **There is no org-level shortcut.** Ingress rules cannot match "any project in my organization" - each project is listed individually.
- **Adding new BigQuery projects to an existing connection requires a perimeter update first.** Otherwise the crawler is denied on the new projects - and the workflow can *report success while silently skipping them*, so nobody notices for weeks. Make "update VPC-SC ingress rules" a standing step in your new-project checklist, and tell Atlan support too (Atlan may need to mirror the change on its side).

## How your security team can find the actual denial

Every VPC-SC error carries a unique identifier. The matching audit log names the blocked service, method, caller, and reason:

```
protoPayload.metadata.vpcServiceControlsUniqueIdentifier="<identifier-from-the-error>"
```

:::tip Look in the right project

These logs usually live in your organization's **centralized security/audit project or org-level log sink** - not in the BigQuery project itself. A `violationReason: NETWORK_NOT_IN_SAME_SERVICE_PERIMETER` entry naming an unfamiliar calling project is Atlan's tenant project - get its number from [Atlan support](https://docs.atlan.com/support/submit-request) and reference it in your ingress rule.

:::

## Egress rules - only for Lakehouse integration

Everything above is *ingress* (Atlan calling in). One feature needs an *egress* exception (your BigQuery calling out): the Atlan Lakehouse / Iceberg integration, where BigQuery reads files from an Atlan-managed Cloud Storage bucket. If you use it, your security team adds an egress rule allowing your BigQuery service identities to call `storage.googleapis.com` methods `google.storage.objects.get`, `google.storage.objects.list`, and `google.storage.buckets.get` against Atlan's GCP project (number via support). Details in [Special cases](https://docs.atlan.com/llms/connectors/google-bigquery/special-cases/llms.txt).

---