Workforce Identity Federation

This document describes the key concepts of Workforce Identity Federation.

What is Workforce Identity Federation?

Workforce Identity Federation lets you use an external identity provider (IdP) to authenticate and authorize a workforce—a group of users, such as employees, partners, and contractors—using IAM, so that the users can access Google Cloud services. With Workforce Identity Federation you don't need to synchronize user identities from your existing IdP to Google Cloud identities, as you would with Cloud Identity's Google Cloud Directory Sync (GCDS). Workforce Identity Federation extends Google Cloud's identity capabilities to support syncless, attribute-based single sign on.

After user authentication, information that is received from the IdP is used to determine the scope of access to the Google Cloud resources.

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

Workforce identity pools

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

Pools let you do the following:

  • Group user identities; for example, employees or partners
  • 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, including attribute mapping and attribute 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, see Example: Multiple workforce identity pools.

Pools are configured at the Google Cloud organization level. Because of this, pools are available across all projects and folders within the organization, as long as you have the appropriate IAM permissions to view the pool. When you first set up Workforce Identity Federation for your organization, you provide a name for the pool. In IAM allow policies, you reference the pool by its name. Because of this, we recommend that you name the pool so that it clearly describes the identities it contains.

Workforce identity pool providers

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

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

OIDC flow types

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

Google Cloud Workforce Identity Federation console

Users in a workforce identity pool can access the Google Cloud Workforce Identity Federation console, also known as the console (federated). The console provides these users with UI access to Google Cloud products that support Workforce Identity Federation.

Attribute mappings

Your IdP provides attributes, referred to by some IdPs as claims. Attributes contain information about your users. You can map these attributes for use by Google Cloud using Common Expression Language (CEL).

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

You can also define custom attributes in your IdP that can then be used by specific Google Cloud products; for example in IAM allow policies.

The maximum size for attribute mappings is 4 KB.

The attributes are as follows:

  • google.subject (Required): a unique identifier for the authenticating user. It is often the subject assertion of the JWT, because Cloud Audit Logs logs record the contents of this field as the principal. You can use this field to configure IAM for authorization decisions. We recommend that you don't use a mutable value because if you change 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 authenticating user is a member of. You can configure a logic expression using a subset of CEL that produces an array of strings. You can also use this field to configure IAM for authorization decisions. Limitations for google.groups are as follows:

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

    • If one user is associated with more than 100 groups, define a smaller set of groups, and only include those groups in assertions used to federate the user to Google Cloud. If one user belongs to more than 100 groups, authentication fails.

    • If you use this attribute to grant access in IAM, every member in the mapped groups is granted access. Therefore, we recommend that you ensure that only authorized users in your organization can modify the membership of the mapped groups.

  • google.display_name (Optional): attribute that is used to set the name of the signed-in user in the Google Cloud console. This attribute can't be used in IAM allow policies nor in the attribute condition.

    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, the image 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 is displayed instead. This attribute can't be used in either IAM allow policies or in the attribute condition.

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

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

  • attribute.KEY (Optional): a customer-defined attribute that is present in a user's IdP token. You can use these custom attributes to define your authorization strategy in an IAM allow policy. For example, you can choose to define an attribute such as the user's cost center: attribute.costcenter = "1234". This attribute could then be used in IAM conditions to grant access only to users in that cost center.

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

    Although we don't have restrictions on the attributes you can map here, we strongly recommend that you choose attributes whose values are stable. For example, an attribute like attribute.job_description might change for many reasons (such as improving its readability). As an alternative, consider using attribute.role. Changes to the latter indicate a change of assigned responsibility and align with changes in the access granted to the user.

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

  • 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 populates the custom attribute department by concatenating a list of strings with . 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 constraints on the identity attributes that Google Cloud accepts.

The benefits of using attribute conditions include the following:

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

Use attribute conditions when federating with GitHub or other multi-tenant identity providers

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

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

When you use these identity providers, it's insufficient to let Workforce Identity Federation check a token's issuer URL to ensure that it comes from a trusted source and that its claims can be trusted. If your multi-tenant IdP has a single issuer URL, we recommend that you must use attribute conditions to ensure that access is restricted to the correct tenant.

