> For the complete documentation index, see [llms.txt](https://docs.tonic.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tonic.ai/fabricate/workspaces/gcp-service-accounts/gcp-external-workload-id-provider.md).

# Using an external workload identity provider

You can use the external workload identity provider option when your organization does not allow you to grant an outside Google identity access to your service account. The outside identity can only reach Google through workload identity federation.

With this option, Fabricate:

1. Signs in to your OIDC identity provider with an application that you register there.
2. Exchanges that token at Google.
3. Impersonates your service account.

No Fabricate identity needs access to your project.

## Register the application

In your identity provider:

1. Register an application (a machine-to-machine client) that can use the OAuth2 `client_credentials` grant.
2. Note the following values:

   * **client ID**
   * **client secret**
   * The provider's **token URL** (the OAuth2 token endpoint)

   You use these in the Fabricate configuration.
3. Make sure that:
   * The application tokens are signed JWTs.
   * Google can reach the issuer's public keys.

## Create a workload identity pool and OIDC provider

In GCP:

1. Click **☰ → IAM & Admin → Workload Identity Federation**, then click **Create pool**.
2. Enter a name, for example `fabricate`, then click **Continue**.
3. Choose **OpenID Connect (OIDC)** as the provider type.
4. Enter a provider name.
5. In the **Issuer (URL)** field, enter the issuer URL of your identity provider.
6. Under **Attribute mapping**, map `google.subject` to `assertion.sub`.
7. Click **Save**.
8. Copy the provider's audience:
   1. Open the provider.
   2. Copy the resource name shown there, in the form `//iam.googleapis.com/projects/<project number>/locations/global/workloadIdentityPools/<pool>/providers/<provider>`.

## Allow the application to act as the service account

In GCP:

1. Click **☰ → IAM & Admin → Service Accounts**
2. Click the service account email.
3. Open the **Permissions** tab, then click **Grant access**.
4. In **New principals**, enter the pool's principal for the application:\
   \
   `principal://iam.googleapis.com/projects/<project number>/locations/global/workloadIdentityPools/<pool>/subject/<subject>`.\
   \
   The subject is the `sub` claim of the application's tokens, which is the client ID for most providers.
5. Select the role **Workload Identity User**.
6. Click **Save**.

## Complete the configuration in Fabricate

<figure><img src="https://4109733485-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmoU4gTR9LxlzHeWmQCUZ%2Fuploads%2FslynrbNjNu3EQWrJCPrg%2FWorkspace_GCPServiceAccountExternalWorkloadIDProvider.png?alt=media&amp;token=92b01a9c-c758-43f2-b27b-61e8b5d24ffa" alt=""><figcaption><p>Details panel for a GCP service account that uses an external workload identity provider</p></figcaption></figure>

After you complete the configuration in GCP, to complete the service account configuration in Fabricate:

1. In the **Identity Provider Token URL** field, provide the OAuth2 token endpoint.\
   \
   It must be an `https` URL that Fabricate can reach.
2. By default, **Verify TLS Cert** is set to **Yes** by default.\
   \
   It checks the provider's certificate against the system roots and the CA certificates that are uploaded to your account.\
   \
   Only change this to **No** for testing or if the provider has a private CA that you cannot upload.
3. In the **Client ID** and **Client Secret** fields, provide the application's credentials. The secret is stored encrypted and never shown again.\
   \
   When you edit the service account, to keep the existing value, leave **Client Secret** blank.
4. If your provider requires a scope, then in the **Scope** field, provide the scope.
5. From the **Client Authentication** dropdown list, select the type of authentication that your provider expects.
6. In the **Workload Identity Provider** field, provide the audience that you copied from the provider.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tonic.ai/fabricate/workspaces/gcp-service-accounts/gcp-external-workload-id-provider.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
