Configure workload connection

The workload connection is the trust anchor that establishes the relationship between Okta Privileged Access and your external identity provider, such as GitHub, GitLab, or CircleCI. This setup uses a split-duty security model: a DevOps admin configures and tests the connection in draft mode, while a security admin performs the final review and promotes the connection to active status to enable live token issuance.

You can establish this trust using either a generic JWT configuration or a specific provider integration. While specific integrations offer a more streamlined setup experience with pre-defined fields, the underlying security mechanism remains identical. Both methods use a standard JSON web token (JWT) as the workload identity document and require the same core security elements, such as a JWKS URL and required claims, for successful validation.

Before you begin

• You must have a DevOps admin role to create draft workload connection.

• You must have a security admin role to activate or deactivate a workload connection.

• You can use one of the following JWT integration methods:

  • Generic JWT: You must provide the JWKS URL and specify all required claims (such as iss, aud, and sub) to verify the JWT and identify the workload.

  • Specific provider: Okta's user interface offers pre-configured fields and native support for provider-specific JWT structures. By entering common identifiers, like an organization ID for CircleCI, Okta auto-populates the required claims and, sometimes, the JWKS URL.

Create a workload connection with generic JWT

1. On the Okta Privileged Access dashboard, go to DevOps AdministrationWorkload connections.

2. Click Create Workload Connection.

3. Click Generic JWT.

4. Complete the following details:

Setting	Action
Connection name	Enter a unique, URL-friendly name.
Connection description	Enter a description.
Select token time to live (TTL)	Enter an Amount and Unit. These define how long the Okta Privileged Access access token is valid once issued.
JWKS URL	Enter a JWKS URL. This URL is where Okta Privileged Access retrieves the public key to verify the provider's signature on the JWT.
Required Claims	Define the criteria that must be met in the workload's JWT. Okta recommends inspecting your JWT using a debug script or jwt.io. Enter the Source Field Name. Select the operator type: Equals Starts with Exists If you select Exists, then Value input is not required. Enter a Value. Optional. Click Add a condition, and repeat the previous steps.

5. Click Create Workload Connection.

Create a workload connection for CircleCI

1. On the Okta Privileged Access dashboard, go to DevOps AdministrationWorkload connections.

2. Click CircleCI.

3. Enter your Organization ID.

4. Optional. Select Scope to Project ID, and then enter the ID.

5. Click Next.

6. Complete the following details:

   Setting	Action
   Connection name	Enter a unique, URL-friendly name.
   Connection description	Enter a description.
   Select token time to live (TTL)	Enter an Amount and Unit. These define how long the Okta Privileged Access access token is valid once issued.
   JWKS URL	Enter a JWKS URL. This URL is where Okta Privileged Access retrieves the public key to verify the provider's signature on the JWT.
   Required Claims	Define the criteria that must be met in the workload's JWT. Okta recommends inspecting your JWT using a debug script or jwt.io. Enter the Source Field Name. Select the operator type: Equals Starts with Exists If you select Exists, then Value input is not required. Enter a Value. Optional. Click Add a condition, and repeat the previous steps.

7. Click Create Workload Connection.

Create a workload connection for GitLab

1. On the Okta Privileged Access dashboard, go to DevOps AdministrationWorkload connections.

2. Click GitLab.

3. Enter your Domain name.

4. Optional. Select Scope to Group name, and then enter the group name.

5. Optional. Select Scope to Project Name, and then enter the project name.

6. Optional. Select Scope to Project ID, and then enter the project ID.

7. Click Next.

8. Complete the following details:

   Setting	Action
   Connection name	Enter a unique, URL-friendly name.
   Connection description	Enter a description.
   Select token time to live (TTL)	Enter an Amount and Unit. These define how long the Okta Privileged Access access token is valid once issued.
   JWKS URL	Enter a JWKS URL. This URL is where Okta Privileged Access retrieves the public key to verify the provider's signature on the JWT.
   Required Claims	Define the criteria that must be met in the workload's JWT. Okta recommends inspecting your JWT using a debug script or jwt.io. Enter the Source Field Name. Select the operator type: Equals Starts with Exists If you select Exists, then Value input is not required. Enter a Value. Optional. Click Add a condition, and repeat the previous steps.

9. Click Create Workload Connection.

Create a workload connection for Google Cloud Provider

1. On the Okta Privileged Access dashboard, go to DevOps AdministrationWorkload connections.

2. Click Google Cloud Provider.

3. Enter App Client ID name.

4. Optional. Select Scope to Email, and then enter the group name.

5. Optional. Select Scope to Account ID, and then enter the project ID.

6. Click Next.

7. Complete the following details:

   Setting	Action
   Connection name	Enter a unique, URL-friendly name.
   Connection description	Enter a description.
   Select token time to live (TTL)	Enter an Amount and Unit. These define how long the Okta Privileged Access access token is valid once issued.
   JWKS URL	Enter a JWKS URL. This URL is where Okta Privileged Access retrieves the public key to verify the provider's signature on the JWT.
   Required Claims	Define the criteria that must be met in the workload's JWT. Okta recommends inspecting your JWT using a debug script or jwt.io. Enter the Source Field Name. Select the operator type: Equals Starts with Exists If you select Exists, then Value input is not required. Enter a Value. Optional. Click Add a condition, and repeat the previous steps.

8. Click Create Workload Connection.

Manage a workload connection

Once the DevOps admin confirms that testing is complete, the security admin promotes the connection.

1. On the Okta Privileged Access dashboard, go to DevOps AdministrationWorkload connections.

2. Select a workload connection that you want to manage.

3. Click Actions, and then select Edit, Activate, or Deactivate.

4. Click Activate workload connection.

Related topics

Workloads