With Workforce Identity Federation, users in your external identity provider (IdP)can use single sign-on (SSO) to access Google Cloud resources.

What is Workforce Identity Federation?

Workforce Identity Federation lets you use your external identity provider (IdP)to authenticate your workforce—users andgroups of users, such as employees,partners, and contractors. Your users can then access Google Cloud usingsingle sign-on (SSO), through your IdP. You can use Identity and Access Management (IAM)policies toauthorize your workforce users to access Google Cloud services.

Federation versus synchronization

Workforce Identity Federation federates identities from your IdP, so itdoesn't store user accounts in Google Cloud. Because of this,Workforce Identity Federation is syncless, meaning that you don't need touse tools to synchronize user identities from your IdP to Google-managedidentities that require Google Accounts. For example, by usingWorkforce Identity Federation, you don't need to use Cloud Identity'sGoogle Cloud Directory Sync (GCDS).

Workforce Identity Federation versus Workload Identity Federation

Workforce Identity Federation federates user identities whereas Workload Identity Federation federates workload identities.

For more information, seeWorkload Identity Federation.

Attribute-based access

Workforce Identity Federation extends Google Cloud's identitycapabilities to support attribute-based access. In some IdPs, attributes arealso known asclaims orassertions.

After user authentication, attributes that are received from the IdP are used todetermine the scope of access to the Google Cloud resources.

Supported protocols

You can use Workforce Identity Federation with any IdP that supportsOpenIDConnect (OIDC) orSAML 2.0,such as Microsoft Entra ID, Active Directory Federation Services(AD FS), Okta, and others.

Key concepts

This section describes the key concepts ofWorkforce Identity Federation.

Workforce identity pools

Workforce identity pools let you manage groups of workforceidentities and their access to Google Cloud resources.

Pools let you do the following:

• Group user identities; for example,employees orpartners
• Grant IAM access to an entire pool or a subset thereof.
• Federate identities from one or more IdPs.
• Define policies on a group of users that require similar access permissions.
• Specify IdP-specific configuration information, includingattribute mappingandattribute conditions.
• Enable the Google Cloud CLI and API access for third-party identities.
• Log access by users within a pool to Cloud Audit Logs, along with the pool ID.

You can create multiple pools. For an example that describes one such approach,seeExample: Multiple workforce identity pools.

Pools are configured at theGoogle Cloud organization level, whichmotivates the following considerations:

• When you first set up Workforce Identity Federation for yourorganization, provide a unique name for the pool. The name must be unique across all pools in the organization, and should clearly describe the identities it contains.
• If you have the appropriate IAM permissions to view the pool,it can be referenced by its name across all projects and folders within the organization.

Workforce identity pool providers

A workforce identity pool provider is an entity that describes a relationshipbetween your Google Cloud organization and your IdP.

Workforce Identity Federation follows theOAuth 2.0 Token Exchange specification (RFC 8693).You provide a credential from your external identity provider to theSecurity Token Service, which verifies the identity in the credential, and then returns ashort-lived Google Cloud access token in exchange.

OIDC flow types

For OIDC providers, Workforce Identity Federation supports bothauthorization code flow andimplicit flow.Authorization code flow is considered to be the most secure, becausetokens are returned from the IdP in a separate, secure backend transaction,directly from the IdP to Google Cloud, after users authenticate. As aresult, code flow transactions can retrieve tokens of any size, so you can havemore claims to use for attribute mapping and attribute condition.In implicit flow, by comparison, the ID Token is returned from the IdP to thebrowser. Tokens are subject to individual browser URL size limits.

Google Cloud Workforce Identity Federation console

Users in aworkforce identity pool canaccess the Google Cloud Workforce Identity Federation console, also known as the console (federated). The console provides these users with UI access toGoogle Cloudproducts that support Workforce Identity Federation.

SCIM support

If your IdP supportsSystem for Cross-domain Identity Management (SCIM),you can configure your IdP to provision and manage groups in Google Cloud.

Workforce Identity Federation SCIM tenants support sharing inGemini Enterprise. After you configure SCIM tenants in your IdPapplication and in Workforce Identity Federation, GeminiEnterprise users can share NotebookLM notebooks with a group using the group'sname instead of its object ID (UUID). To learn more about sharing notebooks withgroups, seeShare a notebooks with a group.

When you use Workforce Identity Federation SCIM support, the followingconsiderations apply:

