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

You must have a Google Cloud organization set up.
Identify a billing/quota project.

Note: Ask your Google Cloud account team to request access to workforce identity federation for this project. The account team notifies you when the project is granted access.

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

Name	Value
`email`	`user.email`
`department`	`user.department`

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:

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.

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:

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

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"
}

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

Delete workforce identity federation users and their data
Learn which Google Cloud products support workforce identity federation
Set up user access to console (federated)