> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/use-harness-platform/pipelines/workload-identity/workload-identity-overview.md).

# Workload identity overview

Use Harness as a workload identity provider to issue short-lived OIDC tokens that carry pipeline execution context, so workloads authenticate to external systems without connector-managed credentials.

{% hint style="info" %}
Workload identity for the Shell Script step is behind the feature flag `PIPE_PIPELINE_IDENTITY`. Contact [Harness Support](mailto:support@harness.io) to enable it.
{% endhint %}

Harness acts as a workload identity provider for pipeline workloads, issuing short-lived, signed OIDC ID tokens that carry execution context such as account, organization, project, pipeline, stage, step, environment, service, and connector. External systems validate these tokens through public OpenID Connect (OIDC) discovery and JSON Web Key Set (JWKS) endpoints, then grant access based on the claims the token carries. This lets a workload authenticate rather than through credentials held in a connector, which separates workload identity from the [OIDC support that Harness connectors already provide](https://developer.harness.io/harness-platform/use-harness-platform/connectors/artifact-repositories/add-an-artifactory-connector/artifactory-connector-settings-reference#artifactory-connector-settings).

***

## What you will learn in this topic

By the end of this topic, you will understand:

* [What a workload is](#what-is-a-workload) in the context of a Harness pipeline.
* [How workload identity differs from connector OIDC](#how-workload-identity-differs-from-connector-oidc), and when to use each.
* [Where you can use workload identity](#use-workload-identity), including the steps that support it.
* [How workload identity works](#how-workload-identity-works) and how external systems consume it.

***

## Before you begin

Before you use workload identity, ensure you have the following:

* **A Harness pipeline**: A pipeline containing the step that requires a token. Go to [Add a stage](https://developer.harness.io/harness-platform/use-harness-platform/pipelines/add-a-stage.md) for more information on building a stage.
* **A relying party configured for OIDC**: An external system, such as AWS, GCP, Azure, or HashiCorp Vault, configured to trust Harness as an OIDC identity provider.
* **Knowledge of the target trust policy**: The audience value and subject claim format your relying party expects.

***

## What is a workload?

A **workload** is a unit of pipeline execution that runs your code or commands and needs to authenticate to an external system. When a Shell Script step runs a script that calls AWS, GCP, Azure, or HashiCorp Vault, that step is the workload.

Workload identity gives that unit its own identity, separate from any user and separate from any connector:

* **Not a user**: A workload is a machine identity. It is not a Harness user account, and it does not use a user session, password, or single sign-on. Workload identity is unrelated to how people log in to Harness.
* **Not a connector**: A connector holds credentials that Harness stores and reuses across executions. A workload identity token is generated for one execution and describes that execution.
* **Scoped to a step in this release**: You declare identities on the step that needs a token, so the workload is the individual step rather than the whole stage or pipeline.

Since the identity describes a specific execution, you can write a trust policy in your cloud provider that grants access to one pipeline, one environment, or one step rather than to all Harness workloads in your account.

***

## How workload identity differs from connector OIDC

Harness already supports OIDC on connectors, where an [AWS](https://developer.harness.io/harness-platform/use-harness-platform/connectors/cloud-providers/add-aws-connector), [GCP](https://developer.harness.io/docs/continuous-integration/secure-ci/configure-oidc-gcp-wif-ci-hosted/#set-up-the-gcp-connector), or [Azure](https://developer.harness.io/harness-platform/use-harness-platform/connectors/cloud-providers/add-a-microsoft-azure-connector) connector federates into a cloud role instead of storing static keys. Workload identity adds a second, complementary path for cases where the code running inside a step needs its own identity.

In connector OIDC, the connector is the identity, and every execution that uses the connector presents the same identity to the cloud provider.

In workload identity, the running step is the identity, and the token describes that execution.

| Aspect                 | Connector OIDC                                               | Workload identity                                                                       |
| ---------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| Identity presented     | The connector                                                | The step that runs the script                                                           |
| Who consumes the token | Harness, on behalf of the connector, inside native steps     | Your script, through an environment variable                                            |
| Subject claim          | Fixed by Harness, derived from the connector and account     | Controlled by the subject template you declare                                          |
| Custom claims          | Not supported                                                | Supported through `customClaims`                                                        |
| Audience               | Set by the cloud provider integration                        | Declared per identity on the step                                                       |
| Tokens per step        | One connector token per connector reference                  | One token per declared identity, requested in parallel                                  |
| Issuer                 | Account-scoped connector issuer                              | Dedicated workload identity issuer                                                      |
| Typical use            | Native CD and CI steps that authenticate through a connector | Scripts that authenticate directly to AWS, GCP, Azure, Vault, or any OIDC relying party |

Use connector OIDC when a native step performs the cloud operation for you. Use workload identity when your script performs the operation itself, when you need a subject or claim shape that a connector cannot produce, or when a single step must authenticate to more than one audience. The two can coexist in the same pipeline, and the token expressions that read a connector token remain available. Go to [Accessing AWS and GCP OIDC tokens from connectors in shell scripts](https://developer.harness.io/docs/continuous-delivery/x-platform-cd-features/cd-steps/utilities/shell-script-step#accessing-aws-and-gcp-oidc-tokens-from-connectors-in-shell-scripts) for more information on connector token expressions.

***

## Use workload identity

Currently, workload identity is available on the Shell Script step and the CI Run step. The following table lists what supports it today.

| Area                                                              | Support                                                                                                             |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Shell Script step                                                 | Supported. Declare identities in the `identities` map on the step.                                                  |
| CI Run step                                                       | Supported. Declare identities in the `identities` map on the step.                                                  |
| Every other step type, including Container steps and custom steps | Not supported. The `identities` field is not available.                                                             |
| Shell type                                                        | Bash only. PowerShell steps that run over WinRM are not supported.                                                  |
| Execution target                                                  | Scripts that run on the delegate, and scripts that connect to a target host over SSH.                               |
| Stage types                                                       | Any stage type that can contain a Shell Script step, including CD, Custom, and Approval stages.                     |
| Scope                                                             | Step scope only. The `scope` field accepts `STAGE` and `PIPELINE`, but those values behave as step-scoped.          |
| Runtime inputs                                                    | The `identities` map structure is static. Individual field values, such as `audience`, support Harness expressions. |

{% hint style="info" %}
Use workload identity when a script authenticates to an external service that trusts Harness as an OIDC identity provider, such as AWS Security Token Service (STS), GCP Workload Identity Federation, Microsoft Entra ID, or HashiCorp Vault. Both the discovery endpoint and the JWKS endpoint must be reachable from that service, so a Harness Self-Managed Enterprise Edition installation without public ingress cannot federate with an external cloud provider.
{% endhint %}

***

## How workload identity works

Harness generates the claims in a token from the server-side execution context of the running workload, not from values the workload supplies. A relying party can therefore trust that the claims describe the workload that actually requested the token.

The flow has three parts:

* **Claim generation**: Harness generates claims from the execution context of the running workload.
* **Token issuance**: Harness signs the token and injects it into the workload at runtime.
* **Token validation**: The external system validates the token through the Harness OIDC discovery and JWKS endpoints, then authorizes the request based on the claims.

![Harness issues a signed OIDC token to a pipeline step, which the relying party validates through the Harness discovery and JWKS endpoints.](https://173309742-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3F2TpHXhur2QtQnORSM9%2Fuploads%2Fgit-blob-fd39429c018c636253ac3f69c0cc810f3a17bfc6%2Fworkload-identity-flow.png?alt=media)

JWKS exposes public keys and certificate chains with the `kid`, `x5c`, and `x5t` parameters, so your relying party can select the correct key and verify the certificate chain.

***

## Related articles

* [Subject templates](https://developer.harness.io/harness-platform/use-harness-platform/pipelines/workload-identity/subject-templates.md): Customize the subject claim in OIDC tokens.
* [Token claims reference](https://developer.harness.io/harness-platform/use-harness-platform/pipelines/workload-identity/token-claims-reference.md): Execution context claims that identify which workload requested the token.
* [Configure OIDC discovery URL in your provider](https://developer.harness.io/harness-platform/use-harness-platform/pipelines/workload-identity/configure-oidc-url.md): Register Harness as an OIDC identity provider in that system.
