Configure OpenID Connect with GCP Workload Identity Federation

caution
The CI_JOB_JWT_V2 variable is under development (alpha) and is not yet suitable for production use.

This tutorial demonstrates authenticating to Google Cloud from a GitLab CI/CD job using a JSON Web Token (JWT) token and Workload Identity Federation. This configuration generates on-demand, short-lived credentials without needing to store any secrets.

To get started, configure OpenID Connect (OIDC) for identity federation between GitLab and Google Cloud. For more information on using OIDC with GitLab, read Connect to cloud services.

This tutorial assumes you have a Google Cloud account and a Google Cloud project. Your account must have at least the Workload Identity Pool Admin permission on the Google Cloud project.

To complete this tutorial:

  1. Create the Google Cloud Workload Identity Pool.
  2. Create a Workload Identity Provider.
  3. Grant permissions for service account impersonation.
  4. Retrieve a temporary credential.

Create the Google Cloud Workload Identity Pool

  • Name: Human-friendly name for the Workload Identity Pool, such as GitLab.
  • Pool ID: Unique ID in the Google Cloud project for the Workload Identity Pool, such as gitlab. This value is used to refer to the pool. and appears in URLs.
  • Description: Optional. A description of the pool.
  • Enabled Pool: Ensure this option is true.

    We recommend creating a single pool per GitLab installation per Google Cloud project. If you have multiple GitLab repositories and CI/CD jobs on the same GitLab instance, they can authenticate using different providers against the same pool.

    Create a Workload Identity Provider

    inside the Workload Identity Pool created in the previous step, using the following options:

    Grant permissions for Service Account impersonation

    Creating the Workload Identity Pool and Workload Identity Provider defines the authentication into Google Cloud. At this point, you can authenticate from GitLab CI/CD job into Google Cloud. However, you have no permissions on Google Cloud (authorization).

    To grant your GitLab CI/CD job permissions on Google Cloud, you must:

    1. Create a Google Cloud Service Account. You can use whatever name and ID you prefer.
    2. roles/storage.objectCreator role on your Cloud Storage bucket.
    3. to impersonate that Service Account. This step enables a GitLab CI/CD job to authorize to Google Cloud, via Service Account impersonation. This step grants an IAM permission on the Service Account itself, giving the external identity permissions to act as that service account. External identities are expressed using the principalSet:// protocol.

    Much like the previous step, this step depends heavily on your desired configuration. For example, to allow a GitLab CI/CD job to impersonate a Service Account named my-service-account if the GitLab CI/CD job was initiated by a GitLab user with the username chris, you would grant the roles/iam.workloadIdentityUser IAM role to the external identity on my-service-account. The external identity takes the format: 

    principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.user_login/chris

    where PROJECT_NUMBER is your Google Cloud project number, and POOL_ID is the ID (not name) of the Workload Identity Pool created in the first section.

    This configuration also assumes you added user_login as an attribute mapped from the assertion in the previous section.

    Retrieve a temporary credential

    After you configure the OIDC and role, the GitLab CI/CD job can retrieve a temporary credential from the . 

    PAYLOAD="$(cat <<EOF
{
  "audience": "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID",
  "grantType": "urn:ietf:params:oauth:grant-type:token-exchange",
  "requestedTokenType": "urn:ietf:params:oauth:token-type:access_token",
  "scope": "https://www.googleapis.com/auth/cloud-platform",
  "subjectTokenType": "urn:ietf:params:oauth:token-type:jwt",
  "subjectToken": "${CI_JOB_JWT_V2}"
}
EOF
)"

    FEDERATED_TOKEN="$(curl --fail "https://sts.googleapis.com/v1/token" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data "${PAYLOAD}" \
  | jq -r '.access_token'
)"

    Where:

    You can then use the resulting federated token to impersonate the service account created in the previous section: 

    ACCESS_TOKEN="$(curl --fail "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer FEDERATED_TOKEN" \
  --data '{"scope": ["https://www.googleapis.com/auth/cloud-platform"]}' \
  | jq -r '.accessToken'
)"

    Where:

    • SERVICE_ACCOUNT_EMAIL is the full email address of the service account to impersonate, created in the previous section.
    • FEDERATED_TOKEN is the federated token retrieved from the previous step.

    The result is a Google Cloud OAuth 2.0 access token, which you can use to authenticate to most Google Cloud APIs and services when used as a bearer token. You can also pass this value to the gcloud CLI by setting the environment variable CLOUDSDK_AUTH_ACCESS_TOKEN.

    Working example

    Review this for provisioning OIDC in GCP using Terraform and a sample script to retrieve temporary credentials.

    Troubleshooting

    • When debugging curl responses, install the latest version of curl. Use --fail-with-body instead of -f. This command prints the entire body, which can contain helpful error messages.

    • Review Google Cloud’s documentation for .