## Set up Workload Identity Federation

URL: https://docs.atlan.com/apps/connectors/data-warehouses/google-bigquery/how-tos/set-up-workload-identity-federation

> Configure Workload Identity Federation (WIF) to enable Atlan to authenticate with Google BigQuery without using service account keys.

Workload Identity Federation (WIF) enables Atlan to authenticate with Google BigQuery without storing long-lived service account keys. Instead of using a service account JSON key file, WIF uses short-lived tokens that Atlan exchanges through an OAuth flow.

This approach provides enhanced security by:

- Eliminating the need to manage and rotate service account keys
- Using short-lived tokens instead of persistent credentials
- Enabling fine-grained access control through attribute conditions

## Prerequisites

Before you begin, make sure you have:

- Atlan admin access to create OAuth clients
- Google Cloud IAM administrator access to create workload identity pools and configure service account impersonation
- A service account with the [required BigQuery permissions](https://docs.atlan.com/llms/connectors/google-bigquery/set-up-google-bigquery/llms.txt) already created
- Your Atlan tenant URL (for example, `https://your-company.atlan.com`)

For more information on Workload Identity Federation, see [Google Cloud's Workload Identity Federation documentation](https://cloud.google.com/iam/docs/workload-identity-federation).

## Create OAuth client in Atlan

Create an OAuth client in Atlan for use when authenticating with Google Cloud's Workload Identity Federation.

1. In Atlan, navigate to **Settings** > **OAuth Clients**.
2. Click **Create OAuth Client**.
3. For _Description_, enter a meaningful name for the OAuth client—for example, `BigQuery WIF Integration`.
4. Click **Create**.
5. Copy and securely store the following values. You need these when configuring WIF in Google Cloud and when creating the crawler:
 - **OAuth Client ID**
 - **OAuth Client Secret**

 The client secret is shown only once; store it securely because you can't retrieve it later.

## Configure workload identity federation in Google Cloud

Configure a workload identity pool in Google Cloud to trust tokens issued by your Atlan tenant.

### Google Cloud console

### Create workload identity pool

1. Open the [Google Cloud console](https://console.cloud.google.com).
2. From the left menu under _IAM & Admin_, click **Workload Identity Federation**.
3. Click **Create Pool**.
4. For _Name_, enter a name for the pool—for example, `atlan-wif-pool`.
5. For _Description_, enter a description—for example, `Workload Identity Pool for Atlan BigQuery integration`.
6. Click **Continue**.

### Add OIDC provider

1. For _Select provider_, click **OpenID Connect (OIDC)**.
2. For _Provider name_, enter a name—for example, `atlan-oidc-provider`.
3. For _Issuer (URL)_, enter your Atlan tenant's OIDC issuer URL:
 ```
 https://<tenant>.atlan.com/auth/realms/default
 ```
 Replace `<tenant>` with your Atlan tenant name.
4. For _Allowed audiences_, click **Allowed audiences** and enter the OAuth Client ID you created in Atlan.
5. Click **Continue**.

### Configure attribute mappings

1. For _google.subject_, enter `assertion.sub`.
2. Click **Add Mapping** and add the following attribute mapping:
 - For _Google attribute_, enter `attribute.audience`.
 - For _OIDC attribute_, enter `assertion.aud`.
3. Click **Save**.

### Grant service account access

After creating the pool, grant access to the service account that has BigQuery permissions.

1. In the workload identity pool details page, click **Grant Access**.
2. For _Service account_, select the service account that has the [required BigQuery permissions](https://docs.atlan.com/llms/connectors/google-bigquery/set-up-google-bigquery/llms.txt).
3. For _Attribute name_, select **audience**.
4. For _Attribute value_, enter the OAuth Client ID you created in Atlan.
5. Click **Save**.

### Get WIF pool provider ID

After configuration, you need the full provider resource name for the Atlan crawler configuration.

1. In the workload identity pool details page, click the provider you created.
2. Copy the **Provider resource name**. Format:
 ```
 //iam.googleapis.com/projects/<project-number>/locations/global/workloadIdentityPools/<pool-id>/providers/<provider-id>
 ```

### Google Cloud CLI

### Prerequisites

Set up the Google Cloud CLI in any one of the following development environments:

- **Cloud Shell**: To use an online terminal with the gcloud CLI already set up, activate Cloud Shell:
 - To launch a Cloud Shell session from the Google Cloud console, open the [Google Cloud console](https://console.cloud.google.com), and from the top right, click the **Activate Cloud Shell** icon.
 - A Cloud Shell session starts and displays a command-line prompt. It can take a few seconds for the session to initialize.
- **Local shell**: To use a local development environment, [install](https://cloud.google.com/sdk/docs/install) and [initialize](https://cloud.google.com/sdk/docs/initializing) the gcloud CLI.

### Create workload identity pool

Run the following command to create a workload identity pool:

```shell
gcloud iam workload-identity-pools create atlan-wif-pool \
 --project=<project_id> \
 --location="global" \
 --description="Workload Identity Pool for Atlan BigQuery integration" \
 --display-name="Atlan WIF Pool"
```

- Replace `<project_id>` with your Google Cloud project ID.

### Add OIDC provider

Run the following command to add an OIDC provider to the pool:

```shell
gcloud iam workload-identity-pools providers create-oidc atlan-oidc-provider \
 --project=<project_id> \
 --location="global" \
 --workload-identity-pool="atlan-wif-pool" \
 --display-name="Atlan OIDC Provider" \
 --attribute-mapping="google.subject=assertion.sub,attribute.audience=assertion.aud" \
 --issuer-uri="https://<tenant>.atlan.com/auth/realms/default" \
 --allowed-audiences="<oauth_client_id>"
```

- Replace `<project_id>` with your Google Cloud project ID.
- Replace `<tenant>` with your Atlan tenant name.
- Replace `<oauth_client_id>` with the OAuth Client ID you created in Atlan.

### Grant service account access

Run the following command so the workload identity pool can impersonate the service account:

```shell
gcloud iam service-accounts add-iam-policy-binding <service_account_email> \
 --project=<project_id> \
 --role="roles/iam.workloadIdentityUser" \
 --member="principalSet://iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/atlan-wif-pool/attribute.audience/<oauth_client_id>"
```

- Replace `<service_account_email>` with the email of your service account that has BigQuery permissions.
- Replace `<project_id>` with your Google Cloud project ID.
- Replace `<project_number>` with your Google Cloud project number.
- Replace `<oauth_client_id>` with the OAuth Client ID you created in Atlan.

### Get WIF pool provider ID

Run the following command to get the full provider resource name:

```shell
gcloud iam workload-identity-pools providers describe atlan-oidc-provider \
 --project=<project_id> \
 --location="global" \
 --workload-identity-pool="atlan-wif-pool" \
 --format="value(name)"
```

The output is in the following format:
```
projects/<project-number>/locations/global/workloadIdentityPools/atlan-wif-pool/providers/atlan-oidc-provider
```

When configuring the crawler, prepend `//iam.googleapis.com/` to this value.

## Values required for crawler configuration

After completing the setup, you have the following values needed to [configure the BigQuery crawler](https://docs.atlan.com/llms/connectors/google-bigquery/crawl-google-bigquery/llms.txt):

| Value | Description | Example |
|-------|-------------|---------|
| Project ID | Your Google Cloud project ID | `my-gcp-project` |
| Service Account Email | Email of the service account with BigQuery permissions | `atlan-user@my-gcp-project.iam.gserviceaccount.com` |
| WIF Pool Provider ID | Full resource name of the WIF provider | `//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/atlan-wif-pool/providers/atlan-oidc-provider` |
| Atlan OAuth Client ID | OAuth Client ID created in Atlan | `atlan-oauth-client-id` |
| Atlan OAuth Client Secret | OAuth Client Secret created in Atlan | `atlan-oauth-client-secret` |

## Troubleshooting

If you encounter authentication issues when running the crawler:

- Verify the issuer URL matches your Atlan tenant exactly, including the `/auth/realms/default` path.
- Confirm the allowed audience in the WIF provider matches the OAuth Client ID from Atlan.
- Check that the service account has the [required BigQuery permissions](https://docs.atlan.com/llms/connectors/google-bigquery/set-up-google-bigquery/llms.txt).
- Verify the attribute condition for service account impersonation uses the correct OAuth Client ID.

For more information, see [Google Cloud's Workload Identity Federation troubleshooting guide](https://cloud.google.com/iam/docs/troubleshooting-workload-identity-federation).

## Next steps

- [Crawl Google BigQuery](https://docs.atlan.com/llms/connectors/google-bigquery/crawl-google-bigquery/llms.txt): Create a connection and run the crawler using Workload Identity Federation authentication

---