• You must set up a workforce identity pool and provider before configuring a SCIM tenant.
• Each workforce identity pool supports only one SCIM tenant. To configure a new SCIM tenant in the same workforce identity pool, you must first delete the existing one. When deleting a SCIM tenant, you have two options:
  • Soft Delete (Default): Deleting a SCIM tenant initiates a 30-day soft-delete period. During this time, the tenant is hidden and cannot be used, and you cannot create a new SCIM tenant in the same workforce identity pool.
  • Hard Delete: To permanently and immediately delete a SCIM tenant, use the--hard-delete flag with the delete command. This action is irreversible and lets you create a new SCIM tenant in the same workforce identity pool immediately after the deletion completes.
  Alternatively, you can create a new workforce identity pool and a new SCIM tenant or use a workforce identity pool that hasn't previously been configured with a SCIM tenant.
• When you use SCIM, you map attributes in the both the workforce identity pool provider and the SCIM tenant. The `google.subject` attribute must uniquely refer to the same identities. You specify the `google.subject` in the workforce identity pool provider by using the--attribute-mapping flag and in the SCIM tenant using the--claim-mapping flag. Non-unique identity values that are mapped in this way can cause different identities in your IdP to be treated as the same identity in Google Cloud. As a result, access that is granted to one user or group identity can also be applied to other identities, and revoking access for one identity might not revoke it for all identities, leaving some identities with access.
• To use SCIM to map groups, set `--scim-usage=enabled-for-groups`. When you map groups using SCIM, any group mapping that is defined in the workforce identity pool provider is ignored. When referring to SCIM-managed groups the mapped attribute is `google.group`, not `google.groups`. `google.groups` is only refers to token-mapped groups.
• When using SCIM, token-based attributes that are mapped with `--attribute-mapping` can still be used for authentication and in principal identifiers.
• For Microsoft Entra ID configuration, you mustn't use--extended-attributes flags when you create the workforce identity pool provider.

SCIM capabilities

Google Cloud Workforce Identity Federation SCIM implementation supports the following features and operations:

• /Users: Supported operations areCreate,Get,Update,Delete,Patch, andPut.
• /Groups: Supported operations areCreate,Get,Update,Delete, andPatch.Patch operation supports updating Group properties or memberships.
• /Schemas
• /ServiceProviderConfig

Your IdP provides attributes, referred to by some IdPs asclaims. Attributescontain information about your users. You can use these attributes inattribute mappings andattribute conditions.

Attribute mappings

You can map these attributes for use by Google Cloud usingCommon Expression Language (CEL).

This section describes the set of required and optional attributes thatGoogle Cloud provides.

You can also define custom attributes in your IdP that can then be used byspecific Google Cloud products; for example in IAM allowpolicies.

The maximum size for attribute mappings is 16 KB. Ifthe size of attribute mappings exceeds the 16 KBlimit, the sign-in attempt will fail.

The attributes are as follows:

• google.subject (Required): a unique identifier for the authenticatinguser. It isoften the subject assertion of the JWT, becauseCloud Audit Logs logs record the contents of this field as the principal.You can use this field to configure IAM for authorizationdecisions. We recommend that you don't use a mutable value because if youchange the value in your IdP's user directory, the user loses access.

  The maximum length is 127 bytes.

• google.groups (Optional): the collection of groups that the authenticatinguser is a member of. You can configure a logic expression using a subsetof CEL that producesan array of strings. You can also use this fieldto configure IAM for authorization decisions. Limitationsforgoogle.groups are as follows:

  • We recommend that you limit the group name to 40 characters.

  • If a single user belongs to more than 400 groups, thatuser's sign-in attempt will fail. To mitigate this, you must define asmaller set of groups in the assertion, and map only those groups that areused to federate the user to Google Cloud.

  • If you use this attribute to grant access in IAM, everymember in the mapped groups is granted access. Therefore, we recommendthat you ensure that only authorized users in your organization canmodify the membership of the mapped groups.

• google.display_name (Optional): attribute that isused to setthe name of the signed-in user in the Google Cloud console. This attributecan't be used in IAM allow policies nor in the attributecondition.

  The maximum length is 100 bytes.

• google.profile_photo (Optional): a URL of the user's thumbnail photo.We recommend the photo to be 400x400 pixels. When this attribute is set, theimage is visible as the user's profile picture in the Google Cloud console.If this value isn't set, or it can't be fetched, a generic user icon isdisplayed instead. This attribute can't be used in either IAMallow policies or in the attribute condition.

• google.posix_username (Optional): a unique POSIX-compliant username stringused for the following:

  • SSH-in-browser.

  • OS Login with Workforce Identity Federation(Preview).

  This attribute can't be used in IAM allow policies or in theattribute condition. The maximum length is 32 characters.

• google.email (Optional): an attribute that is used to map email addresses ofsigned-in, federated users from the IdP to products that you integrate usingWorkforce Identity Federation OAuth client integration.This attribute can't be used in IAM allow policies or in theattribute condition.

  For example, to map email addresses from Okta using the OIDC protocol,includegoogle.email=assertion.email in your attribute mapping.

  Example Google Cloud products that support OAuth client integrationinclude the following:

  • Identity-Aware Proxy with Workforce Identity Federation
  • Secure Source Manager with Workforce Identity Federation

