[metadata]
google-signin-client-id: 721724668570-nbkv1cfusk7kk4eni4pjvepaus73b13t.apps.googleusercontent.com
google-signin-scope: profile email https://www.googleapis.com/auth/developerprofiles https://www.googleapis.com/auth/developerprofiles.award https://www.googleapis.com/auth/devprofiles.full_control.firstparty
og:image: https://docs.cloud.google.com/_static/cloud/images/social-icon-google-cloud-1200-630.png
og:image:height: 630
og:image:width: 1200
og:locale: en
og:site_name: Google Cloud Documentation
og:title: Workload Identity Federation | Identity and Access Management (IAM) | Google Cloud Documentation
og:type: website
og:url: https://docs.cloud.google.com/iam/docs/workload-identity-federation
theme-color: #1a73e8
twitter:card: summary_large_image
viewport: width=device-width, initial-scale=1

[canonical-links]
https://docs.cloud.google.com/iam/docs/workload-identity-federation

[document-links]
/
/: https://docs.cloud.google.com/s/results
AI and ML: /docs/ai-ml
AI and ML: https://docs.cloud.google.com/docs/ai-ml
AWS or Azure: /iam/docs/workload-identity-federation-with-other-clouds
About Google: //about.google/
About managed workload identities: /iam/docs/managed-workload-identity
Access BigQuery data in Power BI with Microsoft Entra: /iam/docs/workforce-sign-in-power-bi
Access and resources management: /docs/access-resources
Access and resources management: https://docs.cloud.google.com/docs/access-resources
Access change propagation: /iam/docs/access-change-propagation
Active Directory: /iam/docs/workload-identity-federation-with-active-directory
Agent Identity API audit logging: /iam/docs/audit-logging/audit-logging-agentidentity
Agent Identity Credentials API audit logging: /iam/docs/audit-logging/audit-logging-agentidentitycredentials
Agent Identity auth manager overview: /iam/docs/auth-manager-overview
Agent Identity overview: /iam/docs/agent-identity-overview
All Identity and Access Management code samples: /iam/docs/samples
Allow policies: /iam/docs/allow-policies
Allow policy inheritance: /iam/docs/resource-hierarchy-access-control
Amazon Web Services (AWS) or Azure: /iam/docs/workload-identity-federation-with-other-clouds
Analyze access to resources: /iam/docs/analyze-access
Apache 2.0 License: https://www.apache.org/licenses/LICENSE-2.0
Application development: /docs/application-development
Application development: https://docs.cloud.google.com/docs/application-development
Application hosting: /docs/application-hosting
Application hosting: https://docs.cloud.google.com/docs/application-hosting
Approve or deny grants with PAM: /iam/docs/pam-approve-deny-grants
Architecture patterns for identity federation: /iam/docs/federated-identity-architectures
Attach service accounts to resources: /iam/docs/attach-service-accounts
Audit entitlement and grant events: /iam/docs/pam-audit-entitlement-events
Auditing-related job functions: /iam/docs/job-functions/auditing
Authenticate using 2-legged OAuth: /iam/docs/auth-with-2lo-v2
Authenticate using 3-legged OAuth: /iam/docs/auth-with-3lo-v2
Authenticate using an API key: /iam/docs/auth-with-api-key-v2
Authenticate using an agent's own identity: /iam/docs/auth-agent-own-identity
Authenticate workloads using Google auth libraries: /iam/docs/authenticate-with-auth-libraries
Best practices for PAM: /iam/docs/pam-best-practices
Best practices for managing service account keys: /iam/docs/best-practices-for-managing-service-account-keys
Best practices for using Google groups: /iam/docs/groups-best-practices
Best practices for using Workforce Identity Federation: /iam/docs/best-practices-workforce-identity-federation
Best practices for using Workload Identity Federation: /iam/docs/best-practices-for-using-workload-identity-federation
Best practices for using service accounts in deployment pipelines: /iam/docs/best-practices-for-using-service-accounts-in-deployment-pipelines
Best practices for using service accounts: /iam/docs/best-practices-service-accounts
Billing-related job functions: /iam/docs/job-functions/billing
Blog: //cloud.google.com/blog/
Built-in identities for resources: /iam/docs/built-in-resource-identities
Choose which type of role to use: /iam/docs/choose-role-type
Cloud Architecture Center: /architecture/
Code samples for all products: /docs/samples
Code samples: /docs/samples
Common Expression Language (CEL): https://github.com/google/cel-spec/blob/master/doc/intro.md#introduction
Community forums: //discuss.google.dev/c/google-cloud/14/
Compute: /docs/compute-area
Compute: https://docs.cloud.google.com/docs/compute-area
Configure PAM settings: /iam/docs/pam-configure-settings
Configure resource-based access: /iam/docs/configuring-resource-based-access
Configure temporary access: /iam/docs/configuring-temporary-access
Console: //console.cloud.google.com/
Contact sales: //cloud.google.com/contact/
Costs and usage management: /docs/costs-usage
Costs and usage management: https://docs.cloud.google.com/docs/costs-usage
Create a downscoped short-lived credential: /iam/docs/create-downscoped-short-lived-credentials
Create and apply principal access boundary policies: /iam/docs/principal-access-boundary-policies-create
Create and delete service account keys: /iam/docs/keys-create-delete
Create and deploy an agent with Agent CLI and Agent Identity: /iam/docs/create-and-deploy-agent
Create and grant roles to service agents: /iam/docs/create-service-agents
Create and manage Google groups in the Google Cloud console: /iam/docs/groups-in-cloud-console
Create and manage custom roles: /iam/docs/creating-custom-roles
Create entitlements: /iam/docs/pam-create-entitlements
Create managed workload identities for GCE: /iam/docs/create-managed-workload-identities
Create managed workload identities for GKE: /iam/docs/create-managed-workload-identities-gke
Create managed workload identities for load balancers: /iam/docs/create-managed-workload-identities-load-balancing
Create service accounts: /iam/docs/service-accounts-create
Create short-lived credentials for a service account: /iam/docs/create-short-lived-credentials-direct
Create short-lived credentials for multiple service accounts: /iam/docs/create-short-lived-credentials-delegated
Creative Commons Attribution 4.0 License: https://creativecommons.org/licenses/by/4.0/
Credential Access Boundaries for Cloud Storage: /iam/docs/downscoping-short-lived-credentials
Cross-product tools: /docs/cross-product-overviews
Cross-product tools: https://docs.cloud.google.com/docs/cross-product-overviews
Data analytics and pipelines: /docs/data
Data analytics and pipelines: https://docs.cloud.google.com/docs/data
Databases: /docs/databases
Databases: https://docs.cloud.google.com/docs/databases
Delete Workforce Identity Federation users and their data: /iam/docs/workforce-delete-user-data
Delete and undelete service accounts: /iam/docs/service-accounts-delete-undelete
Deny access: /iam/docs/deny-access
Deny policies: /iam/docs/deny-overview
Deployment pipelines: /iam/docs/workload-identity-federation-with-deployment-pipelines
Disable and enable service account keys: /iam/docs/keys-disable-enable
Disable and enable service accounts: /iam/docs/service-accounts-disable-enable
Distributed, hybrid, and multicloud: /docs/dhm-cloud
Distributed, hybrid, and multicloud: https://docs.cloud.google.com/docs/dhm-cloud
Documentation: https://docs.cloud.google.com/docs
Download credential configuration and grant access: /iam/docs/workload-download-cred-and-grant-access
Edit principal access boundary policies: /iam/docs/principal-access-boundary-policies-edit
Events: //cloud.google.com/events/
Example logs for Workforce Identity Federation: /iam/docs/audit-logging/examples-workforce-identity
Example logs for Workforce OAuth application integration: /iam/docs/audit-logging/examples-oauth-clients
Example logs for Workload Identity Federation: /iam/docs/audit-logging/examples-workload-identity
Example logs for service accounts: /iam/docs/audit-logging/examples-service-accounts
Find the right predefined roles: /iam/docs/choose-predefined-roles
Get predefined role suggestions with Gemini assistance: /iam/docs/role-picker-gemini
Getting Started with Google Cloud: /docs/get-started/
GitHub and GitLab: /iam/docs/workload-identity-federation-with-deployment-pipelines
GitHub: //github.com/googlecloudPlatform/
Google Cloud Marketplace: //cloud.google.com/marketplace/
Google Cloud Tech on YouTube: //www.youtube.com/googlecloudplatform
Google Cloud on YouTube: //www.youtube.com/googlecloud
Google Cloud pricing: //cloud.google.com/pricing/
Google Cloud terms: //cloud.google.com/product-terms
Google Developers Site Policies: https://developers.google.com/site-policies
Grant roles in the Google Cloud console: /iam/docs/grant-role-console
Grant roles using client libraries: /iam/docs/write-policy-client-libraries
Guides: /iam/docs/overview
Guides: https://docs.cloud.google.com/iam/docs/overview
Help secure IAM using VPC Service Controls: /iam/docs/secure-iam-vpc-sc
Home: https://docs.cloud.google.com/
IAM API audit logging: /iam/docs/audit-logging
IAM Conditions: /iam/docs/conditions-overview
IAM SCIM audit logging: /iam/docs/audit-logging/audit-logging-iamscim
IAM and your security architecture: /iam/docs/iam-security-architecture
IAM roles: /iam/docs/overview#roles
IAM: https://docs.cloud.google.com/iam/docs
Identities for users: /iam/docs/user-identities
Identities for workloads: /iam/docs/workload-identities
Identity and Access Management (IAM): https://docs.cloud.google.com/iam/docs
Identity management for Google Cloud: /iam/docs/google-identities
Industry solutions: /docs/industry
Industry solutions: https://docs.cloud.google.com/docs/industry
Infrastructure as code: /docs/iac
Infrastructure as code: https://docs.cloud.google.com/docs/iac
Integrate Cloud Run and Workload Identity Federation: /iam/docs/tutorial-cloud-run-workload-id-federation
Kubernetes: /iam/docs/workload-identity-federation-with-kubernetes
Let customers access their Google Cloud resources from your product or service: /iam/docs/use-workload-identity-federation-to-let-customers-access-their-cloud-resources
Lint conditions in allow policies: /iam/docs/linting-policies
List and edit service accounts: /iam/docs/service-accounts-list-edit
List and get service account keys: /iam/docs/keys-list-get
Manage OAuth applications: /iam/docs/workforce-manage-oauth-app
Manage OIDC JWKs (Optional): /iam/docs/workload-identity-federation-with-other-providers#manage-oidc-keys
Manage access to other resources: /iam/docs/manage-access-other-resources
Manage access to projects, folders, and organizations: /iam/docs/granting-changing-revoking-access
Manage access to service accounts: /iam/docs/manage-access-service-accounts
Manage auth providers: /iam/docs/manage-auth-providers-v2
Manage conditional role bindings: /iam/docs/managing-conditional-role-bindings
Manage tags for custom roles: /iam/docs/custom-roles-tags
Manage tags for service accounts: /iam/docs/service-accounts-tags
Manage workforce identity pools and providers: /iam/docs/manage-workforce-identity-pools-providers
Manage workload identity pools and providers: /iam/docs/manage-workload-identity-pools-providers
Microsoft Entra ID with a large number of groups: /iam/docs/workforce-sign-in-microsoft-entra-id-scalable-groups
Microsoft Entra ID: /iam/docs/configure-scim-ms-entra
Microsoft Entra ID: /iam/docs/workforce-sign-in-microsoft-entra-id
Migrate from service account keys: /iam/docs/migrate-from-service-account-keys
Migrate to the Agent Identity API: /iam/docs/migrate-to-agent-identity-api
Migrate to the Service Account Credentials API: /iam/docs/migrating-to-credentials-api
Migration: /docs/migration
Migration: https://docs.cloud.google.com/docs/migration
Monitor usage patterns for service accounts and keys: /iam/docs/service-account-monitoring
Networking-related job functions: /iam/docs/job-functions/networking
Networking: /docs/networking
Networking: https://docs.cloud.google.com/docs/networking
OAuth 2.0 token exchange: https://tools.ietf.org/html/rfc8693
OAuth application integration overview: /iam/docs/workforce-oauth-app
OIDC or SAML 2.0: /iam/docs/configure-scim-oidc-saml
OIDC or SAML providers: /iam/docs/workload-identity-federation-with-other-providers
Observability and monitoring: /docs/observability
Observability and monitoring: https://docs.cloud.google.com/docs/observability
Obtain short-lived credentials for Workforce Identity Federation: /iam/docs/workforce-obtaining-short-lived-credentials
Okta: /iam/docs/configure-scim-okta
Okta: /iam/docs/workforce-sign-in-okta
OpenID Connect (OIDC) or Security Assertion Markup Language (SAML) V2.0: /iam/docs/workload-identity-federation-with-other-providers
Optimize IAM policies by using Policy Intelligence tools: /iam/docs/policy-intelligence-tools
Other OIDC or SAML 2.0: /iam/docs/configuring-workforce-identity-federation
Other identity providers: /iam/docs/workload-identity-federation-with-other-providers
Our third decade of climate action: join us: //cloud.google.com/sustainability
Overview: /iam/docs
Overview: https://docs.cloud.google.com/iam/docs
PAM overview: /iam/docs/pam-overview
Permission error messages: /iam/docs/permission-error-messages
Permissions and setup: /iam/docs/pam-permissions-and-setup
PingFederate: /iam/docs/workforce-sign-in-pingfederate
PingOne AIC: /iam/docs/workforce-sign-in-pingone
Policy types: /iam/docs/policy-types
Predefined roles for job functions: /iam/docs/job-functions/roles-for-job-functions
Principal access boundary policies: /iam/docs/principal-access-boundary-policies
Principals: /iam/docs/principals-overview
Privacy: //policies.google.com/privacy
Privileged Access Manager audit logging: /iam/docs/audit-logging/audit-logging-pam
Product overview: /iam/docs/overview
Reference: /iam/docs/apis
Reference: https://docs.cloud.google.com/iam/docs/apis
Release Notes: //docs.cloud.google.com/release-notes
Remediate excessive permissions with PAM: /iam/docs/pam-remediate-iam-recommendations
Remove principal access boundary policies: /iam/docs/principal-access-boundary-policies-remove
Request missing permissions: /iam/docs/request-missing-permissions
Request temporary elevated access with PAM: /iam/docs/pam-request-temporary-elevated-access
Resolve permission errors: /iam/docs/resolve-permission-errors
Resources: /iam/docs/resources
Resources: https://docs.cloud.google.com/iam/docs/resources
Restore a previous version of an allow policy: /iam/docs/restore-iam-policy
Review allow policy history: /iam/docs/review-iam-policy-history
Review security insights: /iam/docs/review-security-insights
Revoke grants: /iam/docs/pam-revoke-grants
Roles and permissions: /iam/docs/roles-overview
Roles for service account authentication: /iam/docs/service-account-permissions
SCIM provisioning for Workforce Identity Federation: /iam/docs/workforce-identity-federation-scim
SDK, languages, frameworks, and tools: /docs/devtools
SDK, languages, frameworks, and tools: https://docs.cloud.google.com/docs/devtools
Samples: /iam/docs/samples
Samples: https://docs.cloud.google.com/iam/docs/samples
Security Token Service API audit logging: /iam/docs/audit-logging/audit-logging-sts
Security Token Service: /iam/docs/reference/sts/rest
Security: /docs/security
Security: https://docs.cloud.google.com/docs/security
See all products: //cloud.google.com/products/
Service Account Credentials API audit logging: /iam/docs/audit-logging/audit-logging-iamcreds
Service account credentials: /iam/docs/service-account-creds
Service account impersonation: /iam/docs/service-account-impersonation
Service account key rotation: /iam/docs/key-rotation
Service account types: /iam/docs/service-account-types
Service accounts: /iam/docs/service-account-overview
Set limits on granting roles: /iam/docs/setting-limits-on-granting-roles
Set up user access to console (federated): /iam/docs/workforce-console-sso
Sign in to the gcloud CLI with your federated identity: /iam/docs/workforce-log-in-gcloud
Site terms: //policies.google.com/terms?hl=en
Start free: //console.cloud.google.com/freetrial
Storage: /docs/storage
Storage: https://docs.cloud.google.com/docs/storage
Subscribe: //cloud.google.com/newsletter/
Support: //cloud.google.com/support-hub/
System status: //status.cloud.google.com
Tags and conditional access: /iam/docs/tags-access-control
Technology areas: /docs
Technology areas: https://docs.cloud.google.com/docs
Temporary elevated access overview: /iam/docs/temporary-elevated-access
Test allow policy changes: /iam/docs/test-policy-changes
Test permissions for custom user interfaces: /iam/docs/testing-permissions
Tools to understand service account usage: /iam/docs/service-account-usage-tools
Training and Certification: //cloud.google.com/learn/training/
Troubleshoot "withcond" in policies and role bindings: /iam/docs/troubleshooting-withcond
Troubleshoot Agent Identity auth manager: /iam/docs/troubleshoot-auth-manager
Troubleshoot Workforce Identity Federation: /iam/docs/troubleshooting-workforce-identity-federation
Troubleshoot Workload Identity Federation: /iam/docs/troubleshooting-workload-identity-federation
Troubleshoot allow and deny policies: /iam/docs/troubleshoot-policies
Troubleshoot managed workload identities for GKE: /iam/docs/troubleshoot-managed-workload-identities-gke
Troubleshoot organization policy errors for service accounts: /iam/docs/troubleshoot-org-policies
Upload a public key: /iam/docs/keys-upload
Use IAM securely: /iam/docs/using-iam-securely
Use IAM to help prevent exfiltration from data pipelines: /solutions/help-secure-the-pipeline-from-your-data-lake-to-your-data-warehouse
Use custom organization policies for Privileged Access Manager: /iam/docs/pam-custom-constraints
Use custom organization policies for allow policies: /iam/docs/org-policy-custom-constraints
Use custom organization policies for auth manager: /iam/docs/auth-manager-custom-constraints
Use custom organization policies for service accounts and keys: /iam/docs/service-accounts-custom-constraints
Use custom organization policies: /iam/docs/managed-workload-identity-custom-constraints
Use custom organization policies: /iam/docs/workload-identity-federation-custom-constraints
View and export PAM settings: /iam/docs/pam-view-export-settings
View grantable roles: /iam/docs/viewing-grantable-roles
View grants: /iam/docs/pam-view-grants
View principal access boundary policies: /iam/docs/principal-access-boundary-policies-view
View, update, and delete entitlements: /iam/docs/pam-view-update-delete-entitlements
Withdraw grants: /iam/docs/pam-withdraw-grants
Workforce identity federation: /iam/docs/workforce-identity-federation
Workload Identity Federation: /iam/docs/workload-identity-federation
Workloads with X.509 certificates: /iam/docs/workload-identity-federation-with-x509-certificates
X (Twitter): //x.com/googlecloud
X.509 Certificates: /iam/docs/workload-identity-federation-with-x509-certificates
X.509 client certificates: /iam/docs/workload-identity-federation-with-x509-certificates
attributeCondition field: /iam/docs/reference/rest/v1/projects.locations.workloadIdentityPools.providers#WorkloadIdentityPoolProvider.FIELDS.attribute_condition
attributeMapping field: /iam/docs/reference/rest/v1/projects.locations.workloadIdentityPools.providers#WorkloadIdentityPoolProvider.FIELDS.attribute_mapping
confused deputy problem: https://wikipedia.org/wiki/Confused_deputy_problem
extract function: /iam/docs/conditions-attribute-reference#extract
https://docs.cloud.google.com/iam/docs
join function: https://pkg.go.dev/github.com/google/cel-go/ext#readme-join
limitations: /iam/docs/federated-identity-supported-services
logical operators and functions: https://github.com/google/cel-spec/blob/master/doc/langdef.md#list-of-standard-definitions
manage workload identity pools: /iam/docs/manage-workload-identity-pools-providers
principals: /iam/docs/principals-overview
service account impersonation: /iam/docs/workload-identity-federation-with-other-clouds#impersonation
service account keys: /iam/docs/service-account-creds#key-types
short-lived OAuth 2.0 access token: /iam/docs/creating-short-lived-service-account-credentials#sa-credentials-oauth
split function: https://pkg.go.dev/github.com/google/cel-go/ext#readme-split

