Dev.to Security 🔐 Cybersecurity 👁 0 📖 5 min read

Gitlab CI + GCP Workload Identity Federation

Introduction Hi everyone! I’m Giuliano Ribeiro, a Cloud Architect, DevOps Engineer, and Google Developer Expert (GDE) in Google Cloud. Over my 25+ years in IT—transitioning from Java development to cloud-native archite

Introduction

Hi everyone! I’m Giuliano Ribeiro, a Cloud Architect, DevOps Engineer, and Google Developer Expert (GDE) in Google Cloud. Over my 25+ years in IT—transitioning from Java development to cloud-native architecture and multi-cloud DevOps—one of the recurring challenges I help teams solve is eliminating static credentials from CI/CD pipelines.

When connecting external CI/CD tools like GitLab to Google Cloud, downloading a Service Account JSON key and storing it as a CI/CD variable used to be the standard approach. However, static, long-lived keys are a major security liability: they can leak, require manual rotation, and often grant overly broad access if compromised.

To solve this, Google Cloud offers Workload Identity Federation (WIF). It enables GitLab CI/CD jobs to authenticate with Google Cloud using short-lived OpenID Connect (OIDC) tokens—completely eliminating static Service Account keys.

The Solution

From the official Google Cloud documentation:

Using identity federation, you can grant on-premises or multi-cloud workloads access to Google Cloud resources, without using a service account key. You can use identity federation with Amazon Web Services (AWS), or with any identity provider that supports OpenID Connect (OIDC), such as GitLab, GitHub, or Microsoft Entra ID.

In this updated guide, we will configure Google Cloud Workload Identity Federation alongside GitLab's native id_tokens OIDC support so your pipelines can deploy workloads securely without managing a single key file.

Step 1: Google Cloud Configuration

First, define your environment variables. Be sure to set GITLAB_NAMESPACE_PATH (your GitLab group or username) so that only your repositories can authenticate against your Workload Identity Pool.

export GCP_PROJECT_NUMBER="YOUR_GCP_PROJECT_NUMBER"
export GCP_PROJECT_ID="YOUR_GCP_PROJECT_ID"

export WORKLOAD_POOL_ID="gitlab-idpool"
export WORKLOAD_PROVIDER_ID="gitlab"
export WORKLOAD_POOL_DISPLAY_NAME="Workload pool for GitLab"
export WORKLOAD_PROVIDER_DISPLAY_NAME="OIDC - GitLab"

export WORKLOAD_LOCATION="global"
export GCP_SERVICE_ACCOUNT="gitlab-sa"

# Update this if you run a self-managed GitLab instance
export GITLAB_URL="https://gitlab.com"
# Restrict access to your specific GitLab group or user namespace (e.g., "my-org" or "my-username")
export GITLAB_NAMESPACE_PATH="your-gitlab-group-or-username"

1.1 Create the Workload Identity Pool and OIDC Provider

Pay close attention to the --attribute-mapping and --attribute-condition flags below. Mapping attribute.namespace_path and enforcing an attribute condition prevents unauthorized users on gitlab.com from authenticating with your pool.

# 1. Create the Workload Identity Pool
gcloud iam workload-identity-pools create "${WORKLOAD_POOL_ID}" \
  --project="${GCP_PROJECT_ID}" \
  --location="${WORKLOAD_LOCATION}" \
  --display-name="${WORKLOAD_POOL_DISPLAY_NAME}"

# 2. Create the OIDC Provider with attribute mapping and security conditions
gcloud iam workload-identity-pools providers create-oidc "${WORKLOAD_PROVIDER_ID}" \
  --project="${GCP_PROJECT_ID}" \
  --location="${WORKLOAD_LOCATION}" \
  --workload-identity-pool="${WORKLOAD_POOL_ID}" \
  --display-name="${WORKLOAD_PROVIDER_DISPLAY_NAME}" \
  --attribute-mapping="google.subject=assertion.sub,attribute.namespace_path=assertion.namespace_path,attribute.project_path=assertion.project_path,attribute.ref=assertion.ref" \
  --attribute-condition="assertion.namespace_path.startsWith('${GITLAB_NAMESPACE_PATH}')" \
  --issuer-uri="${GITLAB_URL}" \
  --allowed-audiences="${GITLAB_URL}"

Pro Tip — Restricting to a Specific Branch (e.g., main):
If you only want production deployments running on your main branch to authenticate, tighten the --attribute-condition flag like this:

--attribute-condition="assertion.namespace_path.startsWith('${GITLAB_NAMESPACE_PATH}') && assertion.ref == 'main'"

1.2 Create the Service Account and Bind IAM Permissions

Next, create the Service Account your GitLab job will impersonate, grant it the required deployment roles, and authorize your GitLab namespace to impersonate it.

# 3. Create the Service Account
gcloud iam service-accounts create "${GCP_SERVICE_ACCOUNT}" \
  --description="GitLab Workload Identity Service Account" \
  --display-name="GitLab Workload Identity Service Account" \
  --project="${GCP_PROJECT_ID}"

