Configure workload connection

The workload connection is the trust anchor that establishes the relationship between Okta Privileged Access and your workload's identity source. You can choose between three authentication methods: JWT-based authentication (using external identity providers like GitHub, GitLab, or CircleCI), AWS IAM-based authentication (using the IAM identity of a workload that has AWS credentials), or API key-based authentication (using managed secrets controlled by security admins).

For JWT and AWS IAM connections, a split-duty security model applies: 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. For API key connections, only security admins create and manage the connection.

JWT connections can use 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

• For JWT and AWS IAM workload connections: You must have a DevOps admin role to create a draft workload connection. A security admin role is required to activate or deactivate the connection.

• For AWS IAM workload connections: You must know the 12-digit AWS account ID of the account where the workload runs. To restrict the connection to a specific identity, you must also know the resource type, resource name, and other attributes of the AWS identity that the workload uses.

• For API key workload connections: You must have a security admin role to create, manage, and activate the connection.

• For JWT connections, you can use one of the following JWT integration methods:

  • Generic JWT: You must provide a JWKS validation source and specify all required claims (such as iss, aud, and sub) to verify the JWT and identify the workload. The validation source can be a JWKS URL or static JWKS content that you paste or upload directly.

  • 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 Generic JWT workload connection

1. On the Okta Privileged Access dashboard, go to DevOps Administration > Workload 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.
   JWT Setup Info	Select how Okta Privileged Access retrieves the public key to verify the provider's JWT signature. Select one of the following tabs: JWKS URL: Enter the URL where Okta Privileged Access fetches the public keys at runtime. Paste/Upload: Paste the JWKS JSON directly into the field or select a file to upload. The file contents are read in your browser and aren't uploaded to the server. The input must be a full JWKS JSON object containing a keys array with at least one key. Note: The validation source can't be changed after the connection is created. You can update the JWKS content for a Paste/Upload connection at any time by selecting Edit.
   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 isn't required. Enter a Value. Optional. Click Add a condition, and repeat the previous steps.

5. Click Create Workload Connection.

Create a provider-specific workload connection

1. On the Okta Privileged Access dashboard, go to DevOps Administration > Workload connections.

2. Click Create Workload Connection.

3. Select your connection type and complete the provider-specific fields, and then click Next:

   Connection type	Fields
   Azure Managed Identity	Enter your Azure Tenant ID.
   CircleCI	Enter your Organization ID. Optional. Select Scope to Project ID, and then enter the ID.
   GitHub Actions	Enter your GitHub Owner.
   GitLab	Enter your Domain name. Optional. Select Scope to Group name, and then enter the group name. Optional. Select Scope to Project Name, and then enter the project name. Optional. Select Scope to Project ID, and then enter the project ID.
   Google Cloud Provider	Enter your App Client ID. Optional. Select Scope to Email, and then enter the email. Optional. Select Scope to Account ID, and then enter the account ID.
   Kubernetes	Enter your Cluster Issuer URL.
   Azure DevOps	Enter your Azure DevOps Organization ID.
   Buildkite	Enter your Buildkite Organization Slug.
   Harness	Enter your Harness cluster and Harness Account ID.
   Jenkins	Enter your Jenkins Base URL.
   Pulumi ESC	Enter your Pulumi Org Name.
   Bitbucket Pipelines	Enter your Workspace ID, the URL-friendly identifier for your Bitbucket workspace. Enter your Workspace UUID. Copy this value from the example payload on your repository's OpenID Connect settings page.
   Octopus Deploy	Enter your Octopus Server URL, the base URL of your Octopus Deploy server.
   Terraform Cloud	Enter your Organization Name, the Terraform Cloud organization name.

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.
   JWT Setup Info	Under the JWKS URL tab, enter the URL where Okta Privileged Access fetches the public keys at runtime.
   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 isn't required. Enter a Value. Optional. Click Add a condition, and repeat the previous steps.

5. Click Create Workload Connection.

Create an AWS IAM workload connection

AWS IAM workload connections let a workload authenticate with its AWS IAM identity instead of a JWT or an API key. The workload doesn't need to run in AWS, but it must have valid AWS credentials. The workload signs an AWS STS GetCallerIdentity request with its AWS credentials, and Okta Privileged Access verifies the signed request with AWS STS. The connection defines which AWS account, and optionally which AWS identity, the workload must belong to.

1. On the Okta Privileged Access dashboard, go to DevOps Administration > Workload connections.

2. Select Create Workload Connection.

3. Select AWS.

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.
   AWS account	Enter the 12-digit AWS account ID that the workload authenticates from. This setting is required.
   Parse from ARN	Optional. Fill in the identity settings in this table from an Amazon Resource Name (ARN): Select Parse from ARN. In the ARN field, paste the ARN of the identity that the workload uses. Select Parse. Okta Privileged Access fills in Resource type, Resource name, and Session info when the ARN contains them. Enter Region and Resource ID manually, because they aren't part of the ARN. The ARN is used only to fill in the fields. It isn't saved with the connection. You can parse the following ARN formats: arn:aws:sts::<account-id>:assumed-role/<role-name>/<session-name> arn:aws:iam::<account-id>:user/<user-name> arn:aws:sts::<account-id>:federated-user/<user-name> If you enter an unsupported ARN, such as the ARN of the AWS account root user, an error message appears and the fields keep their current values.
   Resource type	Optional. Select the type of AWS identity that the workload must use: Assumed role, IAM user, or Federated user. Select Not specified to accept any identity type. Settings that don't apply to the type you select are hidden and cleared.
   Resource name	Optional. Enter the name of the IAM role, IAM user, or federated user that the workload must use.
   Session info	Optional. For an assumed role only, enter the session name that the workload must use.
   Resource ID	Optional. For an assumed role or an IAM user, enter the unique AWS ID of the identity. For example, an assumed role ID starts with AROA and an IAM user ID starts with AIDA.
   Region	Optional. Enter the AWS Region that the workload sends its signed request to, for example us-west-2.

5. Select Create Workload Connection.

Create an API Key workload connection

API key workload connections allow workloads to authenticate using a managed API key instead of a JWT. This method is ideal for non-cloud workloads or scenarios where a federated identity provider isn't available. Only security admins can create API key connections.

1. On the Okta Privileged Access dashboard, go to DevOps Administration > Workload connections.

2. Click Create Workload Connection.

3. Click API Key.

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 after it's issued.

5. 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 Administration > Workload 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.