• attribute.KEY (Optional): an external IdP-definedattribute that is present in a user's IdP token. You can use the customattribute to define your authorization strategy in an IAMallow policy.

  For example, in your IdP, you can choose to define an attribute such as theuser's cost center ascostcenter = "1234", and then refer to theprincipal in the following way:

  principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.costcenter/1234

  After you grant access on Google Cloud resources to this principalidentifier, all identities that are configured in the IdP to have thecostcenter attribute set to1234 have access to the resources.

  You can configure a maximum of 50 custom attribute mapping rules. Themaximum size of each such rule is 2048 characters.

  Although we don't have restrictions on the attributes you can map here, westrongly recommend that you choose attributes whose values are stable. Forexample, an attribute likeattribute.job_description might change for manyreasons (such as improving its readability). As an alternative, consider usingattribute.role. Changes to the latter indicate a change of assignedresponsibility and align with changes in the access granted to the user.

You can transform attribute values usingstandard CEL functions. You can also use the following custom functions:

• split functionsplits a string on the provided separator value. For example, to extract the attributeusername 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 functionjoins a list of strings on the provided separator value. For example, to populate the custom attributedepartment by concatenating a list of stringswith. as a separator, use the following attribute mapping:

  attribute.department=assertion.department.join(".")

Attribute conditions

Attribute conditions are optional CEL expressions that let you set constraintson the identity attributes that Google Cloud accepts.

Warning: If your multi-tenant IdP has a single issuer URI, you must useattribute conditions to ensure that access is restricted to the correct tenant. For more information, seeUse attribute conditions when federating with GitHub or other multi-tenant identity providers.

The benefits of using attribute conditions include the following:

• You can use attribute conditions to allow only a subset of externalidentities to authenticate to your Google Cloud project. For example,you might want to allow only those identities that are in a specificteam to sign in, especially if you are using a public IdP.For another example, you might want to allow your accounting team to signin, but not your engineering team.
• Attribute conditions let you prevent credentials intended for use withanother platform from being used with Google Cloud, and vice-versa.This helps avoid theconfused deputy problem.#### Attribute conditions for multi-tenant IdPs

Workforce Identity Federation doesn't maintain a directory of user accounts;instead, it implements claims-based identities. As a result, when two tokens areissued by the same identity provider (IdP) and their claims map to the samegoogle.subject value, the two tokens are assumed to identify the same user. Tofind out which IdP issued a token, Workforce Identity Federation inspects andverifies the token's issuer URL.

Multi-tenant IdPs, such as GitHub and Terraform Cloud, use a single issuer URLacross all of their tenants. For these providers, the issuer URL identifies allof GitHub or Terraform Cloud, not a specific GitHub or Terraform Cloudorganization.

When you use these identity providers, it's insufficient to letWorkforce Identity Federation check a token's issuer URL to ensure that itcomes from a trusted source and that its claims can be trusted. If yourmulti-tenant IdP has a single issuer URL, you must useattribute conditions to ensure that access is restricted to the correct tenant.

Detailed audit logging

Detailed audit logging is a feature of Workforce Identity Federation thatlogs attributes that were received from your IdP to Cloud Audit Logs.

You can enable detailed audit logging when you create your workforce identitypool provider.

To learn how to troubleshoot attribute mapping errors with detailed auditlogging, seeGeneral attribute mapping errors.

JSON web keys

The workforce pool provider can accessJSON web keys (JWKs)that are provided by your IdP in thejwks_uri field in the/.well-known/openid-configuration document. If your OIDC provider doesn'tprovide this information, or your issuer is not publicly accessible, you canmanually upload the JWKs when you create or update the OIDC provider.

Workforce principal identifiers for IAM policies

The following table shows the principal identifiers that you can use to grant rolesto individual users and groups of users.

For a complete list of principal identifiers, seePrincipal identifiers.

Other considerations

This section describes other considerations when using Workforce Identity Federation.

Restrict cross-organization access

Workforce identity pool principals can't directly access resourcesoutside of the organization that they belong to. However, if a principal isgiven permission toimpersonate a service accountwithin the organization, this constraint can be bypassed as service accountsaren't equally restricted.

Workforce pools user project

Most Google Cloud APIs charge billing and quota use to the project thatcontains the resource that your API request accesses. These APIs are calledresource-based APIs. A few Google Cloud APIs charge to the projectassociated with the client; these are calledclient-based APIs. The projectused for billing and quota purposes is called thequota project.

