## How Atlan connects to Google BigQuery

URL: https://docs.atlan.com/apps/connectors/data-warehouses/google-bigquery/concepts/how-atlan-connects-to-google-bigquery

> Understand how Atlan securely connects to your Google BigQuery data warehouse to extract metadata.

Atlan connects to your Google BigQuery data warehouse to extract technical metadata while maintaining network security and compliance. You can choose Direct connectivity when BigQuery is available from the internet or Self-deployed runtime when connections must stay within your network perimeter.

## Connect via direct network connection

Atlan's Google BigQuery workflow establishes a direct connection to the BigQuery API from the Atlan SaaS tenant. Use this approach when the BigQuery API is available from the internet (public endpoint or Private Service Connect).

```mermaid
sequenceDiagram
 participant User as User
 participant Atlan as Atlan SaaS Tenant
 participant BigQuery as Google BigQuery

 User->>Atlan: Provide credentials (service account key or WIF details)
 Atlan->>BigQuery: Establish connection (HTTPS, port 443)
 Atlan->>BigQuery: Call BigQuery APIs for metadata (projects, tables, columns)
 BigQuery->>Atlan: Return metadata
 Atlan->>Atlan: Catalog results in Atlan
 User->>Atlan: View assets in Atlan
```

- Atlan's BigQuery workflow connects to the BigQuery API over HTTPS (port 443) from the Atlan SaaS tenant.
- You authenticate using a [service account key](https://docs.atlan.com/llms/connectors/google-bigquery/set-up-google-bigquery/llms.txt) or [Workload Identity Federation](https://docs.atlan.com/llms/connectors/google-bigquery/set-up-workload-identity-federation/llms.txt). Atlan uses these credentials to call BigQuery APIs for metadata only.
- For private connectivity, you can use Private Service Connect and provide the DNS name Atlan gives you so that traffic stays on your chosen network path.

For details on how direct connectivity works, see [Direct connectivity](https://docs.atlan.com/llms/catalog/connector-capabilities/direct-connectivity/llms.txt).

## Connect via self-deployed runtime

A runtime service deployed within your organization acts as a secure bridge between Atlan Cloud and Google BigQuery. This approach is required only when you want BigQuery API calls to originate from your network (for example, to satisfy egress or VPC requirements). 

```mermaid
sequenceDiagram
 participant User as User
 participant Atlan as Atlan SaaS Tenant
 participant Runtime as Self-Deployed Runtime 
 (customer infrastructure)
 participant SecretStore as Secret Store
 participant BigQuery as Google BigQuery

 User->>Atlan: Configure and schedule crawler workflow 
(non-sensitive connection details)
 Runtime->>Atlan: Poll for job execution request 
(via outbound HTTPS)
 Runtime->>SecretStore: Request sensitive credentials (service account key or WIF)
 SecretStore->>Runtime: Return credentials
 Runtime->>BigQuery: Call BigQuery APIs 
 (HTTPS, from your network)
 BigQuery->>Runtime: Return metadata 
 (projects, datasets, tables, columns)
 Runtime->>Atlan: Send metadata results 
 (via HTTPS)
 Atlan->>Atlan: Catalog results in Atlan
 User->>Atlan: View assets in Atlan
```

- The runtime maintains an outbound HTTPS connection to Atlan Cloud (port 443) and uses your environment's network to call the BigQuery API over HTTPS (port 443).
- When you create a crawler workflow, Atlan Cloud sends metadata extraction requests to the runtime. The runtime authenticates to Google Cloud (using a service account key or Workload Identity Federation from your secret store or GKE) and calls the BigQuery API, then returns metadata to Atlan Cloud.
- Your BigQuery project is only accessed from within your network; Atlan Cloud never receives your credentials when using Self-deployed runtime.

For details on how Self-Deployed Runtime works, see [SDR connectivity](https://docs.atlan.com/llms/catalog/connector-capabilities/sdr-connectivity/llms.txt).

## Authenticate with workload identity federation

When you use [Workload Identity Federation](https://docs.atlan.com/llms/connectors/google-bigquery/set-up-workload-identity-federation/llms.txt), Atlan accesses BigQuery with short-lived credentials instead of a service account key. The same authentication flow applies whether you use Direct connectivity or Self-deployed runtime; only the component that runs the connector (Atlan SaaS or the runtime in your network) differs. The following diagram shows the authentication-specific event flow.

```mermaid
sequenceDiagram
 participant User as User
 participant Atlan as Atlan SaaS Tenant
 participant GBQConnector as GBQ connector 
 (Atlan SaaS Tenant or SDR)
 participant AtlanOIDC as Atlan OIDC 
 (identity)
 participant WIF as Google Workload Identity Federation
 participant BigQuery as Google BigQuery API

 Note over User,WIF: One-time setup
 User->>Atlan: Create OAuth client 
 (client ID, secret)
 User->>WIF: Create WIF pool, OIDC provider (Atlan issuer), 
 SA impersonation

 Note over GBQConnector,BigQuery: At job execution time
 GBQConnector->>AtlanOIDC: Request OIDC token 
 (OAuth client credentials)
 AtlanOIDC->>GBQConnector: Issue OIDC token 
 (signed, audience = client ID)
 GBQConnector->>WIF: Present OIDC token 
 (token exchange)
 WIF->>WIF: Validate token 
 (issuer, audience, attributes)
 WIF->>GBQConnector: Return short-lived GCP credentials 
 (SA impersonation)
 GBQConnector->>BigQuery: Call BigQuery APIs 
 (HTTPS, with short-lived credentials)
 BigQuery->>GBQConnector: Return metadata 
 (projects, datasets, tables, columns)
```

- **One-time setup**: You create an OAuth client in Atlan (client ID and secret) and a workload identity pool in Google Cloud with an OIDC provider that trusts your Atlan tenant's issuer. You configure attribute mapping and grant the pool permission to impersonate a Google Cloud service account that has BigQuery access. No service account key is stored.

- **At crawl time**: The Atlan connector (SaaS or runtime) requests an OIDC token from Atlan's identity using the OAuth client credentials. It sends this token to Google Workload Identity Federation. WIF validates the token and returns short-lived Google Cloud credentials for the impersonated service account. The connector then calls the BigQuery API with those credentials. Tokens and short-lived credentials aren't stored long-term.

This flow keeps long-lived keys out of the connector; only the OAuth client secret (in Atlan) and the WIF configuration (in GCP) are required for ongoing access.

## Authentication and data access

- **Authentication**: Atlan supports [service account keys](https://docs.atlan.com/llms/connectors/google-bigquery/set-up-google-bigquery/llms.txt) and [Workload Identity Federation](https://docs.atlan.com/llms/connectors/google-bigquery/set-up-workload-identity-federation/llms.txt). 

- **Metadata only**: Atlan uses BigQuery APIs to read metadata (projects, datasets, tables, views, columns, routines). For data preview or querying, Atlan runs read-only jobs; the permissions you grant to the service account control what Atlan can access.

- **Credential handling**: In Direct connectivity, Atlan encrypts credentials at rest and in transit. In Self-deployed runtime, credentials stay in your perimeter; the runtime reads them from your secret store (for example, GCP Secret Manager or HashiCorp Vault) and Atlan Cloud never stores them.

## See also

* [Direct connectivity](https://docs.atlan.com/llms/catalog/connector-capabilities/direct-connectivity/llms.txt): How Atlan connects directly to data sources
* [SDR connectivity](https://docs.atlan.com/llms/catalog/connector-capabilities/sdr-connectivity/llms.txt): How Self-Deployed Runtime connects to data sources
* [Set up Google BigQuery](https://docs.atlan.com/llms/connectors/google-bigquery/set-up-google-bigquery/llms.txt): Configure service account and permissions
* [Crawl Google BigQuery](https://docs.atlan.com/llms/connectors/google-bigquery/crawl-google-bigquery/llms.txt): Create a connection and run the crawler

---