GAM/wiki/Using-GAM7-with-keyless-authentication-Workload-Identity-Federation.md

Using GAM7 with Keyless Authentication - Workload Identity Federation

Important: This method is designed for running GAM7 outside of Google Cloud (on-premises, other cloud providers, CI/CD systems). If you're running GAM7 inside Google Cloud, use attached service accounts on Google Compute Engine instead, which provides the same keyless benefits with simpler configuration.

This guide explains how to configure GAM7 to use Google Cloud's Workload Identity Federation for keyless authentication. This is Google's officially recommended authentication method for enhanced security and simplified credential management.

Table of Contents

• Overview
• Prerequisites
• Setup Steps
  • 1. Enable Required APIs
  • 2. Create Workload Identity Pool
  • 3. Create or Use Existing Service Account
  • 4. Grant Required Permissions
• AWS Configuration
  • 1. Create Workload Identity Provider for AWS
  • 2. Allow AWS Identity to Impersonate Service Account
  • 3. Create Credential Configuration File
  • 4. Configure GAM7 Environment for AWS
  • 5. Initialize GAM7
• GitHub Actions Configuration
  • 1. Create Workload Identity Provider for GitHub Actions
  • 2. Allow GitHub Actions to Impersonate Service Account
  • 3. GitHub Actions Workflow Configuration
• Clean Up
• Security Best Practices
• Troubleshooting
• Benefits
• References

Overview

Workload Identity Federation allows GAM7 to authenticate to Google Cloud services without storing long-lived service account keys. Instead, it uses short-lived tokens from external identity providers like AWS, Azure, or GitHub Actions, eliminating the security risks associated with managing static credentials.

Prerequisites

• GAM7 installed and configured
  • Run gam config to generate the gam.cfg file
  • Run gam create/use project to generate the oauth2service.json file
  • Optionally enable DASA gam config enable_dasa true admin_email admin@domain.com customer_id domain domain.com save
• Google Cloud CLI (gcloud) installed and configured
  • Install gcloud CLI
  • Run gcloud auth login to authenticate
  • Run gcloud config set project PROJECT_ID to set your project
  • Alternative: Use the Google Cloud Console web interface to perform the same operations
• Google Cloud project with appropriate APIs enabled
• External identity provider (AWS, Azure, GitHub Actions, etc.)
• Appropriate permissions to create Workload Identity Pools and manage IAM

Setup Steps

1. Enable Required APIs

gcloud services enable iamcredentials.googleapis.com
gcloud services enable sts.googleapis.com

2. Create Workload Identity Pool

gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="Pool for GAM authentication"

3. Create or Use Existing Service Account

You can either create a new service account or reuse an existing one that has the necessary permissions.

Option A: Create New Service Account

gcloud iam service-accounts create SERVICE_ACCOUNT_ID \
    --description="Service account for GAM operations" \
    --display-name="GAM Service Account"

Option B: Use Existing Service Account

If you already have a service account with appropriate Google Workspace permissions (typically the one created during GAM7 initial setup), you can reuse it. Just note the service account email for the next steps.

# List existing service accounts to find the one you want to use
gcloud iam service-accounts list

4. Grant Required Permissions

# Grant necessary Google Workspace permissions
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/iam.serviceAccountTokenCreator"

AWS Configuration

1. Create Workload Identity Provider for AWS

gcloud iam workload-identity-pools providers create-aws PROVIDER_ID \
    --workload-identity-pool="POOL_ID" \
    --account-id="YOUR_AWS_ACCOUNT_ID" \
    --location="global"

2. Allow AWS Identity to Impersonate Service Account

gcloud iam service-accounts add-iam-policy-binding \
    SERVICE_ACCOUNT_EMAIL \
    --role="roles/iam.workloadIdentityUser" \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/arn:aws:sts::YOUR_AWS_ACCOUNT:assumed-role/YOUR_ROLE_NAME"

3. Create Credential Configuration File

Create a JSON file with your Workload Identity Federation configuration:

For AWS IMDSv1

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --aws \
    --output-file=FILEPATH.json