When you create a Workforce Identity Federation configuration file, youspecify aworkforce pools user project. This project is used to identify yourapplication to the Google APIs that it calls. The workforce pools user projectis also used as the default quota project for client-based APIs, unless you usethe gcloud CLI to initiate the API request. You must have theserviceusage.services.use permission, which is included in the Service UsageConsumer (roles/serviceusage.serviceUsageConsumer) role, for the project thatyou specify.

For more information about the quota project, resource-based APIs, andclient-based APIs, seeQuota project overview.

Example: multiple workforce identity pools

This section contains an example that illustrates typical use of multiplepools.

You can create one pool for employees and another for partners. Multinationalorganizations might create separate pools for different divisions in theirorganization. Pools allow for distributed management, in which different groupscan independently manage their specific pool where roles are granted only to theidentities in the pool.

For example, suppose that a company named Enterprise Example Organizationcontracts a different company named Partner Example Organization Inc to provideGoogle Kubernetes Engine (GKE) DevOps services. For Partner Example Organizationworkforce to provide the services, their workforce must be allowed to accessGoogle Kubernetes Engine (GKE) and other Google Cloud resources in EnterpriseExample Organization's organization. Enterprise Example organization alreadyhas a workforce identity pool calledenterprise-example-organization-employees.

To allow Partner Example Organization to manage access to Enterprise ExampleOrganization's resources, Enterprise Example Organization creates a separateworkforce pool for Partner Example Organization workforce users so that PartnerExample Organization can manage it. Enterprise Example Organization providesthe workforce pool to a Partner Example Organization administrator. PartnerExample Organization's administrator uses their own IdP to grant access to theirworkforce.

To do this, Enterprise Example Organization's Admin performs the followingtasks:

1. Create an identity such aspartner-organization-admin@example.com for thePartner Example Organization administrator in Enterprise ExampleOrganization's IdP, which is already configured in the pool calledenterprise-example-organization-employees.

2. Create a new workforce pool calledexample-organization-partner.

3. Create the following allow policy for theexample-organization-partnerpool:

   {"bindings":[{"role":"roles/iam.workforcePoolEditor","members":["principalSet://iam.googleapis.com/locations/global/workforcePools/enterprise-example-organization-employees/subject/partner-organization-admin@example.com"]}]}

4. Grant roles forexample-organization-partner pool on the resources theyneed access to in Enterprise Example Organization's organization.

Partner Example Organization's administrator can now configure theexample-organization-partner pool to connect with their IdP. They can thenallow Partner Example Organization workforce to sign in with Partner ExampleOrganization's IdP credentials. After they sign in, Partner Example Organizationworkforce users can access Google Cloud resources, constrained by policiesthat are defined by Enterprise Example Organization.

Security groups best practices

In large enterprises, IT administrators often create security groups as partof a best-practices access-control model. Security groups govern access tointernal resources. Further, companies often create additional groups foremployees and other groups for partners to extend this access-control model tocloud resources. This can result in proliferation of deeply nested groups thatcan become very difficult to manage.

Your organization might also have policies that limit the number of groups thatyou can create so as to keep the user directory hierarchy reasonably flat. Abetter solution to prevent misconfiguration of IAM policies andlimit growth of groups is to use multiple pools to create a broader separationof users from different organizational units and business units, and partnerorganizations. You can then reference these pools and groups contained withinthese pools to define IAM policies (see examples in theConfiguring IAM step).

VPC Service Controls limitations

Workforce Identity Federation administrative features, including workforce poolconfiguration APIs, and Security Token Service APIs don't support VPC Service Controls.However, Google Cloud products that support bothWorkforce Identity FederationandVPC Service Controls operateas documented and are subject to VPC Service Controls policy checks. Additionally, you canusethird-party identitiessuch as workforce pool users and workload identities in the ingress or egress rules of VPC Service Controls.

Workforce Identity Federation and Essential Contacts

To receive important information about changes to your organization orGoogle Cloud products, you must provideEssential Contacts when usingWorkforce Identity Federation. Cloud Identity users can be contacted throughtheir Cloud Identity email address, but Workforce Identity Federation usersare contacted using Essential Contacts.

When you use the Google Cloud console to create or manage workforce identity pools,you will see a banner that asks you to configure an essential contact with theLegal andSuspension category. Alternatively, you can define a contactin theAll category if you don't have separate contacts. Supplying thecontacts will remove the banner.

What's next

• To learn how to set up Workforce Identity Federation, seeConfiguring Workforce Identity Federation.For IdP-specific instructions, see:
  • Configure Workforce Identity Federation with Microsoft Entra ID and sign in users
  • Configure Workforce Identity Federation with Okta and sign in users
• Obtain short-lived tokens for Workforce Identity Federation
• Manage workforce pools providers
• Delete Workforce Identity Federation users and their data
• View Workforce Identity Federation audit logs
• View products that support Workforce Identity Federation
• Set up user access to console (federated)