> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GCP connection

> Learn how to configure a GCP Connection for Infisical.

Infisical supports [service account impersonation](https://cloud.google.com/iam/docs/service-account-impersonation) to connect with your GCP projects.

> [accordion] Self-Hosted Instance
>
> Using the GCP integration on a self-hosted instance of Infisical requires configuring a service account on GCP and
> configuring your instance to use it.
>
> **1. Enable the IAM Service Account Credentials API**
>
> Enable the IAM Service Account Credentials API for the project containing the service account that will be impersonated. You can do this from the Google Cloud Console or via the command line.
>
> ![Service Account API](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/gcp/service-account-credentials-api.png)
>
> To enable via command line, run the following command, replacing `projectId` with your GCP project ID:
>
> ```bash theme={"dark"}
> gcloud services enable iamcredentials.googleapis.com --project=projectId
> ```
>
> Verify the API is enabled by running:
>
> ```bash theme={"dark"}
> gcloud services list --enabled --project=projectId | grep iamcredentials
> ```
>
> **2. Navigate to IAM & Admin > Service Accounts in Google Cloud Console**
>
> ![Service Account IAM Page](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/gcp/service-account-overview.png)
>
> **3. Create a Service Account**
>
> Create a new service account that will be used to impersonate other GCP service accounts for your app connections.
>
> ![Create Service Account Page](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/gcp/create-instance-service-account.png)
>
> Press "DONE" after creating the service account.
>
> **4. Generate Service Account Key**
>
> Download the JSON key file for your service account. This will be used to authenticate your instance with GCP.
>
> ![Service Account Credential Page](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/gcp/create-service-account-credential.png)
>
> **5. Configure Your Instance**
>
> 1. Copy the entire contents of the downloaded JSON key file.
>
> 2. Set it as a string value for the `INF_APP_CONNECTION_GCP_SERVICE_ACCOUNT_CREDENTIAL` environment variable.
>
> 3. Restart your Infisical instance to apply the changes.
>
> 4. You can now use GCP integration with service account impersonation.
>
> > [!NOTE]
> >
> > Workload identity federation is also supported. Instead of a service account key, you may
> > set `INF_APP_CONNECTION_GCP_SERVICE_ACCOUNT_CREDENTIAL` to an `external_account` credential
> > configuration JSON (the file produced by `gcloud iam workload-identity-pools create-cred-config`).
> > Infisical detects the credential type from the `type` field automatically. The federated identity
> > needs the `roles/iam.serviceAccountTokenCreator` role on the service accounts it impersonates.
> >
> > For **AWS** providers, Infisical resolves the instance's AWS credentials through the standard AWS
> > SDK credential chain, so federation works on EC2, ECS/Fargate, EKS (IRSA), and Lambda, or from
> > `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` environment variables. The region defaults to
> > `us-east-1`; set `AWS_REGION` (or `AWS_DEFAULT_REGION`) to use a specific regional STS endpoint.
> >
> > For other providers, the referenced credential source (a mounted file or URL) must be reachable
> > from the Infisical instance at runtime.

## Configure service account for Infisical

**1. Navigate to IAM & Admin > Service Accounts in Google Cloud Console**

![Service Account Page](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/gcp/service-account-overview.png)

**2. Create Service Account**

Create a new service account with an ID that follows this requirement:

Your service account ID must end with the first two sections of your Infisical organization ID.

Example:

* Infisical organization ID: `df92581a-0fe9-42b5-b526-0a1e88ec8085`
* Required service account ID suffix: `df92581a-0fe9`

  ![Create Service Account](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/gcp/create-service-account.png)

**3. Configure Service Account Permissions**

> [tab] Secret Sync
>
> Add the required permissions for secret syncs:
>
> ![Assign Service Account Permission](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/gcp/service-account-secret-sync-permission.png)

> [tab] Certificate Sync
>
> Add the required permissions for [certificate syncs](https://infisical.com/docs/documentation/platform/pki/applications/certificate-syncs/gcp-certificate-manager.md):
>
> ![Assign Service Account Permission](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/gcp/service-account-certificate-sync-permission.png)
>
> Grant these roles on the project that holds your certificates, and enable the three APIs Infisical calls on that same project:
>
> ```bash theme={"dark"}
> gcloud services enable \
>     certificatemanager.googleapis.com \
>     cloudresourcemanager.googleapis.com \
>     serviceusage.googleapis.com \
>     --project=PROJECT_ID
> ```
>
> Certificate Manager Owner is needed if you enable certificate removal on a sync, or if you attach a sync to a certificate map. `roles/certificatemanager.editor` grants no delete permissions, and maintaining a map entry replaces or removes it.

> [tab] ACME DNS validation
>
> Add the required permissions for [ACME certificate authorities](https://infisical.com/docs/documentation/platform/pki/ca/acme-ca.md) that validate domains through Google Cloud DNS.
>
> Grant the **DNS Administrator** (`roles/dns.admin`) and **Service Usage Viewer** (`roles/serviceusage.serviceUsageViewer`) roles on the project that holds your public managed zone. DNS Administrator lets Infisical list your projects and zones and create and delete the challenge TXT records. Service Usage Viewer lets Infisical check which projects have the Cloud DNS API enabled.
>
> Then enable the Google Cloud APIs that Infisical uses on that same project:
>
> ```bash theme={"dark"}
> gcloud services enable \
>     dns.googleapis.com \
>     cloudresourcemanager.googleapis.com \
>     serviceusage.googleapis.com \
>     --project=PROJECT_ID
> ```

> [tab] Secret Rotation
>
> Add the **Service Account Key Admin** role so Infisical can create and delete keys for [GCP service account key rotations](https://infisical.com/docs/documentation/platform/secret-rotation/gcp-service-account-key.md).
>
> If you add the role here, it applies to every service account in the project. To allow rotation for specific service accounts only, skip the role here and grant it on each of those service accounts, as described in [the rotation guide](https://infisical.com/docs/documentation/platform/secret-rotation/gcp-service-account-key.md#step-1-configure-the-service-account-for-infisical).

After configuring the appropriate roles, press "DONE".

**4. Enable Service Account Impersonation**

To enable service account impersonation, you'll need to grant the **Service Account Token Creator** role to the Infisical instance's service account. This configuration allows Infisical to securely impersonate the new service account.

1. Navigate to the **IAM & Admin > Service Accounts** section in your Google Cloud Console.
2. Select the newly created service account.
3. Click on the **PERMISSIONS** tab.
4. Click **Grant Access** to add a new principal.
5. In the **New principals** field, enter the Infisical service account email for your environment:
   * **Infisical Cloud US:** `infisical-us@infisical-us.iam.gserviceaccount.com`
   * **Infisical Cloud EU:** `infisical-eu@infisical-eu.iam.gserviceaccount.com`
   * **Self-hosted:** use the service account you created for your instance (the one whose credentials are set in `INF_APP_CONNECTION_GCP_SERVICE_ACCOUNT_CREDENTIAL`).
6. In the **Role** field, select **Service Account Token Creator**.
7. Click **Save**.

   ![Service Account Page](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/gcp/service-account-grant-access.png)

> [!NOTE]
>
> **Troubleshooting: "One or more users named in the policy do not belong to a permitted customer."**
>
> If granting access fails with the error *"One or more users named in the policy do not belong to a permitted customer."*, your Google Cloud organization has the Domain Restricted Sharing organization policy (`iam.allowedPolicyMemberDomains`) enabled. This policy only permits identities that belong to allowlisted Google organizations, so the Infisical service account is rejected until it is explicitly allowed.
>
> To resolve this, add Infisical's Google Cloud Customer ID to the policy's allowed values **before** granting the service account a role:
>
> 1. In the Google Cloud Console, navigate to **IAM & Admin > Organization Policies**.
> 2. Search for and open the **Domain restricted sharing** (`iam.allowedPolicyMemberDomains`) policy.
> 3. Under **Custom values**, add a new allowed value containing Infisical's Google Cloud Customer ID:
>
>    ```
>    C03rsjmyl
>    ```
>
>    This is **Infisical's Google Cloud Customer ID**, not your own. Infisical uses a single Google Cloud organization, so this one Customer ID covers both the US and EU service accounts.
>
>    Enter the bare Customer ID (`C03rsjmyl`) in the Console UI. If you manage this policy with `gcloud`, a policy YAML file, or Terraform instead, use the prefixed form `is:C03rsjmyl`.
> 4. Save the policy, then return to **Step 4 (Grant Access)** in the main instructions above and complete steps 4–7 to add the Infisical service account as a principal.

## Setup GCP connection in Infisical

**1. Navigate to App Connections**

Navigate to the **Integrations** tab in the desired project, then select **App Connections**. ![App Connections
Tab](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/general/add-connection.png)

**2. Add Connection**

Select the **GCP Connection** option from the connection options modal.

![Select GCP
Connection](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/gcp/select-gcp-connection.png)

**3. Authorize Connection**

Select the **Service Account Impersonation** method and click **Connect to
GCP**. ![Connect via GCP
impersonation](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/gcp/create-gcp-impersonation-method.png)

**4. Connection Created**

Your **GCP Connection** is now available for use. ![Impersonation GCP
Connection](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/app-connections/gcp/gcp-app-impersonation-connection.png)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.