For AWS IMDSv2

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --aws \
    --enable-imdsv2 \
    --output-file=FILEPATH.json

4. Configure GAM7 Environment for AWS

Set the environment variable to use the credential file:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credential-configurations.json"

Open the oauth2service.json file, and set the key_type to signjwt.

...
  "key_type": "signjwt",
...

5. Initialize GAM7

gam version
gam info user

GitHub Actions Configuration

1. Create Workload Identity Provider for GitHub Actions

gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="https://token.actions.githubusercontent.com" \
    --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
    --attribute-condition="assertion.repository_owner=='YOUR_GITHUB_ORGANIZATION'"
    --location="global"

2. Allow GitHub Actions to Impersonate Service Account

gcloud iam service-accounts add-iam-policy-binding \
    SERVICE_ACCOUNT_EMAIL \
    --role="roles/iam.workloadIdentityUser" \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.repository/YOUR_GITHUB_ORG/YOUR_REPO"

3. GitHub Actions Workflow Configuration

.github/workflows/example.yml

name: GAM Operations
on: [push]

jobs:
  gam-job:
    runs-on: ubuntu-24.04
    permissions:
      id-token: write
      contents: read

    steps:
    - uses: actions/checkout@v3

    - name: Download and install GAM
      run: |
        bash <(curl -s -S -L https://git.io/gam-install) -l

    - name: Copy GAM configs into target dir
      # Make sure to remove the private key from oauth2service.json and set `key_type` to `signjwt`
      run: |
        cp ./gam.cfg ~/.gam/gam.cfg
        cp ./oauth2service.json ~/.gam/oauth2service.json

    # # For debugging GitHub identity tokens
    # - name: Print out GitHub OIDC token
    #   uses: github/actions-oidc-debugger@2e9ba5d3f4bebaad1f91a2cede055115738b7ae8
    #   with:
    #     audience: https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

    - id: 'auth'
      name: 'Authenticate to Google Cloud'
      uses: 'google-github-actions/auth@v1'
      with:
        create_credentials_file: true
        workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
        service_account: 'SERVICE_ACCOUNT_EMAIL'

    - name: Run GAM commands
      run: |
        ~/bin/gam7/gam info user

Clean Up

After verifying that gam is working as expected, delete the old key if it's no longer in use.

gcloud iam service-accounts keys delete KEY_ID --iam-account=SERVICE_ACCOUNT_EMAIL

Also remove it from the oauth2service.json file.

...
  "private_key": "",
  "private_key_id": "",
...

Security Best Practices

1. Principle of Least Privilege: Grant only necessary permissions to the service account
2. Attribute Conditions: Use attribute conditions to restrict access based on specific criteria
3. Regular Auditing: Regularly review and audit Workload Identity Federation configurations
4. Token Lifetime: Configure appropriate token lifetimes for your use case

Troubleshooting

Common Issues

1. Authentication Errors

   • Verify the audience URL matches your Workload Identity Pool
   • Check that the external identity has permission to impersonate the service account

2. Permission Denied

   • Ensure the service account has necessary Google Workspace permissions
   • Verify domain-wide delegation is configured if required

3. Token Expiration

   • Tokens are automatically refreshed by the Google Auth libraries
   • Check network connectivity to Google STS endpoints

Debug Commands

# Test authentication
gcloud auth print-access-token

# Verify service account impersonation
gcloud auth print-access-token --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

# Check GAM authentication
gam info user

Benefits

• Reduced Attack Surface: Short-lived tokens minimize exposure window if compromised
• Reduced Operational Cost: Eliminates the overhead of managing and rotating service account keys
• Improved Scalability: Easily scale across multiple environments without distributing keys
• Better Integration: Native integration with cloud provider identity systems (AWS IAM, GitHub OIDC)
• Compliance: Meets security requirements for keyless authentication

References

• Google Cloud Workload Identity Federation
• Workload Identity Federation With Other Clouds
• Authenticate to Google Cloud from GitHub Actions
• Service Account Impersonation