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 two authentication methods: JWT-based authentication (using external identity providers like GitHub, GitLab, or CircleCI) or API key-based authentication (using managed secrets controlled by security administrators).

For JWT 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 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 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

On the Okta Privileged Access dashboard, go to DevOps Administration > Workload connections.
Click Create Workload Connection.
Click Generic JWT.

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 are not 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 cannot 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 is not required. Enter a Value. Optional. Click Add a condition, and repeat the previous steps.

Click Create Workload Connection.

Create a provider-specific workload connection

On the Okta Privileged Access dashboard, go to DevOps Administration > Workload connections.
Click Create Workload Connection.

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.

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 is not required. Enter a Value. Optional. Click Add a condition, and repeat the previous steps.

Click 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 is not available. Only security admins can create API key connections.

On the Okta Privileged Access dashboard, go to DevOps Administration > Workload connections.
Click Create Workload Connection.
Click API Key.

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.

Click Create Workload Connection.

Note:

Unlike JWT workload connections, API key connections don't have a draft phase. The connection is created directly in active status and is ready for key generation immediately. Only security admins can create, modify, and delete API key connections.

Manage a workload connection

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

On the Okta Privileged Access dashboard, go to DevOps Administration > Workload connections.
Select a workload connection that you want to manage.
Click Actions, and then select Edit, Activate, or Deactivate.
Click Activate workload connection.

Note:

When a workload connection is promoted to Active, the DevOps admin loses admin rights to the connection, and the connection can immediately begin issuing valid Okta Privileged Access access tokens. The security admin retains the ability to switch the connection between Active and Inactive status.