Configure workforce identity federation with Okta and sign in users

Stay organized with collections Save and categorize content based on your preferences.

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.

    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 and initialize the Google Cloud CLI.

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 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 an Okta app

Create an Okta App using the Okta Admin Dashboard. For detailed steps to create a custom app integration, see Create custom app integrations.

Workforce pools support federation using both OIDC and SAML protocols.

We recommend that you use the SAML protocol, as described in this section.

  • Login to the Okta admin dashboard.
  • 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.
  • 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 create later in this guide.
    • WORKFORCE_PROVIDER_ID: the ID of the workforce provider that you create later in this guide.
  • Use Attribute Statements to specify the custom attributes in the generated SAML assertions. After set up, these can be used in Google Cloud to create access management policies; for example, in this guide we'll map the user's email and department as follows:

    Name Value
    email user.email
    department user.department
  • Finish creating the Okta app.

Configure workforce identity federation

This section describes how to configure federation in Google Cloud using Okta as an IdP.

Create a workforce identity federation pool

To create the workforce identity federation pool itself, execute the following command:

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
  --organization=ORGANIZATION_ID \
  --location=global

Replace the following:

  • WORKFORCE_POOL_ID: an ID you choose to represent your Google Cloud workforce pool.
  • ORGANIZATION_ID: the numeric organization ID of your Google Cloud organization.

Save the SAML metadata

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.

Create a workforce identity federation pool provider

To create a workforce provider for your Okta app, execute 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,

    google.subject=assertion.subject, 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

This section describes how to configure Identity and Access Management (IAM) policies for principals.

You can define IAM policies for single identities, group of identities, or an entire pool. For more information, see Represent workforce identity pool users in IAM policies.

To grant the Storage Admin (roles/storage.admin) role to all identities within a specific department for project my-project, execute the following command:

gcloud projects add-iam-policy-binding my-project \
    --role="roles/storage.admin" \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.department/DEPARTMENT_VALUE"

Replace the following:

  • WORKFORCE_POOL_ID: the workforce pool ID
  • DEPARTMENT_VALUE: the mapped attribute.department value

Sign in with the gcloud CLI

To sign in with workforce, do the following:

  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. Generate a configuration file as below. 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"
      }
      
  4. 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].

  5. To list the credentialed accounts and the currently active account, execute 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. For example, you can list Cloud Storage buckets and objects the project you have access to.

To verify that you have access, execute the following command:

gcloud alpha storage ls --project=my-project

The principal must have the serviceusage.services.use permission on the billing/quota project: PROJECT_ID.

What's next