Configure workforce identity federation with Okta and sign in users

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

1. You must have a Google Cloud organization set up.

2. Identify a billing/quota project.

   Note: Ask your Google Cloud account team for access to workforce identity federation for this project. The account team notifies you when the project is granted access. Workforce identity federation supports a limited number of Google Cloud products. To learn more, see Workforce identity federation: supported products and limitations.

   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.

3. Install the Google Cloud CLI, then initialize it by running the following command:

   gcloud init

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

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.

Alternatively, the IAM Owner (roles/owner) basic role also includes permissions to configure 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 federation pool

To create the workforce identity federation pool, run the following command:

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization="ORGANIZATION_ID" \
    --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.

Tip: Run gcloud iam workforce-pools create --help to find other parameters you can customize for this command.

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.

Note: In this guide, you create a custom attribute called department to demonstrate attribute mapping. This task is for illustrative purposes only.

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:

1. Sign in to the Okta Admin Console.
2. Go to Applications > Applications.

3. To begin configuring the app integration, do the following:

   1. Click Create App Integration.
   2. In Sign-in method, select OIDC - OpenID Connect.
   3. In Application type, select an application type; for example, Web Application.
   4. To create the app, click Next.
   5. In App integration name, enter a name for your app.
   6. In the Grant type section, select the Implicit (hybrid) checkbox.

   7. 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.

   8. Select the Skip group assignment for now checkbox.

   9. To save the app integration, click Save.

4. Assign an app integration to a user.

5. Optional: To add custom attributes for an Okta user profile, do the following:

   1. In Data Type, select string.
   2. In Display name, enter Department.
   3. In Variable name, enter department.
   4. To save the mapping, click Save.

   To learn more about adding custom attributes, see Add custom attributes to an Okta user profile.

6. Optional: To create mappings for the attributes that are sent in the OIDC token, in Directory, click Profile Editor, and do the following:

   1. Find the OIDC application that you created earlier in this guide.
   2. Click Mappings.
   3. Select the Okta User to App tab.
   4. In the Okta User User Profile tab, in an available combo box, enter department. Okta auto-completes to user.department.
   5. 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.

7. Optional: To configure a groups claim, do the following:

   1. Go to Applications > Applications
   2. Select the OpenID Connect client application that you created earlier in this section.
   3. Go to the Sign On tab
   4. In the OpenID Connect ID Token section, click Edit.
   5. In the Groups claim type section, you can select either of the following options:
      • Select Expression.
      • Select Matches regex and enter .*.

8. To save the groups claim, click Save.

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:

1. Sign in to the Okta Admin Console.
2. Go to Applications > Applications.
3. Click Create App Integration.
4. In Sign-in method, select SAML 2.0 and click Next.
5. Enter a name for your app and click Next to proceed to the Configure SAML options.
6. 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
   

   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-saml-provider. For information on formatting the ID, see the Query parameters section in the API documentation.

1. 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 guide

• WORKFORCE_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 federation pool provider

OIDC

To create a workforce identity federation pool provider for your Okta app integration, using the OIDC protocol, do the following:

1. To get the client ID for your Okta app integration, do the following:

   1. Go to your Okta app integration.
   2. Click the General tab.
   3. Copy the contents of the Client ID field.

2. To create a workforce provider for your Okta app, run the following command:

   gcloud iam workforce-pools providers create-oidc WORKFORCE_PROVIDER_ID \
       --workforce-pool="WORKFORCE_POOL_ID" \
       --display-name="DISPLAY_NAME" \
       --description="DESCRIPTION" \
       --issuer-uri="OIDC_ISSUER_URL" \
       --client-id="OIDC_CLIENT_ID" \
       --attribute-mapping="ATTRIBUTE_MAPPING" \
       --attribute-condition="ATTRIBUTE_CONDITION" \
       --location="global"
   

   Replace the following:

   • PROVIDER_ID the provider ID
   • WORKFORCE_POOL_ID: the workforce pool ID
   • DISPLAY_NAME: the display name
   • DESCRIPTION: the description
   • OIDC_ISSUER_URL: the OIDC issuer URL, your Okta organizational or custom domain
   • OIDC_CLIENT_ID: the OIDC client ID from the General tab of your Okta application settings

   • ATTRIBUTE_MAPPING: the attribute mapping; for example,

     
     google.subject=assertion.sub,
     google.groups=assertion.groups,
     google.display_name=assertion.name,
     attribute.department=assertion.department
     

   • ATTRIBUTE_CONDITION: an optional attribute condition; for example, assertion.subject.endsWith('@example.com') when the value of Name ID mapped earlier contains email address.

   This command assigns the subject, groups, name, and department in the OIDC assertion to google.subject, google.groups, google.display_name and attribute.department attributes, respectively. Additionally, the attribute condition ensures that only users with a subject ending in @example.com can sign in using this workforce provider.

   Note: For security reasons, OIDC_ISSUER_URL must use the HTTPS scheme.

SAML

To create a workforce identity federation pool provider for your Okta app integration, using the SAML protocol, do the following:

1. To save the SAML metadata for your Okta app, do the following:

   1. Go to your Okta App.
   2. Click the Sign On tab.
   3. In the SAML Signing Certificates section, click Actions > View IdP metadata for the active certificate.
   4. In the new page that opens, copy the XML metadata.
   5. Save the metadata as a local XML file.

2. 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, to map a subject, the mapping is as follows:

     
     google.subject=assertion.subject,
     google.groups=assertion.attributes.groups,
     attribute.department=assertion.attributes.department[0]
     

   • ATTRIBUTE_CONDITION: an optional attribute condition; for example, assertion.subject.endsWith("@example.com")

   • XML_METADATA_PATH: the path to the XML-formatted metadata file for the Okta App that you created earlier in this guide.

   This command assigns the subject and department in the SAML assertion to google.subject and attribute.department attributes, respectively. Additionally, the attribute condition ensures that only users with a subject ending in @example.com can sign in using this workforce provider.

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.

Note: The sample project used here can be different from the project you used to set up workforce identity federation.

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.

Note: You must grant the Browser role (roles/browser) to all workforce identity federation users that access the Google Cloud workforce identity federation console, also known as the console (federated). You don't need to grant the role if the user accesses Google Cloud resources through the Google Cloud CLI.

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 project
• WORKFORCE_POOL_ID: the workforce pool ID
• DEPARTMENT_VALUE: the mapped attribute.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 project
• WORKFORCE_POOL_ID: the workforce pool ID
• GROUP_ID: a group in the mapped google.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)

To sign in to the console (federated), do the following:

1. Go to the console (federated) sign-in page.

   Go to console (federated)

2. Enter the provider name, which is formatted as follows:

   locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

3. Enter user credentials in the Okta app integration, if prompted.

Note: If you start an IdP-initiated sign-in, use the following URL for the nested RelayState parameter: https://console.cloud.google/.

gcloud CLI

To sign in using gcloud CLI, do the following:

OIDC

1. Sign in a user to your Okta app and get the OIDC token from Okta.

2. Save the OIDC token returned by Okta in a secure location on your local machine.

3. 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 ID
• PROVIDER_ID: the provider ID
• PATH_TO_OIDC_TOKEN: the path to the OIDC IdP credential file
• WORKFORCE_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

1. Sign in a user to your Okta app and get the SAML Response from Okta.

2. 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
   

3. 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 alpha storage ls --project="TEST_PROJECT_ID"

The principal must have the serviceusage.services.use permission on the billing/quota project set in the gcloud CLI session: PROJECT_ID.

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)