> 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/configure-oidc-url.md).

# Configure OIDC discovery URL in your provider

Configure the OIDC discovery URL in your provider

Before you configure the discovery URL, go to [Workload identity overview](https://developer.harness.io/harness-platform/use-harness-platform/pipelines/workload-identity/workload-identity-overview.md) to understand how workload identity tokens are issued and how they differ from connector OIDC tokens.

Before a relying party accepts a Harness token, you register Harness as an OIDC identity provider in that system. The provider then reads the Harness OIDC discovery document to learn the issuer, the supported signing algorithm, and the JWKS endpoint that holds the public keys.

### Workload identity issuer and URLs

Workload identity uses a dedicated issuer, which is separate from the per-account connector OIDC issuer that Harness connectors use. Each Harness environment (deployment type or Harness offering) has one issuer. Every region in the environment shares it, so you register one URL, and tokens are valid whichever region ran the pipeline.

| Deployment type                               | Issuer                                                              | Discovery document                                                     | JWKS                                                   |
| --------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------ |
| Harness SaaS (production)                     | `https://id.harness.io/workload`                                    | `https://id.harness.io/workload/.well-known/openid-configuration`      | `https://id.harness.io/workload/.well-known/jwks`      |
| Harness FedRAMP                               | `https://fedramp.harness.io/workload`                               | `https://fedramp.harness.io/workload/.well-known/openid-configuration` | `https://fedramp.harness.io/workload/.well-known/jwks` |
| Harness Self-Managed Enterprise Edition (SMP) | Your own domain, for example `https://harness.example.com/workload` | `<issuer>/.well-known/openid-configuration`                            | `<issuer>/.well-known/jwks`                            |

### Which discovery and JWKS URL to register

Harness publishes two separate OIDC discovery documents and key sets. They are not interchangeable, and a relying party validates tokens only from the issuer it is configured with. Register the URL that matches the token your workload presents:

* **Workload identity**: An identity declared on a step.
* **Connector OIDC**: An AWS, GCP, or Azure connector that uses OIDC.

| URL                | Workload identity                                                 | Connector OIDC                                                                                      |
| ------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Issuer             | `https://id.harness.io/workload`                                  | `https://<HOSTNAME>/ng/api/oidc/account/<YOUR_HARNESS_ACCOUNT_ID>`                                  |
| Discovery document | `https://id.harness.io/workload/.well-known/openid-configuration` | `https://<HOSTNAME>/ng/api/oidc/account/<YOUR_HARNESS_ACCOUNT_ID>/.well-known/openid-configuration` |
| JWKS               | `https://id.harness.io/workload/.well-known/jwks`                 | `https://<HOSTNAME>/ng/api/oidc/account/<YOUR_HARNESS_ACCOUNT_ID>/.well-known/jwks`                 |

The workload identity URLs above are for Harness SaaS (production). For other environments, use the issuer from the previous table.

### Why there are two issuers

Connector OIDC predates the workload identity framework. When Harness first implemented OIDC for connectors, each account got its own issuer with the account ID embedded in the URL. A relying party could use the issuer URL itself to identify which Harness account was authenticating.

The workload identity framework uses a single shared issuer across all accounts. The account is identified by the `account_id` claim in the token, not the issuer URL. This makes registration simpler — one URL works for all accounts — and enables centralized key management across regions.

Both issuers are currently active. Harness is migrating connectors to the unified workload identity issuer incrementally. AWS KMS, AWS Secrets Manager, and Vault connectors have moved to the Harness ID framework. For migrated connectors, the issuer depends on whether the feature flag is enabled for your account. The connectors and secret manager requires `PL_UNIFIED_OIDC_FRAMEWORK` and `PIPE_PIPELINE_IDENTITY` feature flags to be enabled.

* **Feature flag enabled**: `https://id.harness.io/workload`
* **Feature flag disabled**: `https://<HOSTNAME>/ng/api/oidc/account/<YOUR_HARNESS_ACCOUNT_ID>`

All other connectors still use the per-account issuer (`https://<HOSTNAME>/ng/api/oidc/account/<YOUR_HARNESS_ACCOUNT_ID>`) until they are onboarded to the Harness ID framework.

Two consequences follow from this split in the meantime:

* **A trust relationship built for connector OIDC does not accept workload identity tokens**: If you already federate a cloud role against the connector OIDC issuer, which embeds your account ID, you must also register the workload identity issuer as an additional identity provider before a script can authenticate with a step identity.
* **Both issuers can be registered at the same time**: A cloud provider accepts more than one OIDC identity provider, so connector-based steps and script-based steps can authenticate into the same cloud account side by side.

Both endpoints under an issuer must be reachable from the relying party. Most providers only need the issuer URL and resolve the discovery and JWKS paths themselves.

### Find the hostname for connector OIDC

Connector OIDC URLs use a hostname that depends on the Harness cluster your account resides in, not on your login URL. Workload identity does not need this lookup. To find your cluster, navigate to **Account Settings** > **Account Details**. Use the following hostname even when a vanity URL is configured for your account.

| Cluster        | Hostname                                 |
| -------------- | ---------------------------------------- |
| Prod1 or Prod2 | `app.harness.io`                         |
| Prod3          | `app3.harness.io`                        |
| Prod0 or Prod4 | `prod0.harness.io` or `prod4.harness.io` |
| EU clusters    | `accounts.eu.harness.io`                 |

For Harness Self-Managed Enterprise Edition, use your Harness installation's hostname.

### Verify the endpoint

Confirm the discovery document resolves before you configure your provider:

```bash
curl https://id.harness.io/workload/.well-known/openid-configuration
```

The response describes how a relying party validates your tokens:

| Field                                   | Description                                                                                                                                                                                                                                            |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `issuer`                                | The shared issuer URL that appears in the `iss` claim of every workload identity token. This is the same URL for all Harness accounts — register it once. The account is identified by the `account_id` claim inside the token, not by the issuer URL. |
| `jwks_uri`                              | The endpoint that publishes the public keys used to verify token signatures.                                                                                                                                                                           |
| `id_token_signing_alg_values_supported` | The signing algorithm Harness uses, which is `RS256`.                                                                                                                                                                                                  |
| `subject_types_supported`               | The subject types the endpoint supports, which is `public`.                                                                                                                                                                                            |
| `response_types_supported`              | The response types the endpoint supports, which is `id_token`.                                                                                                                                                                                         |
| `scopes_supported`                      | The scopes the endpoint supports, which is `openid`.                                                                                                                                                                                                   |
| `claims_supported`                      | The claims the endpoint advertises.                                                                                                                                                                                                                    |

To inspect the signing keys, request the `jwks_uri` value:

```bash
curl https://id.harness.io/workload/.well-known/jwks
```

The JWKS contains the public keys for every Harness region, so it can hold more than one key. This is expected. Your provider picks the key whose `kid` matches the token, so don't hard-code a single key or certificate.

{% hint style="info" %}
Both the discovery endpoint and the JWKS endpoint must be reachable from the system that validates the token. A cloud provider fetches these over the public internet, so a Self-Managed Enterprise Edition installation without public ingress cannot complete OIDC federation with an external cloud provider.
{% endhint %}

### Where each provider expects the URL

Each provider names this setting differently, and providers differ on whether they want the issuer URL or the full discovery URL.

| Provider                         | Setting                                               | Value to supply                                                                             |
| -------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| AWS IAM                          | Provider URL on an OpenID Connect identity provider   | The issuer URL. AWS appends the discovery path itself.                                      |
| GCP Workload Identity Federation | Issuer URI on an OIDC workload identity pool provider | The issuer URL.                                                                             |
| Microsoft Entra ID               | Issuer on a federated identity credential             | The issuer URL, together with the `sub` value your template produces.                       |
| HashiCorp Vault                  | `oidc_discovery_url` on the JWT auth method           | The issuer URL. Vault appends `/.well-known/openid-configuration` when it fetches metadata. |

The following example configures the Vault JWT auth method to trust Harness:

```bash
vault write auth/jwt/config \
  oidc_discovery_url="https://id.harness.io/workload" \
  default_role="harness-workload"
```

You then bind a Vault role to the claims a token carries, so only the intended workload authenticates:

```bash
vault write auth/jwt/role/harness-workload \
  role_type="jwt" \
  bound_audiences="https://vault.example.com" \
  user_claim="sub" \
  bound_claims_type="glob" \
  bound_claims='{"account_id":"my_account","project_id":"my_project","pipeline_id":"deploy_prod"}' \
  policies="deploy" \
  ttl="15m"
```

***

## How Harness secures tokens

Harness protects the tokens it issues in the following ways:

* **Short-lived**: Tokens expire one hour after issuance, so a leaked token has a narrow window of use.
* **Signed by Harness**: Signing keys are backed by a Key Management Service (KMS) and Hardware Security Module (HSM), and the private key never leaves KMS.
* **Publicly verifiable**: A relying party verifies the signature through the Harness OIDC discovery and JWKS endpoints, so it never needs a shared secret with Harness.
* **Server-generated claims**: Claims come from the Harness execution context rather than from workload input, so a workload cannot assert an identity it does not have.
* **Audience-bound**: Each token is issued for the audience you declare, so a relying party rejects a token that was minted for a different system.
* **Separate signing keys for internal and external tokens**: Harness signs the internal token that carries your workload's execution context with one key, and signs the OIDC ID token your relying party verifies with a separate key that is published through JWKS. A leaked internal token cannot be replayed as a valid OIDC token, because no relying party trusts the key that signed it.

***

## Token modes

Token mode determines how Harness formats the token it presents to the relying party. Set the mode to match what your identity provider expects.

### STANDARD

`STANDARD` is the default mode. Harness issues an OIDC ID token where the `iss` claim is the Harness workload issuer and the `sub` claim is the workload subject derived from your template. The token is signed with an RSA key and is verifiable by any OIDC-compliant identity provider through the Harness discovery and JWKS endpoints.

Use `STANDARD` for AWS IAM, GCP Workload Identity Federation, Microsoft Entra ID, and HashiCorp Vault JWT auth.

### CLIENT\_ASSERTION

`CLIENT_ASSERTION` is for enterprise identity providers that require the client to authenticate using a signed JWT credential rather than presenting a bearer token. Harness formats the token as a JWT client assertion per RFC 7523, where both the `iss` and `sub` claims are set to the workload subject (`iss=sub`). The Harness workload issuer URL does not appear as the `iss` claim in this mode.

Use `CLIENT_ASSERTION` for Active Directory Federation Services (ADFS), PingFederate, and any provider that requires `private_key_jwt` client authentication.

### Set the token mode

Token mode is a per-identity setting. It is not an account setting, a connector setting, or a pipeline setting. Set it with the `tokenMode` field on an individual identity inside the `identities` map on the Shell Script step, so two identities on the same step can use different modes.

```yaml
- step:
    type: ShellScript
    name: Authenticate with ADFS
    identifier: adfs_auth
    identities:
      ADFS_ID_TOKEN:
        audience: https://adfs.example.com
        tokenMode: CLIENT_ASSERTION
```

When you omit `tokenMode`, Harness uses `STANDARD`.

***

## Add an identity to a step

An identity is a named entry that you add to the `identities` map on the step that needs a token. The name you choose is both the label for the identity and the name of the environment variable that carries its token. Declaring an identity therefore means two things at once: it tells Harness to mint one OIDC ID token for that name, and it tells Harness which environment variable to inject the token into when the step runs.

Three points describe the model:

* **One identity produces one token**: Each identity carries its own audience, subject template, custom claims, and token mode, so each token is independent. A step that must authenticate to two services declares two identities, and Harness requests both tokens in parallel.
* **The identity name becomes the environment variable**: An identity named `AWS_ID_TOKEN` makes its token available to the script as `$AWS_ID_TOKEN`. Nothing is written to disk, and the token is not exposed as a Harness expression or output variable.
* **The declaration is static**: Identity names and the shape of the `identities` map are fixed in the step YAML and cannot be overridden through input sets, runtime inputs, or a parent pipeline. Field values inside an identity, such as `audience`, do support Harness expressions.

The following step declares a single identity named `AWS_ID_TOKEN` and reads it in the script:

```yaml
- step:
    type: ShellScript
    name: Authenticate with workload identity
    identifier: harness_id_step
    identities:
      AWS_ID_TOKEN:
        audience: sts.amazonaws.com
    spec:
      shell: Bash
      onDelegate: true
      source:
        type: Inline
        spec:
          script: |-
            echo "Token acquired for AWS: ${AWS_ID_TOKEN}"
      timeout: 10m
```

If Harness cannot generate a token for an identity, for example because the audience resolves to a blank value, Harness skips that identity and does not inject its environment variable. The step still runs, so write your script to handle an empty value.

Go to [OIDC ID tokens for the Shell Script step](https://developer.harness.io/continuous-delivery/use-continuous-delivery/cd-building-blocks/cd-steps/utilities/shell-script-step) for the full field reference and more YAML examples. Go to [Subject templates](https://developer.harness.io/harness-platform/use-harness-platform/pipelines/workload-identity/subject-templates.md) for more information on controlling the format of the token subject claim.

***

## Next steps

* [Workload identity overview](https://developer.harness.io/harness-platform/use-harness-platform/pipelines/workload-identity/workload-identity-overview.md): Understand how Harness issues and secures tokens.
* [Subject templates](https://developer.harness.io/harness-platform/use-harness-platform/pipelines/workload-identity/subject-templates.md): Customize the subject claim in your tokens.
