Workforce Identity Federation (original) (raw)

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

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

Federation versus synchronization

Workforce Identity Federation federates identities from your IdP, so it doesn't store user accounts in Google Cloud. Because of this, Workforce Identity Federation is syncless, meaning that you don't need to use tools to synchronize user identities from your IdP to Google-managed identities that require Google Accounts. For example, by using Workforce 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, see Workload Identity Federation.

Attribute-based access

Workforce Identity Federation extends Google Cloud's identity capabilities to support attribute-based access. In some IdPs, attributes are also known as claims or assertions.

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

Supported protocols

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.

Key concepts

This section describes the key concepts of Workforce Identity Federation.

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:

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, which motivates the following considerations:

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 bothauthorization code flowand 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.

SCIM support

If your IdP supports System 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 in Gemini Enterprise. After you configure SCIM tenants in your IdP application and in Workforce Identity Federation, Gemini Enterprise users can share NotebookLM notebooks with a group using the group's name instead of its object ID (UUID). To learn more about sharing notebooks with groups, see Share a notebooks with a group.

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

SCIM capabilities

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

Limitations

The following features are not supported:

Attributes

Your IdP provides attributes, referred to by some IdPs as claims. Attributes contain information about your users. You can use these attributes inattribute mappings and attribute 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 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 16 KB. If the size of attribute mappings exceeds the 16 KB limit, the sign-in attempt will fail.

The attributes are as follows:

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

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:

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 samegoogle.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, you must use attribute conditions to ensure that access is restricted to the correct tenant.

Detailed audit logging

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

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

To learn how to troubleshoot attribute mapping errors with detailed audit logging, see General attribute mapping errors.

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.

Workforce principal identifiers for IAM policies

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

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/*

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 resources outside of the organization that they belong to. However, if a principal is given permission to impersonate a service accountwithin 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 theserviceusage.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 calledenterprise-example-organization-employees.
  2. Create a new workforce pool called example-organization-partner.
  3. Create the following allow policy for the example-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"  
      ]  
    }  
  ]  
}
  1. 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 theexample-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.

Security groups best practices

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 administrative features, including workforce pool configuration APIs, and Security Token Service APIs don't support VPC Service Controls. However, Google Cloud products that support both Workforce Identity Federationand VPC Service Controls operate as documented and are subject to VPC Service Controls policy checks. Additionally, you can use third-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 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 theLegal 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