> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/ox-integrations/3rd-party-integrations/cloud-security/gcp-and-gke-1/gcp-workload-identity-federation.md).

# GCP Workload Identity Federation

Use this authentication method to connect OX to Google Cloud without creating or storing a service account key. Instead, OX authenticates by using Google Cloud Workload Identity Federation and short-lived credentials.

This is the recommended authentication method for new connections and for organizations that require a keyless authentication model.

## Prerequisites

* A Google Cloud project with IAM permissions to:
  * Create service accounts
  * Manage service account keys
* Enable required APIs (e.g., Compute Engine API, IAM API, Kubernetes Engine API).
* Optional: `gcloud` CLI installed and configured.

## Step 1: Enable Google Cloud APIs \[Google]

1. In the **Google Cloud Console**, navigate to **APIs & Services**.
2. In the left pane, select **Library**.
3. Search for and enable the following APIs:

* Compute Engine API (`compute.googleapis.com`)
* Kubernetes Engine API (`container.googleapis.com`)
* Cloud Resource Manager API (`cloudresourcemanager.googleapis.com`)

<figure><img src="/files/NXQUf4jYcWTIbvHvxgHA" alt="" width="544"><figcaption></figcaption></figure>

4. Alternatively, use the `gcloud` CLI to enable all the required APIs at once:

```bash
    gcloud services enable \
  aiplatform.googleapis.com \
  appengine.googleapis.com \
  artifactregistry.googleapis.com \
  bigquery.googleapis.com \
  cloudfunctions.googleapis.com \
  cloudkms.googleapis.com \
  cloudresourcemanager.googleapis.com \
  compute.googleapis.com \
  container.googleapis.com \
  containerregistry.googleapis.com \
  dataproc.googleapis.com \
  datastore.googleapis.com \
  discoveryengine.googleapis.com \
  dns.googleapis.com \
  firebase.googleapis.com \
  firebasedatabase.googleapis.com \
  firebaserules.googleapis.com \
  firestore.googleapis.com \
  healthcare.googleapis.com \
  iam.googleapis.com \
  logging.googleapis.com \
  monitoring.googleapis.com \
  pubsub.googleapis.com \
  redis.googleapis.com \
  run.googleapis.com \
  secretmanager.googleapis.com \
  spanner.googleapis.com \
  sqladmin.googleapis.com \
  storage.googleapis.com
  iamcredentials.googleapis.com
```

> **Note:** The CLI command enables a broader set of APIs than the minimum required for GKE. The additional APIs (such as BigQuery, Cloud KMS, and Dataproc) support other GCP features that OX Security may scan. If you prefer to enable only the minimum required APIs, use the manual UI steps in step 16c above.

5. To verify the APIs were enabled, run:

```
gcloud services list --enabled
```

## Step 2: Create a Workload Identity Pool and OIDC provider \[Google]

Instead of creating a service account key, configure Google Cloud to trust OX as an external identity provider.

1. In the Google Cloud Console, go to **IAM & Admin** > **Workload Identity Federation**.
2. Select **Create workload provider and pool**.
3. Configure the Workload Identity Pool.
4. Configure the OIDC provider using the following values:

| Parameter         | Value                                                                                                                              |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Pool ID**       | Enter a unique ID for the pool, for example, **ox-pool**. This value becomes part of the audience.                                 |
| **Provider**      | OpenID Connect (OIDC).                                                                                                             |
| **Provider name** | Enter a display name, for example, **ox-oidc**.                                                                                    |
| **Provider ID**   | Keep the generated value or enter **ox-oidc**. This value becomes part of the audience.                                            |
| **Issuer (URL)**  | Enter the issuer URL displayed in the OX connection dialog.                                                                        |
| **Audience**      | Keep **Default audience** selected. Copy the generated audience value. You will use it later when configuring the connector in OX. |

5. Configure the following attribute mapping:

| Google attribute   | Value           |
| ------------------ | --------------- |
| **google.subject** | `assertion.sub` |

6. Select **Save**.

## Step 3: Grant OX read-only access \[Google]

Grant OX read-only access by using one of the following methods:

* **Option A: Service account (recommended):** Grants the Workload Identity Pool permission to impersonate the read-only service account that you created in **Connect using Token & Project ID**. This option provides broader compatibility with Google Cloud services.
* **Option B: Direct access:** Grants the required read-only IAM roles directly to the Workload Identity Pool instead of using a service account.

### Option A: Service account (recommended)

1. [Create a new service account.](/ox-integrations/3rd-party-integrations/cloud-security/gcp-and-gke-1/gcp-token-and-project-id.md#step-1-create-a-new-service-account-google)
2. Go to **IAM & Admin** > **Service Accounts**.
3. Open the read-only service account that you created in **Connect using Token & Project ID**.
4. Open the **Principals with access** tab.

<figure><img src="/files/rhmhgWYegiri8WLJadiV" alt="" width="563"><figcaption></figcaption></figure>

3. Select **Grant access**.

<figure><img src="/files/ZAAk8mV9AnArUjzjkfZu" alt="" width="563"><figcaption></figcaption></figure>

4. In **New principals**, enter:

```
principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/*
```

6. Replace:
   * `<PROJECT_NUMBER>` with your numeric Google Cloud project number.
   * `<POOL_ID>` with the ID of your Workload Identity Pool.
7. Assign the **Workload Identity User** (`roles/iam.workloadIdentityUser`) role.
8. Select **Save**.

### Option B: Direct access

1. Go to **IAM & Admin** > **IAM**.
2. Select **Grant access**.
3. In **New principals**, enter:

```
principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/*
```

4. Replace:
   * `<PROJECT_NUMBER>` with your numeric Google Cloud project number.
   * `<POOL_ID>` with the ID of your Workload Identity Pool.
5. Assign the same read-only IAM roles described in **Connect using Token & Project ID**.
6. Select **Save**.

## Step 5: Connect GCP to OX

1. In the OX platform, go to **Connectors** and search for **GCP**.

<figure><img src="/files/L6p5rRrD8w2fBiOSDGFj" alt="" width="155"><figcaption></figcaption></figure>

2. Select **GCP**.

<figure><img src="/files/A10huzBESq8tPdgAh1MH" alt="" width="512"><figcaption></figcaption></figure>

3. Select **Workload Identity Federation** as the authentication method.
4. Configure the following parameters:

| Parameter                           | Description                                                                                                                                               |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workload Identity Pool Provider** | Paste the **Default audience** value that you copied when creating the OIDC provider. This field is required.                                             |
| **Service Account**                 | Optional. Enter the email address of the read-only service account if you configured **Option A**. Leave this field empty if you configured **Option B**. |

5. Select **Connect**.

## Multi-project access

To use the same Workload Identity Federation configuration across multiple GCP projects:

* Create the Workload Identity Pool and OIDC provider only once.
* For each additional project, grant the required read-only IAM roles to the identity that you selected in **Step 2**:
  * If you configured **Option A**, grant the roles to the service account.
  * If you configured **Option B**, grant the roles directly to the Workload Identity Pool principal.

The Workload Identity Pool, OIDC provider, and, if applicable, the service account impersonation configuration can be reused across all configured projects.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ox.security/ox-integrations/3rd-party-integrations/cloud-security/gcp-and-gke-1/gcp-workload-identity-federation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.