Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
PlatformPipelinesWorkload Identity

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 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:

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:

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.

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.

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:

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


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.

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:

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 for the full field reference and more YAML examples. Go to Subject templates for more information on controlling the format of the token subject claim.


Next steps

Last updated

Was this helpful?