[structured-data]
{"@context":"https://schema.org","@type":"Article","headline":"Workload Identity Federation"}
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","item":"https://docs.cloud.google.com/iam/docs","name":"IAM","position":1},{"@type":"ListItem","item":"https://docs.cloud.google.com/iam/docs","name":"Identity and Access Management (IAM)","position":2},{"@type":"ListItem","item":"https://docs.cloud.google.com/iam/docs/workload-identity-federation","name":"Workload Identity Federation","position":3}]}

[content]
Workload Identity Federation | Identity and Access Management (IAM) | Google Cloud Documentation
Skip to main content
Technology areas
close
AI and ML
Application development
Application hosting
Compute
Data analytics and pipelines
Databases
Distributed, hybrid, and multicloud
Industry solutions
Migration
Networking
Observability and monitoring
Security
Storage
Cross-product tools
close
Access and resources management
Costs and usage management
Infrastructure as code
SDK, languages, frameworks, and tools
/
Console
English
Deutsch
Español
Español – América Latina
Français
Indonesia
Italiano
Português
Português – Brasil
עברית
中文 – 简体
中文 – 繁體
日本語
한국어
Sign in
IAM
Identity and Access Management (IAM)
Start free
Overview
Guides
Reference
Samples
Resources
Technology areas
More
Overview
Guides
Reference
Samples
Resources
Cross-product tools
More
Console
Discover
Product overview
Get started
Grant roles in the Google Cloud console
Grant roles using client libraries
IAM and your security architecture
Identity management for Google Cloud
Configure identities for users
Identities for users
Create and manage Google groups in the Google Cloud console
Best practices for using Google groups
Federate identities for users
Workforce identity federation
Architecture patterns for identity federation
Best practices for using Workforce Identity Federation
SCIM provisioning for Workforce Identity Federation
Configure Workforce Identity Federation
Microsoft Entra ID
Microsoft Entra ID with a large number of groups
Okta
PingFederate
PingOne AIC
Other OIDC or SAML 2.0
Access BigQuery data in Power BI with Microsoft Entra
Configure SCIM
Microsoft Entra ID
Okta
OIDC or SAML 2.0
Obtain short-lived credentials for Workforce Identity Federation
Manage workforce identity pools and providers
Delete Workforce Identity Federation users and their data
Set up user access to console (federated)
Sign in to the gcloud CLI with your federated identity
Integrate OAuth applications
OAuth application integration overview
Manage OAuth applications
Configure identities for workloads
Identities for workloads
Create and manage service accounts
About service accounts
Service accounts
Service account credentials
Service account impersonation
Service account types
Roles for service account authentication
Create and grant roles to service agents
Create service accounts
Manage service accounts
List and edit service accounts
Disable and enable service accounts
Delete and undelete service accounts
Manage tags for service accounts
Attach service accounts to resources
Use custom organization policies for service accounts and keys
Service account best practices
Best practices for using service accounts
Best practices for using service accounts in deployment pipelines
Use managed workload identities
About managed workload identities
Compute Engine
Create managed workload identities for GCE
GKE
Create managed workload identities for GKE
Troubleshoot managed workload identities for GKE
Cloud load balancing
Create managed workload identities for load balancers
Use custom organization policies
Federate identities for external workloads
Workload Identity Federation
Configure Workload Identity Federation
AWS or Azure
Active Directory
Deployment pipelines
Kubernetes
Workloads with X.509 certificates
Other identity providers
Authenticate workloads using Google auth libraries
Manage workload identity pools and providers
Best practices for using Workload Identity Federation
Let customers access their Google Cloud resources from your product or service
Download credential configuration and grant access
Integrate Cloud Run and Workload Identity Federation
Use custom organization policies
Create and manage service account keys
Migrate from service account keys
Service account key rotation
Create and delete service account keys
List and get service account keys
Upload a public key
Disable and enable service account keys
Best practices for managing service account keys
Built-in identities for resources
Configure identities for agents
Agent Identity overview
Create and deploy an agent with Agent CLI and Agent Identity
Authenticate using an agent's own identity
Agent Identity auth manager
Agent Identity auth manager overview
Authenticate using 3-legged OAuth
Authenticate using 2-legged OAuth
Authenticate using an API key
Manage auth providers
Migrate to the Agent Identity API
Use custom organization policies for auth manager
Control access to resources
About IAM access controls
Roles and permissions
Principals
Policy types
Allow policies
Allow policy inheritance
Deny policies
Principal access boundary policies
Access change propagation
IAM Conditions
Choose roles to grant
Choose which type of role to use
Find the right predefined roles
Get predefined role suggestions with Gemini assistance
View grantable roles
Roles for specific job functions
Predefined roles for job functions
Billing-related job functions
Networking-related job functions
Auditing-related job functions
Create and manage custom roles
Create and manage custom roles
Manage tags for custom roles
Grant access
Manage access to projects, folders, and organizations
Manage access to service accounts
Manage access to other resources
Test allow policy changes
Grant access conditionally
Manage conditional role bindings
Configure temporary access
Configure resource-based access
Tags and conditional access
Set limits on granting roles
Lint conditions in allow policies
Deny access
Restrict the resources that a principal can access
Create and apply principal access boundary policies
View principal access boundary policies
Edit principal access boundary policies
Remove principal access boundary policies
Temporary elevated access
Temporary elevated access overview
Control temporary elevated access with PAM
PAM overview
Permissions and setup
Create entitlements
View, update, and delete entitlements
Configure PAM settings
View and export PAM settings
View grants
Revoke grants
Audit entitlement and grant events
Remediate excessive permissions with PAM
Use custom organization policies for Privileged Access Manager
Best practices for PAM
Request temporary elevated access with PAM
Withdraw grants
Approve or deny grants with PAM
Create short-lived credentials for a service account
Create short-lived credentials for multiple service accounts
Restrict a credential's Cloud Storage permissions
Credential Access Boundaries for Cloud Storage
Create a downscoped short-lived credential
Migrate to the Service Account Credentials API
Restore a previous version of an allow policy
Test permissions for custom user interfaces
Use custom organization policies for allow policies
Use IAM to help prevent exfiltration from data pipelines
Optimize your IAM configuration
Use IAM securely
Optimize IAM policies by using Policy Intelligence tools
Help secure IAM using VPC Service Controls
Monitor
Audit logging
IAM API audit logging
IAM SCIM audit logging
Service Account Credentials API audit logging
Agent Identity API audit logging
Agent Identity Credentials API audit logging
Privileged Access Manager audit logging
Security Token Service API audit logging
Example logs for service accounts
Example logs for Workforce Identity Federation
Example logs for Workforce OAuth application integration
Example logs for Workload Identity Federation
Analyze access to resources
Monitor service account usage
Tools to understand service account usage
Monitor usage patterns for service accounts and keys
Review allow policy history
Review security insights
Troubleshoot
Troubleshoot permission error messages
Permission error messages
Request missing permissions
Resolve permission errors
Troubleshoot allow and deny policies
Troubleshoot organization policy errors for service accounts
Troubleshoot "withcond" in policies and role bindings
Troubleshoot Workforce Identity Federation
Troubleshoot Workload Identity Federation
Troubleshoot Agent Identity auth manager
Samples
All Identity and Access Management code samples
Code samples for all products
AI and ML
Application development
Application hosting
Compute
Data analytics and pipelines
Databases
Distributed, hybrid, and multicloud
Industry solutions
Migration
Networking
Observability and monitoring
Security
Storage
Access and resources management
Costs and usage management
Infrastructure as code
SDK, languages, frameworks, and tools
Home
Documentation
Security
IAM
Identity and Access Management (IAM)
Guides
Send feedback
Workload Identity Federation
Stay organized with collections
Save and categorize content based on your preferences.
This document provides an overview of Workload Identity Federation. Using Workload Identity Federation, you can provide on-premises or multicloud workloads with access to Google Cloud resources by using federated identities instead of a service account key.
You can use Workload Identity Federation with workloads that authenticate using
X.509 client certificates
; that run on
Amazon Web Services (AWS) or Azure
; on-premises
Active Directory
; deployment services, such as
GitHub and GitLab
; and with any identity provider (IdP) that supports
OpenID Connect (OIDC) or Security Assertion Markup Language (SAML) V2.0
.
Why Workload Identity Federation?
Applications running outside Google Cloud can use
service account keys
to access Google Cloud resources. However, service account keys are powerful credentials, and can present a security risk if they are not managed correctly. Workload Identity Federation eliminates the maintenance and security burden associated with service account keys.
With Workload Identity Federation, you can use Identity and Access Management (IAM) to grant
IAM roles
to
principals
that are based on federated identities in a workload identity pool. You can grant access to the principals on specific Google Cloud resources. This approach is called
direct access
. Alternatively, you can grant access to a service account, which can then access Google Cloud resources. This approach is called
service account impersonation
.
Workload identity pools
A
workload identity pool
is an entity that lets you manage external identities.
In general, we recommend creating a new pool for each non-Google Cloud environment that needs to access Google Cloud resources, such as development, staging, or production environments.
Workload identity pool providers
A
workload identity pool provider
is an entity that describes a relationship between Google Cloud and your IdP, including the following:
AWS
Microsoft Entra ID
GitHub
GitLab
Kubernetes clusters
Okta
On-premises Active Directory Federation Services (AD FS)
Terraform
Workload Identity Federation follows the
OAuth 2.0 token exchange
specification. You provide a credential from your IdP to the
Security Token Service
, which verifies the identity on the credential, and then returns a federated token in exchange.
OIDC provider with local JWKs
To federate workloads that don't have a public OIDC endpoint, you can upload OIDC JSON Web Key Sets (JWKS) directly to the pool. This is common if you have Terraform or GitHub Enterprise hosted in your own environment or you have regulatory requirements not to expose public URLs. For more information, see
Manage OIDC JWKs (Optional)
.
Attribute mappings
The tokens issued by your external IdP contain one or more attributes. Some IdPs refer to these attributes as
claims
.
Google Security Token Service tokens also contain one or more attributes, as listed in the following table:
Attribute
Description
google.subject
Required. A unique identifier for the user. This attribute is used in IAM
principal://
role bindings and appears in Cloud Logging logs. The value must be unique and can't exceed 127 characters.
google.groups
Optional. A set of groups that the identity belongs to. This attribute is used in IAM
principalSet://
role bindings to grant access to all members of a group.
attribute.
NAME
Optional. You can define up to 50 custom attributes and use these attributes in IAM
principalSet://
role bindings to grant access to all identities with a certain attribute.
An attribute mapping defines how to derive the value of the Google Security Token Service token attribute from an external token. For each Google Security Token Service token attribute, you can define an attribute mapping, formatted as follows:
TARGET_ATTRIBUTE
=
SOURCE_EXPRESSION
Replace the following:
TARGET_ATTRIBUTE
is an attribute of the Google Security Token Service token
SOURCE_EXPRESSION
is a
Common Expression Language (CEL)
expression that transforms one or more attributes from the tokens issued by your external IdP
The following list provides attribute mapping examples:
Assign the assertion attribute
sub
to
google.subject
:
google.subject=assertion.sub
Concatenate multiple assertion attributes:
google.subject='myprovider::' + assertion.aud + '::' + assertion.sub
Map a GUID-valued assertion attribute
workload_id
to a name, and assign the result to a custom attribute named
attribute.my_display_name
:
attribute.my_display_name={ "8bb39bdb-1cc5-4447-b7db-a19e920eb111": "Workload1", "55d36609-9bcf-48e0-a366-a3cf19027d2a": "Workload2" }[assertion.workload_id]
Use CEL
logical operators and functions
to set a custom attribute named
attribute.environment
to either
prod
or
test
, depending on the identity's Amazon Resource Name (ARN):
attribute.environment=assertion.arn.contains(":instance-profile/Production") ? "prod" : "test"
Use the
extract
function
to populate a custom attribute
aws_role
with the name of the assumed role or, if no role has been assumed, with the identity's ARN.
attribute.aws_role=assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn
Use the
split
function
splits a string on the provided separator value. For example, to extract the attribute
username
from an email address attribute by splitting its value at the
@
and using the first string, use the following attribute mapping:
attribute.username=assertion.email.split("@")[0]
join
function
joins a list of strings on the provided separator value. For example, to populate the custom attribute
department
by concatenating a list of strings with
.
as a separator, use the following attribute mapping:
attribute.department=assertion.department.join(".")
When you use X.509 client certificates, Google provides default mappings from certificate attributes.
For AWS, Google provides default mappings, which cover most common scenarios. You can also supply custom mappings.
For OIDC providers, you supply the mappings. To construct the mapping, consult the provider's documentation for a list of attributes on their credentials.
For more details, see the API documentation for the
attributeMapping
field
.
Attribute conditions
An
attribute condition
is a CEL expression that can check assertion attributes and target attributes. If the attribute condition evaluates to
true
for a given credential, the credential is accepted. Otherwise, the credential is rejected.
You can use an attribute condition to restrict which identities can authenticate using your workload identity pool.
Attribute conditions are useful in scenarios such as the following:
If your workload uses an IdP that's available to the general public, you can restrict access so only the identities you choose have access to your workload identity pool.
If you're using an IdP with multiple cloud platforms, you can prevent credentials intended for use with another platform from being used with Google Cloud, and vice-versa. This helps avoid the
confused deputy problem
.
The attribute condition for a workload identity pool provider can use the
assertion
keyword, which refers to a map that represents the authentication credential issued by the IdP. You can use dot notation to access the map's values. For example, AWS credentials include an
arn
value, which you can access as
assertion.arn
. In addition, the attribute condition can use any attribute that is defined in the provider's
attribute mapping
.
The following example only allows requests from identities that have a specific AWS role:
attribute.aws_role
==
"
ROLE_MAPPING
"
For more details, see the API documentation for the
attributeCondition
field
.
Access management
The token exchange flow returns a federated access token. You can use this federated access token to grant your workload access on behalf of
principal identities
on Google Cloud resources and obtain a
short-lived OAuth 2.0 access token
.
You can use this access token to provide IAM access.
We recommend that you use Workload Identity Federation to provide access
directly to a Google Cloud resource
. Although most Google Cloud APIs support Workload Identity Federation, some APIs have
limitations
. As an alternative, you can use
service account impersonation
.
The short-lived access token lets you call any Google Cloud APIs that the resource or service account has access to.
Direct resource access
You can use
direct resource access
to grant to your external identity access directly on a Google Cloud resource using resource-specific roles.
Alternative: Service account impersonation
As an alternative to providing
direct resource access
you can use
service account impersonation
.
Note:
Use fully qualified resource names when granting roles to external identities, and use your
project number
, not your
project ID
.
You must grant your service account the role Workload Identity User (
roles/iam.workloadIdentityUser
).
Principal scopes and security
You grant access to principals or subsets thereof by using
principal types
.
Warning:
Although you can grant access to all of the identities in a workload identity pool, doing so can incur risk. We recommend that you limit access using
attributes
and
conditions
.
Principal types
The following table describes how to define principals as individuals and groups of identities:
Identities
Identifier format
Single identity
principal://iam.googleapis.com/projects/
PROJECT_NUMBER
/locations/global/
workloadIdentityPools/
POOL_ID
/subject/
SUBJECT_ATTRIBUTE_VALUE
All identities in a group
principalSet://iam.googleapis.com/projects/
PROJECT_NUMBER
/locations/global/
workloadIdentityPools/
POOL_ID
/group/
GROUP_ID
All identities with a specific
attribute value
principalSet://iam.googleapis.com/projects/
PROJECT_NUMBER
/locations/global/
workloadIdentityPools/
POOL_ID
/attribute.
ATTRIBUTE_NAME
/
ATTRIBUTE_VALUE
What's next
Use Workload Identity Federation to let your workloads access resources from
AWS or Azure
,
X.509 Certificates
,
Active Directory
,
Deployment pipelines
, or
OIDC or SAML providers
.
Learn how to
manage workload identity pools
using the Google Cloud CLI or the REST API.
Send feedback
Except as otherwise noted, the content of this page is licensed under the
Creative Commons Attribution 4.0 License
, and code samples are licensed under the
Apache 2.0 License
. For details, see the
Google Developers Site Policies
. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-08-13 UTC.
Products and pricing
See all products
Google Cloud pricing
Google Cloud Marketplace
Contact sales
Support
Community forums
Support
Release Notes
System status
Resources
GitHub
Getting Started with Google Cloud
Code samples
Cloud Architecture Center
Training and Certification
Engage
Blog
Events
X (Twitter)
Google Cloud on YouTube
Google Cloud Tech on YouTube
About Google
Privacy
Site terms
Google Cloud terms
Manage cookies
Our third decade of climate action: join us
Sign up for the Google Cloud newsletter
Subscribe
English
Deutsch
Español
Español – América Latina
Français
Indonesia
Italiano
Português
Português – Brasil
עברית
中文 – 简体
中文 – 繁體
日本語
한국어
