This guide shows you how configure Workforce Identity Federation using Okta as an identity provider (IdP), manage access, and sign in users to access Google Cloud services that support Workforce Identity Federation.
Before you begin
You must have a Google Cloud organization set up.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
For sign-in, your IdP must provide signed authentication information: OIDC IdPs must provide a JWT, and SAML IdP responses must be signed.
To receive important information about changes to your organization or Google Cloud products, you must provide Essential Contacts. For more information, see the Workforce Identity Federation overview.
Required roles
To get the permissions that you need to configure Workforce Identity Federation,
ask your administrator to grant you the
IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin
) IAM role on the organization.
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Alternatively, the IAM Owner (roles/owner
) basic role 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.
Create a workforce identity pool
Console
To create the workforce identity pool, do the following:
In the Google Cloud console, go to the Workforce Identity Pools page:
Click Create pool and do the following:
In the Name field, enter the display name of the pool. The pool ID is automatically derived from the name as you type, and it is displayed under the Name field. You can update the pool ID by clicking Edit next to the pool ID.
Optional: In Description, enter a description of the pool.
Session duration is set by default. To enter a custom session duration, click Edit. Session duration determines how long the Google Cloud access tokens, console (federated) sign-in sessions, and gcloud CLI sign-in sessions from this workforce pool are valid. The duration must be greater than 15 minutes (900s) and less than 12 hours (43200s). If session duration is not set, it defaults to a duration of one hour (3600s).
To create the pool in the enabled state, make sure that Enabled Pool is on.
To create the workforce identity pool, click Next.
gcloud
To create the workforce identity pool, run the following command:
gcloud iam workforce-pools create WORKFORCE_POOL_ID \
--organization=ORGANIZATION_ID \
--display-name="DISPLAY_NAME" \
--description="DESCRIPTION" \
--session-duration=SESSION_DURATION \
--location=global
Replace the following:
WORKFORCE_POOL_ID
: an ID that you choose to represent your Google Cloud workforce pool. For information on formatting the ID, see the Query parameters section in the API documentation.ORGANIZATION_ID
: the numeric organization ID of your Google Cloud organization.DISPLAY_NAME
: Optional. A display name for your workforce identity pool.DESCRIPTION
: Optional. A workforce identity pool description.SESSION_DURATION
: Optional. The session duration, which determines how long the Google Cloud access tokens, console (federated) sign-in sessions, and gcloud CLI sign-in sessions from this workforce pool are valid. The duration must be greater than 15 minutes (900s) and less than 12 hours (43200s). If session duration is not set, it defaults to a duration of one hour (3600s).
Create an Okta app integration
This section provides the steps to create an Okta app integration using the Okta Admin Console. For additional details, see Create custom app integrations.
Workforce pools support federation using both OIDC and SAML protocols.
Refer to Okta's OIDC and SAML integration guide for more details. The basic configuration is described in this section.
OIDC
To create an Okta app integration that uses the OIDC protocol, perform the following steps:
- Sign in to the Okta Admin Console.
- Go to Applications > Applications.
To begin configuring the app integration, do the following:
- Click Create App Integration.
- In Sign-in method, select OIDC - OpenID Connect.
- In Application type, select an application type; for example, Web Application.
- To create the app, click Next.
- In App integration name, enter a name for your app.
- In the Grant type section, select the Implicit (hybrid) checkbox.
In the Sign-in redirect URIs section, in the text field, enter a redirect URL. Your users are redirected to this URL after they successfully sign in. If you are configuring access to the console (federated), use the following URL format:
https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
Replace the following:
WORKFORCE_POOL_ID
: the ID of the workforce pool that you created earlier in this guide.WORKFORCE_PROVIDER_ID
: a workforce identity provider ID of your choice; for example:okta-oidc-provider
. For information on formatting the ID, see the Query parameters section in the API documentation.
Select the Skip group assignment for now checkbox.
To save the app integration, click Save.
Optional: To add custom attributes for an Okta user profile, do the following:
- In Data Type, select
string
. - In Display name, enter
Department
. - In Variable name, enter
department
. - To save the mapping, click Save.
To learn more about adding custom attributes, see Add custom attributes to an Okta user profile.
- In Data Type, select
Optional: To create mappings for the attributes that are sent in the OIDC token, in Directory, click Profile Editor, and do the following:
- Find the OIDC application that you created earlier in this guide.
- Click Mappings.
- Select the Okta User to App tab.
- In the Okta User User Profile tab, in an available combo box,
enter
department
. Okta auto-completes touser.department
. - To save the mappings, click Save Mappings. For more details, refer to Add attribute mapping.
To learn more about mappings, see refer to Map Okta attributes to app attributes in the Profile Editor.
Optional: To configure a groups claim, do the following:
- If you use an Org Authorization Server, do the following:
- Go to Applications > Applications
- Select the OpenID Connect client application that you created earlier in this section.
- Go to the Sign On tab
- In the OpenID Connect ID Token section, click Edit.
- In the Groups claim type section, you can select either of the
following options:
- Select Expression.
- Select Matches regex and enter
.*
.
- To save the groups claim, click Save.
- When you create the workforce identity pool provider later in this
guide, add
groups
as an additional scope to request the groups claim from Okta for web single sign-on. This step is only required if you use the console (federated) or gcloud CLI browser-based sign-in flow.
- If you use a Custom Authorization Server, do the following:
- In the Admin Console, from the Security menu, select API.
- Select the custom authorization server that you want to configure.
- Go to the Claims tab and click Add Claim.
- Enter a name for the claim. For this example, name it
groups
. - In your claim, in Include in token type, select ID Token and select Always.
- Select Groups as the Value type.
- In the Filter drop-down box, select Matches regex and then enter the following expression as the Value:
.*
- Click Create.
- If you use an Org Authorization Server, do the following:
For more details on groups claims, refer to Add a Groups claim.
SAML
To create an Okta app integration that uses the SAML protocol, perform the following steps:
- Sign in to the Okta Admin Console.
- Go to Applications > Applications.
- Click Create App Integration.
- In Sign-in method, select SAML 2.0 and click Next.
- Enter a name for your app and click Next to proceed to the Configure SAML options.
In Single Sign On URL, enter a redirect URL. This is the URL users are redirected to after they successfully sign in. If you are configuring access to the console, use the following URL format.
https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
Enter the Audience URI (
SP Entity ID
). The ID is formatted as follows:https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
Replace the following:
WORKFORCE_POOL_ID
: the ID of the workforce pool that you created earlier in this guideWORKFORCE_PROVIDER_ID
: a workforce identity provider ID of your choice; for example:okta-saml-provider
For information on formatting the ID, see the Query parameters section in the API documentation.
Optional: Use Attribute Statements to specify any custom attributes that you want to send in the SAML assertion. After setup, these attributes can be used in Google Cloud to create access management policies or in the attribute_condition; for example, in this guide you map the department as follows:
Name Value department
user.department
Optional: To add the groups claim, used later in this guide, see How to pass a user's group membership in a SAML assertion.
Finish creating the Okta app integration.
Create a workforce identity pool provider
This section describes how to create a workforce identity pool provider to enable your IdP users to access Google Cloud. You can configure the provider to use either the OIDC or SAML protocol.
Create an OIDC workforce pool provider
To create a workforce identity pool provider for your Okta app integration, using the OIDC protocol, do the following:
To get the client ID for your Okta app integration, do the following:
- Go to your Okta app integration.
- Click the General tab.
- Copy the contents of the Client ID field.
To create an OIDC workforce identity pool provider for web-based sign-in, do the following:
Console
Code flow
In Okta, do the following:
In Client authentication, select Client secret.
In the Client Secrets table, locate the secret and click content_copy Copy.
In the Google Cloud console, to create an OIDC provider that uses authorization code flow, do the following:
In the Google Cloud console, go to the Workforce Identity Pools page:
In the Workforce Identity Pools table, select the pool for which you want to create the provider.
In the Providers table, click Add Provider.
In Select a protocol, select Open ID Connect (OIDC).
In Create a pool provider, do the following:
- In Name, enter a name for the provider.
- In Issuer (URL), enter the issuer URI. The OIDC issuer URI must be in a valid URI format and start with
https
; for example,https://example.com/oidc
. - Enter the Client ID, the OIDC client ID that is registered
with your OIDC IdP; the ID must match the
aud
claim of the JWT that is issued by your IdP. - To create a provider that is enabled, make sure Enabled Provider is on.
- Click Continue.
In Response type do the following. Response type is used only for a web-based single-sign-on flow.
- In Response type, select Code.
- In Client secret, enter the client secret from your IdP.
In Assertion claims behavior, select either of the following:
- User info and ID token
- Only ID token
Click Continue.
In Configure provider, you can configure an attribute mapping and an attribute condition. To create an attribute mapping, do the following. You can provide either the IdP field name or a CEL-formatted expression that returns a string.
Required: In OIDC 1, enter the subject from the IdP; for example,
assertion.sub
.Optional: To add additional attribute mappings, do the following:
- Click Add mapping.
- In Google n, where n is a number, enter one of the Google Cloud-supported keys.
- In the corresponding OIDC n field, enter the name of the IdP-specific field to map, in CEL format.
To create an attribute condition, do the following:
- Click Add condition.
- In Attribute Conditions, enter a condition in CEL format;
for example,
assertion.subject.endsWith('@example.com')
when the value ofsubject
mapped earlier contains an email address that ends with@example.com
.
To create the provider, click Submit.
Implicit flow
In the Google Cloud Google Cloud console, do the following:
In the Google Cloud console, go to the Workforce Identity Pools page:
In the Workforce Identity Pools table, select the pool for which you want to create the provider.
In the Providers table, click Add Provider.
In Select a protocol, select Open ID Connect (OIDC).
In Create a pool provider, do the following:
- In Name, enter a name for the provider.
- In Issuer (URL), enter the issuer URI. The OIDC issuer URI must be in a valid URI format and start with
https
; for example,https://example.com/oidc
. - Enter the Client ID, the OIDC client ID that is registered
with your OIDC IdP; the ID must match the
aud
claim of the JWT that is issued by your IdP. - To create a provider that is enabled, make sure Enabled Provider is on.
- Click Continue.
In Response type do the following. Response type is used only for a web-based single-sign-on flow.
- In Response type, select ID token.
- Click Continue.
In Configure provider, you can configure an attribute mapping and an attribute condition. To create an attribute mapping, do the following. You can provide either the IdP field name or a CEL-formatted expression that returns a string.
Required: In OIDC 1, enter the subject from the IdP; for example,
assertion.sub
.Optional: To add additional attribute mappings, do the following:
- Click Add mapping.
- In Google n, where n is a number, enter one of the Google Cloud-supported keys.
- In the corresponding OIDC n field, enter the name of the IdP-specific field to map, in CEL format.
To create an attribute condition, do the following:
- Click Add condition.
In Attribute Conditions, enter a condition in CEL format; for example,
assertion.subject.endsWith('@example.com')
when the value ofsubject
mapped earlier contains an email address that ends with@example.com
.
To create the provider, click Submit.
gcloud
Code flow
In Okta, do the following:
In Client authentication, select Client secret.
In the Client Secrets table, locate the secret and click content_copy Copy.
In Google Cloud, to create an OIDC provider that uses authorization code flow for web sign-in, run 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="OIDC_CLIENT_ID" \
--client-secret-value="OIDC_CLIENT_SECRET" \ --web-sso-response-type="code" \ --web-sso-assertion-claims-behavior="merge-user-info-over-id-token-claims" \ --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \ --attribute-mapping="ATTRIBUTE_MAPPING" \ --attribute-condition="ATTRIBUTE_CONDITION" \ --jwk-json-path="JWK_JSON_PATH" \ --location=globalReplace the following:
PROVIDER_ID
: A unique provider ID. The prefixgcp-
is reserved and can't be used in a pool or provider ID.WORKFORCE_POOL_ID
: The workforce identity pool ID to connect your IdP to.DISPLAY_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 issuer URI, in a valid URI format, that starts withhttps
; for example,https://example.com/oidc
. Note: For security reasons,ISSUER_URI
must use the HTTPS scheme.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 IdP.OIDC_CLIENT_SECRET
: The OIDC client secret.WEB_SSO_ADDITIONAL_SCOPES
: Optional additional scopes to send to the OIDC IdP for console (federated) or gcloud CLI browser-based sign-in; for example,groups
to request the groups claim from Okta if using Okta's org authorization server.ATTRIBUTE_MAPPING
: An attribute mapping. The following is an example of an attribute mapping:
This example maps the IdP attributesgoogle.subject=assertion.sub, google.groups=assertion.group1, attribute.costcenter=assertion.costcenter
subject
,group1
, andcostcenter
in the OIDC assertion togoogle.subject
,google.groups
, andattribute.costcenter
attributes, respectively.ATTRIBUTE_CONDITION
: An attribute condition; for example,assertion.subject.endsWith('@example.com')
when the value ofsubject
mapped earlier contains an email address that ends with@example.com
.JWK_JSON_PATH
: An optional path to a locally uploaded OIDC JWKs. If this parameter isn't supplied, Google Cloud instead uses your IdP's/.well-known/openid-configuration
path to source the JWKs containing the public keys. For more information about locally uploaded OIDC JWKs, see manage OIDC JWKs.
locations/global/workforcePools/enterprise-example-organization-employees
.Implicit flow
To create an OIDC provider that uses the implicit flow for web sign-in, run 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="OIDC_CLIENT_ID" \ --web-sso-response-type="id-token" \ --web-sso-assertion-claims-behavior="only-id-token-claims" \ --web-sso-additional-scopes="WEB_SSO_ADDITIONAL_SCOPES" \ --attribute-mapping="ATTRIBUTE_MAPPING" \ --attribute-condition="ATTRIBUTE_CONDITION" \ --jwk-json-path="JWK_JSON_PATH" \ --location=global
Replace the following:
PROVIDER_ID
: A unique provider ID. The prefixgcp-
is reserved and can't be used in a pool or provider ID.WORKFORCE_POOL_ID
: The workforce identity pool ID to connect your IdP to.DISPLAY_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 issuer URI, in a valid URI format, that starts withhttps
; for example,https://example.com/oidc
. Note: For security reasons,ISSUER_URI
must use the HTTPS scheme.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 IdP.WEB_SSO_ADDITIONAL_SCOPES
: Optional additional scopes to send to the OIDC IdP for console (federated) or gcloud CLI browser-based sign-in; for example,groups
to request the groups claim from Okta if using Okta's org authorization server.ATTRIBUTE_MAPPING
: An attribute mapping. The following is an example of an attribute mapping:
This example maps the IdP attributesgoogle.subject=assertion.sub, google.groups=assertion.group1, attribute.costcenter=assertion.costcenter
subject
,group1
, andcostcenter
in the OIDC assertion togoogle.subject
,google.groups
, andattribute.costcenter
attributes, respectively.ATTRIBUTE_CONDITION
: An attribute condition; for example,assertion.subject.endsWith('@example.com')
when the value ofsubject
mapped earlier contains an email address that ends with@example.com
.JWK_JSON_PATH
: An optional path to a locally uploaded OIDC JWKs. If this parameter isn't supplied, Google Cloud instead uses your IdP's/.well-known/openid-configuration
path to source the JWKs containing the public keys. For more information about locally uploaded OIDC JWKs, see manage OIDC JWKs.
locations/global/workforcePools/enterprise-example-organization-employees
.
Create a SAML workforce pool provider
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, in your SAML IdP, set the redirect URL or Assertion Consumer Service (ACS) URL field to the following URL:
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 document. 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.
Console
To configure the SAML provider using the Google Cloud console, do the following:
In the Google Cloud console, go to the Workforce Identity Pools page:
In the Workforce Identity Pools table, select the pool for which you want to create the provider.
In the Providers table, click Add Provider.
In Select a protocol, select SAML.
In Create a pool provider do the following:
In Name, enter a name for the provider.
Optional: In Description, enter a description for the provider.
In IDP metadata file (XML), select the metadata XML file that you generated earlier in this guide.
Ensure that Enabled provider is enabled.
Click Continue.
In Configure provider, do the following:
In Attribute mapping, enter a CEL expression for
google.subject
.Optional: To enter other mappings, click Add mapping and enter other mappings—for example:
This example maps the IdP attributesgoogle.subject=assertion.subject, google.groups=assertion.attributes['https://example.com/aliases'], attribute.costcenter=assertion.attributes.costcenter[0]
assertion.subject
,assertion.attributes['https://example.com/aliases']
, andassertion.attributes.costcenter[0]
to the Google Cloud attributesgoogle.subject
,google.groups
, andgoogle.costcenter
, respectively.Optional: To add an attribute condition, click Add condition and enter a CEL expression representing an attribute condition. For example, to limit the
ipaddr
attribute to a certain IP range you can set the conditionassertion.attributes.ipaddr.startsWith('98.11.12.')
. This example condition ensures that only users with an IP address that starts with98.11.12.
can sign in using this workforce provider.Click Continue.
To create the provider, click Submit.
gcloud
To create a workforce identity pool provider for your Okta app integration, using the SAML protocol, do the following:
To save the SAML metadata for your Okta app, do the following:
- Go to your Okta App.
- Click the Sign On tab.
- In the SAML Signing Certificates section, click Actions > View IdP metadata for the active certificate.
- In the new page that opens, copy the XML metadata.
- Save the metadata as a local XML file.
To create a workforce provider for your Okta app, run the following command:
gcloud iam workforce-pools providers create-saml WORKFORCE_PROVIDER_ID \ --workforce-pool="WORKFORCE_POOL_ID" \ --attribute-mapping="ATTRIBUTE_MAPPING" \ --attribute-condition="ATTRIBUTE_CONDITION" \ --idp-metadata-path="XML_METADATA_PATH" \ --location="global"
Replace the following:
WORKFORCE_PROVIDER_ID
: The workforce provider ID that you created earlier in this guide.WORKFORCE_POOL_ID
: The workforce pool ID you created earlier in this guide.ATTRIBUTE_MAPPING
: An attribute mapping—for example:
This example maps the IdP attributesgoogle.subject=assertion.subject, google.groups=assertion.attributes['https://example.com/aliases'], attribute.costcenter=assertion.attributes.costcenter[0]
assertion.subject
,assertion.attributes['https://example.com/aliases']
, andassertion.attributes.costcenter[0]
to the Google Cloud attributesgoogle.subject
,google.groups
, andgoogle.costcenter
, respectively.ATTRIBUTE_CONDITION
: An optional attribute condition. For example, to limit theipaddr
attribute to a certain IP range you can set the conditionassertion.attributes.ipaddr.startsWith('98.11.12.')
. This example condition ensures that only users with an IP address that starts with98.11.12.
can sign in using this workforce provider.XML_METADATA_PATH
: The path to the XML-formatted metadata file for the Okta App that you created earlier in this guide.
The prefix
gcp-
is reserved and can't be used in a pool or provider ID.Optional: Accept encrypted SAML assertions from your IdP
To enable your SAML 2.0 IdP to produce encrypted SAML assertions that can be accepted by workforce identity federation, do the following:
- In workforce identity federation, do the following:
- Create an asymmetric key pair for your workforce identity pool provider.
- Download a certificate file that contains the public key.
- Configure your SAML IdP to use the public key to encrypt SAML assertions it issues.
- In your IdP, do the following:
- Enable assertion encryption, also known as token encryption.
- Upload the public key that you created in workforce identity federation.
- Confirm that your IdP produces encrypted SAML assertions.
Create workforce identity federation SAML assertion encryption keys
This section guides you through creating an asymmetric key pair that enables workforce identity federation to accept encrypted SAML assertions.
Google Cloud uses the private key to decrypt the SAML assertions that your IdP issues. To create an asymmetric key pair for use with SAML encryption, run the following command. To learn more, see Supported SAML encryption algorithms.
gcloud iam workforce-pools providers keys create KEY_ID \ --workforce-pool WORKFORCE_POOL_ID \ --provider PROVIDER_ID \ --location global \ --use encryption \ --spec KEY_SPECIFICATION
Replace the following:
KEY_ID
: a key name of your choiceWORKFORCE_POOL_ID
: the pool IDPROVIDER_ID
: the provider ID-
KEY_SPECIFICATION
: the key specification, which can be one ofrsa-2048
,rsa-3072
, andrsa-4096
.
After the key pair is created, to download the public key into a certificate file, execute the following command. Only workforce identity federation has access to the private key.
gcloud iam workforce-pools providers keys describe KEY_ID \ --workforce-pool WORKFORCE_POOL_ID \ --provider PROVIDER_ID \ --location global \ --format "value(keyData.key)" \ > CERTIFICATE_PATH
Replace the following:
KEY_ID
: the key nameWORKFORCE_POOL_ID
: the pool IDPROVIDER_ID
: the provider IDCERTIFICATE_PATH
: the path to write the certificate to—for example,saml-certificate.cer
orsaml-certificate.pem
Configure your SAML 2.0-compliant IdP to issue encrypted SAML assertions
To configure Okta to encrypt SAML assertions, do the following:
- Go to your Okta dashboard and sign in.
- Go to Applications>Applications.
- Click on your app.
- In the General tab, in the SAML Settings section, click Edit.
- Click Next to view SAML Settings.
- Click Show advanced settings.
- In SAML Settings, do the following:
- In either of Response (preferred) or Assertion Signature, select
Signed
. - In Signature Algorithm and Digest Algorithm, select any option.
- Set the following values:
- Assertion Encryption: Encrypted.
- Encryption Algorithm: Any algorithm that you choose.
- Encryption Certificate: Upload the certificate file that you generated earlier in this guide.
- To save the configuration, click Next and then Finish
After you configure your IdP to encrypt SAML assertions, we recommend that you check to make sure that the assertions it generates are actually encrypted. Even with SAML assertion encryption configured, workforce identity federation can still process plaintext assertions.
Delete workforce identity federation encryption keys
To delete SAML encryption keys run the following command:gcloud iam workforce-pools providers keys delete KEY_ID \ --workforce-pool WORKFORCE_POOL_ID \ --provider PROVIDER_ID \ --location global
Replace the following:
KEY_ID
: the key nameWORKFORCE_POOL_ID
: the pool IDPROVIDER_ID
: the provider ID
Supported SAML encryption algorithms
Workforce identity federation supports the following key transport algorithms:
- http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
- http://www.w3.org/2009/xmlenc11#rsa-oaep"
- http://www.w3.org/2001/04/xmlenc#rsa-1_5"
Workforce identity federation supports the following block encryption algorithms:
Manage access to Google Cloud resources
This section provides an example that shows you how to manage access to Google Cloud resources by Workforce Identity Federation users.
In this example, you grant an Identity and Access Management (IAM) role on a sample project. Users can then sign in and use this project to access Google Cloud products.
You can manage IAM roles for single identities, group of identities, or an entire pool. For more information, see Represent workforce identity pool users in IAM policies.
For single identity
To grant the Storage Admin (roles/storage.admin
) role to a single identity
for project
TEST_PROJECT_ID
, run the following command:
gcloud projects add-iam-policy-binding TEST_PROJECT_ID \
--role="roles/storage.admin" \
--member="principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_VALUE"
Replace the following:
TEST_PROJECT_ID
: ID of the projectWORKFORCE_POOL_ID
: the workforce identity pool IDSUBJECT_VALUE
: the user identity
Using mapped department attribute
To grant the Storage Admin (roles/storage.admin
) role to all identities
within a specific department for project
TEST_PROJECT_ID
, run the following command:
gcloud projects add-iam-policy-binding TEST_PROJECT_ID \
--role="roles/storage.admin" \
--member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.department/DEPARTMENT_VALUE"
Replace the following:
TEST_PROJECT_ID
: ID of the projectWORKFORCE_POOL_ID
: the workforce pool IDDEPARTMENT_VALUE
: the mappedattribute.department
value
Using mapped groups
To grant the Storage Admin (roles/storage.admin
) role to all identities within
a specific group for project TEST_PROJECT_ID
,
run the following command:
gcloud projects add-iam-policy-binding TEST_PROJECT_ID \
--role="roles/storage.admin" \
--member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"
Replace the following:
TEST_PROJECT_ID
: ID of the projectWORKFORCE_POOL_ID
: the workforce pool IDGROUP_ID
: a group in the mappedgoogle.groups
claim.
Sign in and test access
In this section, you sign in as a workforce identity pool user and test that you have access to a Google Cloud product.
Sign in
This section shows you how to sign in as a federated user and access Google Cloud resources.
Console (federated) sign-in
To sign in to the Google Cloud Workforce Identity Federation console, also known as the console (federated), do the following:
-
Go to the console (federated) sign-in page.
-
Enter the provider name, which is formatted as follows:
locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
- Enter user credentials in the Okta app integration, if prompted.
If you start an IdP-initiated sign-in, use the following URL in SAML
Settings for the nested Default RelayState parameter:
https://console.cloud.google/
.
gcloud CLI browser-based sign-in
To sign in to gcloud CLI using a browser-based sign-in flow, do the following:
Create a configuration file
To create the login configuration file, run the following command. You can optionally activate
the file as the default for the gcloud CLI by using the
--activate
flag.
gcloud iam workforce-pools create-login-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \ --output-file=LOGIN_CONFIG_FILE
Replace the following:
WORKFORCE_POOL_ID
: the workforce pool IDPROVIDER_ID
: the provider IDLOGIN_CONFIG_FILE
: a path to the configuration file that you specify—for example,login.json
The file contains contains the endpoints used by the gcloud CLI to enable the browser-based authentication flow and set the audience to the provider you created earlier in this guide. The file doesn't contain confidential information.
The output looks similar to the following:
{ "type": "external_account_authorized_user_login_config", "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID", "auth_url": "https://auth.cloud.google/authorize", "token_url": "https://sts.googleapis.com/v1/oauthtoken", "token_info_url": "https://sts.googleapis.com/v1/introspect", }
Sign in using browser-based authentication
To authenticate using browser-based sign-in authentication, you can use one of the following methods:
-
If you used the
--activate
flag when you created the configuration file, or if you activated the configuration file withgcloud config set auth/LOGIN_CONFIG_FILE
, the gcloud CLI uses your configuration file automatically:gcloud auth login
-
To sign in by specifying the location of the configuration file, run the following command:
gcloud auth login --login-config=LOGIN_CONFIG_FILE
-
To use an environment variable to specify the location of the configuration
file, set
CLOUDSDK_AUTH_LOGIN_CONFIG_FILE
to the configuration path.
Disable browser-based sign-in
To discontinue using the login configuration file, do the following:
-
If you used the
--activate
flag when you created the configuration file, or if you activated the configuration file withgcloud config set auth/LOGIN_CONFIG_FILE
, you must run the following command to unset it:gcloud config unset auth/login_config_file
-
Clear the
CLOUDSDK_AUTH_LOGIN_CONFIG_FILE
environment variable, if it is set.
gcloud CLI headless sign-in
To sign in to gcloud CLI, using a headless flow, do the following:
OIDC
Sign in a user to your Okta app and get the OIDC token from Okta.
Save the OIDC token returned by Okta in a secure location on your local machine.
Generate a configuration file as below. Run the following command:
gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \ --subject-token-type="urn:ietf:params:oauth:token-type:id_token" \ --credential-source-file="PATH_TO_OIDC_ID_TOKEN" \ --workforce-pool-user-project="WORKFORCE_POOL_USER_PROJECT" \ --output-file="config.json"
Replace the following:
WORKFORCE_POOL_ID
: the workforce pool IDPROVIDER_ID
: the provider IDPATH_TO_OIDC_TOKEN
: the path to the OIDC IdP credential fileWORKFORCE_POOL_USER_PROJECT
: the project number associated with the workforce pools user project
The principal must have serviceusage.services.use
permission on this
project.
When you run the command, it produces an OIDC IdP config file that is formatted similar to the following:
{
"type": "external_account",
"audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
"subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
"token_url": "https://sts.googleapis.com/v1/token",
"workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
"credential_source": {
"file": "PATH_TO_OIDC_CREDENTIALS_FILE"
}
}
SAML
Sign in a user to your Okta app and get the SAML Response from Okta.
Save the SAML Response returned by Okta in a secure location on your local machine, then store the path, as follows:
SAML_ASSERTION_PATH=SAML_ASSERTION_PATH
To generate a configuration file, run the following command:
gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \ --subject-token-type="urn:ietf:params:oauth:token-type:saml2" \ --credential-source-file="SAML_ASSERTION_PATH" \ --workforce-pool-user-project="PROJECT_ID" \ --output-file="config.json"
Replace the following:
WORKFORCE_PROVIDER_ID
: the workforce provide ID you created earlier in this guide.WORKFORCE_POOL_ID
: the workforce pool ID you created earlier in this guide.SAML_ASSERTION_PATH
: the path of the SAML assertion file.PROJECT_ID
: the project ID
The configuration file that is generated looks similar to the following:
{ "type": "external_account", "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID", "subject_token_type": "urn:ietf:params:oauth:token-type:saml2", "token_url": "https://sts.googleapis.com/v1/token", "credential_source": { "file": "SAML_ASSERTION_PATH" }, "workforce_pool_user_project": "PROJECT_ID" }
To login to gcloud
using token exchange, run the following command:
gcloud auth login --cred-file="config.json"
gcloud
then transparently exchanges your Okta credentials for temporary
Google Cloud access tokens, allowing you to make other gcloud
calls to Google Cloud.
You see output similar to the following:
Authenticated with external account user credentials for: [principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID
/subject/USER_ID
].
To list the credentialed accounts and the currently active account, run the following command:
gcloud auth list
Test access
You now have access to Google Cloud services that support
Workforce Identity Federation and to which you are granted access. Earlier in
this guide, you granted the Storage Admin (roles/storage.admin
) role to all
identities within a specific department for project
TEST_PROJECT_ID
. You can now test that you have access
by listing Cloud Storage buckets.
Console (federated)
To list Cloud Storage buckets using the console (federated), do the following:
- Go to the Cloud Storage page.
- Verify that you can see list of existing buckets for the
TEST_PROJECT_ID
gcloud CLI
To list Cloud Storage buckets and objects for the project that you have access to, run the following command:
gcloud storage ls --project="TEST_PROJECT_ID"
The principal must have the serviceusage.services.use
permission on the
specified project.
Delete users
Workforce Identity Federation creates user metadata and resources for federated user identities. If you choose to delete users, in your IdP, for example, you must also explicitly delete these resources in Google Cloud. To do so, see Delete Workforce Identity Federation users and their data.
You might see resources continue to be associated with a user that was deleted. This is because deleting user metadata and resources requires a long-running operation. After you initiate a deletion of a user's identity, processes that the user initiated before the deletion can continue to run until the processes complete or are canceled.
What's next
- Delete Workforce Identity Federation users and their data
- Learn which Google Cloud products support Workforce Identity Federation
- Set up user access to console (federated)