Represent workforce pool users in IAM policies

The following table shows the principal identifiers that you use to grant roles to a single user, a group of users, users carrying a particular claim, or all users from a workforce pool.

Identities Identifier format
Single identity in a workforce identity pool principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ATTRIBUTE_VALUE
All workforce identities in a group principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/group/GROUP_ID
All workforce identities with a specific attribute value principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
All identities in a workforce identity pool principalSet://iam.googleapis.com/locations/global/workforcePools/POOL_ID/*

JSON web keys

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

Restrict cross-organization access

Workforce identity pool principals can't directly access resources outside of the organization that they belong to. However, if a principal is given permission to impersonate a service account within the organization, this constraint can be bypassed as service accounts aren't equally restricted.

Workforce pools user project

Most Google Cloud APIs charge billing and quota use to the project that contains the resource that your API request accesses. These APIs are called resource-based APIs. A few Google Cloud APIs charge to the project associated with the client; these are called client-based APIs. The project used for billing and quota purposes is called the quota project.

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

For more information about the quota project, resource-based APIs, and client-based APIs, see Quota project overview.

Example: multiple workforce identity pools

This section contains an example that illustrates typical use of multiple pools.

You can create one pool for employees and another for partners. Multinational organizations might create separate pools for different divisions in their organization. Pools allow for distributed management, in which different groups can independently manage their specific pool where roles are granted only to the identities in the pool.

For example, suppose that a company named Enterprise Example Organization contracts a different company named Partner Example Organization Inc to provide Google Kubernetes Engine (GKE) DevOps services. For Partner Example Organization workforce to provide the services, their workforce must be allowed to access Google Kubernetes Engine (GKE) and other Google Cloud resources in Enterprise Example Organization's organization. Enterprise Example organization already has a workforce identity pool called enterprise-example-organization-employees.

To allow Partner Example Organization to manage access to Enterprise Example Organization's resources, Enterprise Example Organization creates a separate workforce pool for Partner Example Organization workforce users so that Partner Example Organization can manage it. Enterprise Example Organization provides the workforce pool to a Partner Example Organization administrator. Partner Example Organization's administrator uses their own IdP to grant access to their workforce.

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

  1. Create an identity such as partner-organization-admin@example.com for the Partner Example Organization administrator in Enterprise Example Organization's IdP, which is already configured in the pool called enterprise-example-organization-employees.

  2. Create a new workforce pool called example-organization-partner.

  3. Create the following allow policy for the example-organization-partner pool:

    {
  "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 for example-organization-partner pool on the resources they need access to in Enterprise Example Organization's organization.

Partner Example Organization's administrator can now configure the example-organization-partner pool to connect with their IdP. They can then allow Partner Example Organization workforce to sign in with Partner Example Organization's IdP credentials. After they sign in, Partner Example Organization workforce users can access Google Cloud resources, constrained by policies that are defined by Enterprise Example Organization.

Easier access management

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

Your organization might also have policies that limit the number of groups that you can create so as to keep the user directory hierarchy reasonably flat. A better solution to prevent misconfiguration of IAM policies and limit growth of groups is to use multiple pools to create a broader separation of users from different organizational units and business units, and partner organizations. You can then reference these pools and groups contained within these pools to define IAM policies (see examples in the Configuring IAM step).

VPC Service Controls limitations

Workforce Identity Federation, workforce pool configuration APIs, and Security Token Service APIs don't support VPC Service Controls. However, Google Cloud products that workforce pool users can access support VPC Service Controls. To learn more, see VPC Service Controls's supported products and limitations page.

Workforce Identity Federation and Essential Contacts

To receive important information about changes to your organization or Google Cloud products, you must provide Essential Contacts when using Workforce Identity Federation. Cloud Identity users can be contacted through their Cloud Identity email address, but Workforce Identity Federation users are 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 the Legal and Suspension category. Alternatively, you can define a contact in the All category if you don't have separate contacts. Supplying the contacts will remove the banner.

What's next