# 4. Grant deployment roles to the Service Account (adjust roles to fit your workload)
roles=("roles/cloudfunctions.admin" "roles/run.admin" "roles/iam.serviceAccountUser")
for role in "${roles[@]}"; do
  gcloud projects add-iam-policy-binding "${GCP_PROJECT_ID}" \
    --member="serviceAccount:${GCP_SERVICE_ACCOUNT}@${GCP_PROJECT_ID}.iam.gserviceaccount.com" \
    --role="${role}"
done

# 5. Allow identities from your GitLab namespace to impersonate the Service Account
gcloud iam service-accounts add-iam-policy-binding "${GCP_SERVICE_ACCOUNT}@${GCP_PROJECT_ID}.iam.gserviceaccount.com" \
  --project="${GCP_PROJECT_ID}" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/${GCP_PROJECT_NUMBER}/locations/${WORKLOAD_LOCATION}/workloadIdentityPools/${WORKLOAD_POOL_ID}/attribute.namespace_path/${GITLAB_NAMESPACE_PATH}"

# 6. Print the full Provider Resource Name (you will need this in GitLab)
gcloud iam workload-identity-pools providers describe "${WORKLOAD_PROVIDER_ID}" \
  --project="${GCP_PROJECT_ID}" \
  --location="${WORKLOAD_LOCATION}" \
  --workload-identity-pool="${WORKLOAD_POOL_ID}" \
  --format="value(name)"

Copy the output of the final command. It will follow this format:
projects/123456789/locations/global/workloadIdentityPools/gitlab-idpool/providers/gitlab

Step 2: GitLab CI/CD Configuration

In your GitLab repository, navigate to Settings > CI/CD > Variables and configure the following variables:

  • GCP_WORKLOAD_IDENTITY_PROVIDER: The full provider resource name copied in the previous step.
  • GCP_SERVICE_ACCOUNT_EMAIL: gitlab-sa@YOUR_GCP_PROJECT_ID.iam.gserviceaccount.com
  • GCP_PROJECT_ID: Your Google Cloud Project ID.

Next, update your .gitlab-ci.yml file. GitLab uses the id_tokens keyword to generate a scoped OIDC token with a specific aud (audience):

gcp-deploy:
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
  stage: deploy
  id_tokens:
    GCP_OIDC_TOKEN:
      aud: https://gitlab.com # Must match --allowed-audiences in GCP
  before_script:
    - echo "${GCP_OIDC_TOKEN}" > "${CI_PROJECT_DIR}/.ci_job_jwt_file"
    - gcloud iam workload-identity-pools create-cred-config "${GCP_WORKLOAD_IDENTITY_PROVIDER}"
      --service-account="${GCP_SERVICE_ACCOUNT_EMAIL}"
      --output-file="${CI_PROJECT_DIR}/.gcp_temp_cred.json"
      --credential-source-file="${CI_PROJECT_DIR}/.ci_job_jwt_file"
    - gcloud auth login --cred-file="${CI_PROJECT_DIR}/.gcp_temp_cred.json"
    - gcloud config set project "${GCP_PROJECT_ID}"
  script:
    - gcloud run services list

(Note: If you use a self-managed GitLab instance, replace https://gitlab.com under aud: with your instance URL).

Bonus: Skipping the Service Account with Direct Workload Identity Federation

Google Cloud also supports Direct Workload Identity Federation, allowing you to grant IAM permissions directly to your GitLab principalSet without creating or impersonating a Service Account at all.

If you prefer a pure keyless setup with zero Service Accounts:

  1. Skip creating the Service Account in Step 1.2 and bind project roles directly to the principalSet:
   gcloud projects add-iam-policy-binding "${GCP_PROJECT_ID}" \
     --role="roles/run.admin" \
     --member="principalSet://iam.googleapis.com/projects/${GCP_PROJECT_NUMBER}/locations/${WORKLOAD_LOCATION}/workloadIdentityPools/${WORKLOAD_POOL_ID}/attribute.namespace_path/${GITLAB_NAMESPACE_PATH}"
  1. Omit the --service-account flag when generating the credential config in .gitlab-ci.yml:
   - gcloud iam workload-identity-pools create-cred-config "${GCP_WORKLOAD_IDENTITY_PROVIDER}"
     --output-file="${CI_PROJECT_DIR}/.gcp_temp_cred.json"
     --credential-source-file="${CI_PROJECT_DIR}/.ci_job_jwt_file"

(Note: While Direct WIF is the cleanest approach for most Google Cloud APIs, a few legacy APIs and third-party Terraform providers still expect Service Account impersonation—so choose the option that best fits your tooling).

Wrapping Up

Your GitLab CI/CD pipelines can now authenticate with Google Cloud using short-lived, automatically rotated OIDC tokens. There are no static JSON keys stored in CI/CD variables, and strict namespace and branch conditions ensure only authorized pipelines can access your cloud environment.

I hope this updated guide helps you secure your deployments! Feel free to share your feedback or questions in the comments below.

📰 Read the original article on Dev.to Security

Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.