Traditionally, when using services like Google Cloud in a non-GCP environment (e.g., a CI/CD environment like GitLab pipelines), developers would need to use service account keys or other long-lived credentials to authenticate with Google Cloud services. However, this approach has some security risks:

• Long-Term Credential Exposure: Service account keys are long-lived credentials, typically valid until manually revoked or rotated. Storing these keys in source code repositories, configuration files, or CI/CD environments increases the risk of unauthorized access if these repositories or environments are compromised.
• Privilege Escalation: Service account keys often have broad permissions designed to perform various tasks within Google Cloud. If an attacker gains access to a service account key, they can access a wide range of resources, which might go beyond what is necessary for a specific application or workload.
• Credential Management: Regularly rotating service account keys are crucial for security best practices. However, manual key rotation can be cumbersome and error-prone, leading to potential lapses in security.
• Limited Auditing and Accountability: When using service account keys, it can be challenging to attribute specific actions to individual users or services. This lack of granularity can hinder auditing efforts and make tracing actions back to their origins harder.

GCP workload identity federation addresses these security concerns and allows you to use your existing identity provider (IdP) to authenticate to Google Cloud Platform (GCP). This can be useful for GitLab pipelines, as it allows you to use your GitLab credentials to authenticate to GCP without managing separate service accounts or credentials.

The key components of the GCP workload identity federation:

• Identity provider (IdP): The IdP is the system that authenticates users and issues them credentials. GCP supports various identity providers such as Active Directory Federation Services (ADFS), Okta, Azure Active Directory, or any identity provider that supports OpenID Connect (OIDC) or SAML 2.0.
• Workload identity pool: An entity that lets you manage external identities. We recommend creating a new pool for each non-Google Cloud environment that needs to access Google Cloud resources.
• Service account: In GCP, service accounts are used to represent workloads. To access resources, pool identities must be granted access to a service account. Once added, these identities will have permission to access any Google Cloud services that the service account can access.
• Federated token: A federated token is a token that is issued by the IdP and exchanged for a service account token. The federated token allows the workload to authenticate to GCP as the service account.

In this blog post, we will explore how to set up workload identity federation in GCP and securely access the GCP services using short-lived tokens in Gitlab pipelines.

Prerequisites

• Ensure you have the Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) and Service Account Admin (roles/iam.serviceAccountAdmin) roles on the project.
• Enable the below APIs.

#Update $GCP_PROJECT_ID value
gcloud services enable cloudresourcemanager.googleapis.com \
iam.googleapis.com \
iamcredentials.googleapis.com \
sts.googleapis.com \
--project $GCP_PROJECT_ID

• A GitLab account, Create a new account if required.

Setup Workload Identity Federation

• Step 1: Create a Workload Identity Pool.

#Update $GCP_PROJECT_ID value
gcloud iam workload-identity-pools create gitlab-demo-wip \
  --location="global" \
  --description="Gitlab demo workload Identity pool" \
  --display-name="gitlab-demo-wip"
  --project=$GCP_PROJECT_ID

workload identity pool

workload identity pool configuration

• Step 2: Add a workload identity pool provider for GitLab and use Attribute conditions to restrict which identities can authenticate using the workload identity pool.
• The attribute mapping configuration is a key part of setting up workload identity federation. It allows you to map attributes from authentication credentials issued by an external identity provider to Google Cloud attributes, such as subject and email. Some identity providers refer to these attributes as claims.
• Each external identity provider can have different attributes exposed. For AWS, Google provides default mappings, which cover most common scenarios. You can also supply custom mappings.
• For OIDC providers like Gitlab, you supply the mappings. To construct the mapping, consult the provider’s documentation for a list of attributes on their credentials. For gitlab, refer to the ID Token payload for claims included in each gitlab ID token.

The below attribute condition restricts the identities only from my personal GitLab namespace. Refer to Gitlab Namespace to determine whether you’re viewing a group or personal namespace.

#Update GITLAB_NAMESPACE_PATH value
gcloud iam workload-identity-pools providers create-oidc gitlab-identity-provider --location="global" \
 --workload-identity-pool="gitlab-demo-wip" \
 --issuer-uri="https://gitlab.com" \
 --allowed-audiences=https://gitlab.com \
 --attribute-mapping="google.subject=assertion.sub,attribute.aud=assertion.aud,attribute.project_path=assertion.project_path,attribute.project_id=assertion.project_id,attribute.namespace_id=assertion.namespace_id,attribute.namespace_path=assertion.namespace_path,attribute.user_email=assertion.user_email,attribute.ref=assertion.ref,attribute.ref_type=assertion.ref_type" \
 --attribute-condition="assertion.namespace_path.startsWith(\"$GITLAB_NAMESPACE_PATH\")" \
 --project=$GCP_PROJECT_ID

