This guide describes how to configure workforce identity federation with an identity provider (IdP) that supports OIDC or SAML 2.0.
For IdP-specific instructions, see the following:
- Configure Azure AD-based workforce identity federation
- Configure Okta-based workforce identity federation
Before you begin
You must have a Google Cloud organization set up.
Identify a billing/quota project.
To set the Google Cloud project that is billed and charged quota for operations performed in the gcloud CLI, execute the following command:
gcloud config set billing/quota_project PROJECT_ID
Replace PROJECT_ID with the project ID.
Enable the Identity and Access Management (IAM) and Resource Manager APIs.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
Required roles
To get the permissions that you need to configure workforce identity federation,
ask your administrator to grant you the
Workforce Identity Pool Admin (roles/iam.workforcePoolAdmin
) IAM role on the organization.
For more information about granting roles, see
Manage access.
Alternatively, the Owner basic role (roles/owner
) also
includes permissions to configure workforce identity federation.
You should not grant basic roles in a production environment, but you can grant them in a
development or test environment.
Configure workforce identity federation
To configure workforce identity federation you create a workforce identity federation pool and a workforce identity federation pool provider.
Create a workforce identity pool
To create the pool, execute the following command:
gcloud iam workforce-pools create WORKFORCE_POOL_ID \
--organization=ORGANIZATION_ID \
--description="DESCRIPTION" \
--location=global
Replace the following:
WORKFORCE_POOL_ID
: the workforce identity pool IDORGANIZATION_ID
: the numeric organization IDDESCRIPTION
: a workforce identity pool description
Create a workforce identity pool provider
You can configure workforce identity pool providers in the following ways:
OIDC
To configure the OIDC provider, perform the following steps:
In your OIDC IdP, register a new application for Google Cloud workforce identity federation. Note the client ID and issuer URI provided by the IdP. You use them in this document.
If you plan to set up user access to the console, add the following redirect URL to your OIDC IdP:
https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
To learn how to configure console (federated) sign-in, see Set up user access to the console (federated).
In Google Cloud, create an OIDC workforce identity pool provider by executing the following command:
gcloud iam workforce-pools providers create-oidc PROVIDER_ID \
--workforce-pool=WORKFORCE_POOL_ID \
--display-name="DISPLAY_NAME" \
--description="DESCRIPTION" \
--issuer-uri="ISSUER_URI" \
--client-id="CLIENT_ID" \
--attribute-mapping="ATTRIBUTE_MAPPING" \
--attribute-condition="ATTRIBUTE_CONDITION" \
--location=global
Replace the following:
PROVIDER_ID
: a unique provider IDWORKFORCE_POOL_ID
: the workforce identity pool ID to connect your IdP toDISPLAY_NAME
an optional user-friendly display name for the provider; for example,idp-eu-employees
DESCRIPTION
: an optional workforce provider description; for example,IdP for Partner Example Organization employees
ISSUER_URI
: the OIDC issue URI that Issuer, in a valid URI format, that starts withhttps
; for example,https://example.com/oidc
CLIENT_ID
: the OIDC client ID that is registered with your OIDC IdP; the ID must match theaud
claim of the JWT that is issued by your IdPATTRIBUTE_MAPPING
: an attribute mapping; for example,google.subject=assertion.sub, google.groups=[assertion.group1,assertion.group2], attribute.costcenter=assertion.costcenter
ATTRIBUTE_CONDITION
: an attribute condition; for example,assertion.role == 'gcp-users'
For OIDC federation, you can use assertion.NAME
: a string equal
to the value of the like-named claim in the ID token payload.
SAML
To configure the SAML provider, perform the following steps:
In your SAML IdP, register a new application for Google Cloud workforce identity federation.
Set the audience for SAML assertions. It is usually the
SP Entity ID
field in your IdP configuration. You must set it to the following URL:https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID
If you plan to set up user access to the console, add the following redirect URL to your SAML IdP:
https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
See Set up user access to the console for more details on configuring Console Sign-in.
In Google Cloud, create a SAML workforce identity pool provider using your IdP's SAML metadata doc. You can download the SAML metadata XML document from your IdP. The document must include at least the following:
- A SAML entity ID for your IdP
- The single-sign-on URL for your IdP
- At least one signing public key.
See Key requirements later in this guide for details on signing keys.
gcloud iam workforce-pools providers create-saml PROVIDER_ID \ --workforce-pool=WORKFORCE_POOL_ID \ --display-name="DISPLAY_NAME" \ --description="DESCRIPTION" \ --idp-metadata-path=METADATA_FILE_PATH \ --attribute-mapping="ATTRIBUTE_MAPPING" \ --attribute-condition="ATTRIBUTE_CONDITION" \ --location=global
Replace the following:
PROVIDER_ID
: the provider ID.WORKFORCE_POOL_ID
: the pool ID.DISPLAY_NAME
the display name for the provider; for example,idp-eu-employees
DESCRIPTION
: the description for the workforce identity pool provider; for example,IdP for Partner Example Organization EU employees
.METADATA_FILE_PATH
: the file path of the SAML metadataATTRIBUTE_MAPPING
: the attribute mapping; for example,google.subject=assertion.subject, google.groups=assertion.attributes.groupList, attribute.costcenter=assertion.attributes.costcenter[0]
ATTRIBUTE_CONDITION
: an attribute condition; for example:assertion.attributes.role[0] == 'gcp-users'
For SAML federation, you can use the following keywords in attribute mappings and conditions:
assertion.subject
: a string equal to theNameID
attribute in the SAML assertion.assertion.attributes.NAME
: a string list equal to the values of the like-named attributes in the SAML assertion.
Key requirements
The following key specifications apply to SAML:
An RSA public key that is wrapped in an X.509 v3 certificate.
Certificate validity requirements:
notBefore
: a timestamp of no more than 7 days in the future.notAfter
: a timestamp no more than 14 years in the future.
Recommended algorithms:
- RSAwithSHA256 (supported key sizes (bits): 2048, 3072, 4096)
- ECDSAwithSHA256
A workforce identity pool provider can be configured with at most three signing keys at a given time. When multiple keys exist, Google Cloud iterates through them and attempts to use each non-expired key to fulfill a token exchange request.
As a security best practice, we strongly recommend that you don't reuse the same key pair with other services.
Key management
To update your IdP's signing keys, do the following:
Create a new asymmetric key pair and configure the SAML identity provider with the key pair. You initially mark it as inactive before activating it in a later step.
Download a SAML metadata XML document from your IdP.
Update the workforce identity pool provider resource using the SAML metadata document. When multiple keys exist, Google Cloud iterates through each non-expired key and attempts to it to fulfill a token exchange request.
To update the workforce identity pool provider with the SAML metadata, execute the following command.
gcloud iam workforce-pools providers update-saml PROVIDER_ID \ --workforce-pool=WORKFORCE_POOL_ID \ --idp-metadata-path=SAML_METADATA_FILE_PATH \ --location=global
Replace the following:
PROVIDER_ID
: the provider IDWORKFORCE_POOL_ID
: the workforce identity pool IDSAML_METADATA_FILE_PATH
: the path to the SAML metadata file
Wait for the operation returned from the previous step to complete (the operation is marked as done), and then in your SAML IdP, activate the new signing key. The old signing key is marked as inactive. Assertions issued by your IdP are signed using the new key.
The following steps are optional, but we recommend you perform them as a best practice:
- Delete the old, now inactive, signing key from your IdP.
- Download the SAML metadata XML document from your IdP.
Update the workforce identity pool provider resource using the SAML metadata document. Google Cloud refuses assertions that are signed with the expired signing key. To update the document, execute the following command:
gcloud iam workforce-pools providers update-saml PROVIDER_ID \ --workforce-pool=WORKFORCE_POOL_ID \ --idp-metadata-path=SAML_METADATA_FILE_PATH \ --location=global
Replace the following:
PROVIDER_ID
: the provider IDWORKFORCE_POOL_ID
: the workforce identity pool IDSAML_METADATA_FILE_PATH
: the SAML metadata file path
Key deletion constraint
Google Cloud refuses assertions signed with a deleted key.
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/*
|
Grant IAM roles to principals
You can grant roles to principals, such as single identities, groups of identities, or an entire pool.
To grant a role on a project to a principal, execute the following command:
gcloud projects add-iam-policy-binding PROJECT_ID \
--role="ROLE" \
--member="PRINCIPAL"
Replace the following:
PROJECT_ID
: the project IDROLE
: the role to setPRINCIPAL
: the principal; see Representing workforce identity pool users in IAM policies.
In the example that follows, the command grants the Storage Admin
(roles/storage.admin
) to all identities within the group
GROUP_ID
:
gcloud projects add-iam-policy-binding my-project \
--role="roles/storage.admin" \
--member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"
For more information about the principal format, see Represent workforce identity pool users in IAM policies.
What's next
- Obtain short-lived credentials for workforce identity federation
- Manage workforce identity pool providers
- Delete workforce identity federation users and their data
- Learn which Google Cloud products support workforce identity federation
- Set up user access to console (federated)