# Configuring Workload Identity Federation for BigQuery

As an admin, you can enable users in your CARTO organization to connect to Google BigQuery using Workload Identity Federation, instead of using Service Account keys or Google OAuth. Once this integration is enabled, the option will be available for all users whenever they try to create a new [BigQuery connection](https://docs.carto.com/carto-user-manual/connections/bigquery).

{% hint style="info" %}
**What is Workload Identity Federation and how does it work?**

When you complete the integration, identities coming from CARTO (ie: CARTO users) will be recognized in your Google Cloud account as part of a *Workload Identity Pool*. You can then assign granular permissions to each of those CARTO users, using IAM rules directly in Google Cloud.

For example, you will be able to grant access to a BigQuery project for a specific set of CARTO users, or grant a specific permission to a specific group inside CARTO.

Learn more about [Workload Identity Federation in Google Cloud](https://cloud.google.com/iam/docs/workload-identity-federation).
{% endhint %}

{% hint style="success" %}
**Workload Identity Federation is recommended over using Service Account keys**. Google discourages the use of Service Account keys whenever possible, and authenticating your connections via Workload Identitiy Federation can provide the same flexibility.
{% endhint %}

## Requisites

{% hint style="warning" %}
To finish the integration, you will need at least the **`workloadIdentityPoolAdmin`** role in Google Cloud, or an equivalent set of permissions. Additionally, you will need to be able to grant BigQuery permissions to the resulting identity pool.
{% endhint %}

## Integrate CARTO via Workload Identity Federation

To start the process, navigate to **Settings > Advanced Settings > Integrations,** where you'll find an integration for Workload Identity Federation. Click on "Add" to begin the process. The integration configuration panel will open. Continue with the steps in this guide.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-468bb901d19edfffa764c1ce9952abd545beb36c%2FScreenshot%202025-01-08%20at%2012.33.32.png?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-2b0a58ac81a24b1a842805bc0ffd482d61c2b283%2FScreenshot%202025-01-08%20at%2012.57.02.png?alt=media" alt=""><figcaption></figcaption></figure>

### Get the Issuer URL and the JWK JSON from CARTO

Copy the **Issuer URL** and download the **JWK JSON** provided by CARTO. You will need these two items during the next steps in the Google Cloud console.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-9c0ec1c0683cbc8182cb9ce99c7379c5e7c49b2a%2FScreenshot%202025-01-08%20at%2013.00.11.png?alt=media" alt=""><figcaption></figcaption></figure>

### Create a Workload Identity Pool for CARTO in Google Cloud

Now, open your Google Cloud console and navigate to **IAM & Admin > Workload Identity Pools.** Click on **Create Pool.**

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-1da1759b4338b65af7b8448041558c7d3a3b8b04%2FScreenshot%202025-01-08%20at%2017.14.28.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

In the next step, you will need to define:

* **Name:** a user-facing name that will be used to identify this pool in Google Cloud Platform
* **Pool ID:** the internal ID that will be part of the final IAM identities.

You can also add a description. CARTO does not enforce any rule for the name or the pool ID, so you can define them in whatever way it is more clear for your organization.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-30144adc89c18d7d946f4f07872cdc8fc6b8969c%2FScreenshot%202025-01-08%20at%2017.16.21.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

Click on Continue, and you will be asked to add a provider to the pool. You will need to **create a new provider**, with the following characteristics:

* **OpenID Connect (OIDC)**
* **Provider name**: a user facing name that will be used to identify this provider in your Google Cloud organization. CARTO does not enforce any special rule about the provider name.
* **Issuer (URL):** introduce the Issuer URL field that you [previously obtained from CARTO](#get-the-issuer-url-and-the-jwk-json-from-carto).
* **JWK File (JSON):** upload the JWK JSON that you [previously downloaded from CARTO](#get-the-issuer-url-and-the-jwk-json-from-carto).

{% hint style="success" %}
**Important:**

* Make sure you're using the **Default audience.**
* Copy the **Default audience**, you will need it in the next steps.
  {% endhint %}

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-8ecec5f2d0a58e73fc7ceba5adae9e0442735f11%2FScreenshot%202025-01-08%20at%2017.18.30.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

Click on Continue, and the last step is to configure the **provider attribute mapping**. In this case, CARTO will be identifying users in this pool via their **email**, so we need to map:

`google.subject = assertion.sub`.

For **group-based permission management** (recommended for large deployments), also add:

`google.groups = assertion.groups`

This enables you to assign BigQuery permissions to groups in your identity provider, and users will automatically inherit those permissions based on their group memberships.

This additional mapping enables you to assign BigQuery permissions to user groups from your identity provider instead of managing permissions for each individual user. Users will automatically inherit permissions based on their group memberships.

Optionally, you could add Attribute Conditions so that only some users are able to use this pool integration, but in most cases you won't need any additional condition.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-693a137bb66920dc9ba86f7c277d591fbbabeb35%2Fimage.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

Click on Save — Your pool is now created and you're ready to grant permissions to identities from this pool.

### Grant permissions to identities from this pool

After you have created the Workload identity Pool for CARTO, you will notice new **IAM Principals** available from this pool, as well as logs and usage metrics.

{% hint style="info" %}
For **individual users**, the IAM Principal will look something like: `principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/CARTO_USER_EMAIL`

And for **groups**, assuming you configured the `google.groups` mapping:

`principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP_ID`
{% endhint %}

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-80311864071a7a86f3590ab6da874cf8ed81ee6a%2FScreenshot%202025-01-08%20at%2017.38.34.png?alt=media" alt=""><figcaption></figcaption></figure>

You can now go to any resource in Google BigQuery and grant permissions to users in this pool in two ways:

1. **Individual principals:** Grant permissions directly to specific users using their IAM Principal.
2. **Group-based permissions (recommended):** If you configured the `google.groups` mapping, you can grant permissions to groups from your identity provider. Users will automatically inherit permissions based on their group memberships. Make sure to use the [matching **SSO Group ID** found in CARTO](https://docs.carto.com/carto-user-manual/settings/users-and-groups/managing-user-groups).

{% hint style="warning" %}
To get started with your first connection, grant the minimum required permissions (`bigquery.dataEditor` and `bigquery.user` ) to your own CARTO user from the pool, in the GCP billing project you will connect in CARTO.
{% endhint %}

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-ac99f0061e8d73ff4c0d915d75a9926f477c8754%2FScreenshot%202025-01-08%20at%2017.47.02.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To give a specific permission or role to all CARTO users, you can use a more global IAM Principal Set such as : `principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*`

Learn more about [IAM Principal Identifiers in Google Cloud](https://cloud.google.com/iam/docs/principal-identifiers).
{% endhint %}

This is the way your organization will manage permissions from now on, for all users using Workload Identity Federation to connect CARTO and BigQuery, so make sure you are familiar with it.

### Provide the Default Audience URL of the Pool to CARTO

Now that the Workload Identity Pool exists in Google Cloud, and you know how to manage and grant permissions to identities from this pool, let's finish the integration in CARTO.

To complete the configuration, paste the **Default Audience URL** you [obtained in the previous step](#create-a-workload-identity-pool-for-carto-in-google-cloud), confirm that you've [granted the required permissions](#grant-permissions-to-identities-from-this-pool), and click on Save.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-851ba2c50808aafe4ee4642a5d45d30bc9e80073%2FScreenshot%202025-01-08%20at%2017.58.55.png?alt=media" alt=""><figcaption></figcaption></figure>

Nice! You've successfully integrated CARTO and Google BigQuery via Workload Identity Federation. Now, all users in your organization can use this integration to create BigQuery connections.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-56b5c5ce72e6cf30bfd2bf10f78563fb0804ab5d%2FScreenshot%202025-01-08%20at%2018.01.05.png?alt=media" alt=""><figcaption></figcaption></figure>

## Create a connection and validate the setup

To validate that your integration is working, you can now create a [BigQuery connection using Workload Identity Federation](https://docs.carto.com/connections/bigquery#using-workload-identity-federation).