sample gcloud command result

gitlab provider added to the workload identity pool

gitlab identity provider configuration

• At this point, you can authenticate from GitLab CI/CD job into Google Cloud. However, you have no permissions on Google Cloud (authorization).
• Step 3: Create a service account that the gitlab external identity can impersonate.

#Create a service account
gcloud iam service-accounts create gitlab-wif-demo --project=$GCP_PROJECT_ID

#Add sample permissions to the Service account
gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
  --member=serviceAccount:gitlab-wif-demo@${GCP_PROJECT_ID}.iam.gserviceaccount.com \
  --role=roles/storage.admin

• Step 4: Grant the gitlab external identity permissions to impersonate the Service Account, enabling a GitLab CI/CD job to authorize Google Cloud via Service Account impersonation. This step grants IAM permission on the Service Account itself, providing the external identity with the authority to act as that service account.

The below command allows all identities in the pool to access GCP resources using service account impersonation, but we recommend restricting the impersonation to specific external identities based on their attributes.

Refer to https://cloud.google.com/iam/docs/workload-identity-federation#impersonation for common scenarios for granting roles.

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\) --project $GCP_PROJECT_ID)

gcloud iam service-accounts add-iam-policy-binding gitlab-wif-demo@${GCP_PROJECT_ID}.iam.gserviceaccount.com \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/gitlab-demo-wip/*"

service account connected to the workload identity pool

Test the workload Identify Federation set up in GitLab Pipeline

In the previous steps, we configured the workload identity pool to trust the identities from my personal Gitlab namespace. No configuration changes are required in your Gitlab account, and you can enable workload identity federation for individual CI/CD jobs. You can customize the setup based on your requirement.

• Step 5: Create an empty Gitlab project or use an existing project.

gitlab repo

• Step 6: Create a file named  .gitlab-ci.yml  and set up a Gitlab pipeline with the below template. Refer to CI/CD pipelines to learn more about the Gitlab pipelines.

#Update the $GCP_PROJECT_NAME and $GCP_PROJECT_NUMBER values
variables:
  GCP_PROJECT_NAME: $GCP_PROJECT_NAME
  GCP_WORKLOAD_IDENTITY_PROVIDER: "projects/$GCP_PROJECT_NUMBER/locations/global/workloadIdentityPools/gitlab-demo-wip/providers/gitlab-identity-provider"
  SERVICE_ACCOUNT_EMAIL: "gitlab-wif-demo@$GCP_PROJECT_NAME.iam.gserviceaccount.com"

stages:
  - gcp_wif_demo

.gcp_wif_auth: &gcp_wif_auth
  #id_tokens to create JSON web tokens (JWT) to authenticate with third party services.This replaces the CI_JOB_JWT_V2
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.com
  before_script:
    - apt-get update && apt-get install -yq jq
    #Get temporary credentials using the ID token
    - |
      PAYLOAD=$(cat <<EOF
      {
      "audience": "//iam.googleapis.com/${GCP_WORKLOAD_IDENTITY_PROVIDER}",
      "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": "${GITLAB_OIDC_TOKEN}"
      }
      EOF
      )
    - |
      FEDERATED_TOKEN=$(curl -s -X POST "https://sts.googleapis.com/v1/token" \
      --header "Accept: application/json" \
      --header "Content-Type: application/json" \
      --data "${PAYLOAD}" \
      | jq -r '.access_token'
      )
    #Use the federated token to impersonate the service account linked to workload identity pool
    #The resulting access token is stored in CLOUDSDK_AUTH_ACCESS_TOKEN environment variable and this will be passed to the gcloud CLI
    - |
      export CLOUDSDK_AUTH_ACCESS_TOKEN=$(curl -s -X POST "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'
      )

gcloud_test:
  <<: *gcp_wif_auth
  stage: gcp_wif_demo
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:441.0.0
  script:
    - gcloud config set project ${GCP_PROJECT_NAME}
    - gcloud storage ls

.gitlab-ci.yml

• BY DEFAULT, GitLab CI/CD pipelines are executed automatically when new commits are pushed. Check the pipeline output under Build -> Pipelines.

gitlab pipeline trigger status

gitlab job sample log

The job logs the authentication and authorization worked as expected with the short-lived token generated as part of the Workload Identity Federation.

Conclusion

Overall, Workload Identity Federation is a valuable service that can help you to secure your GitLab pipelines and improve your security posture. If you are not already using Workload Identity Federation, I encourage you to use it in your pipelines instead of service account keys.