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.
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.
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/workloadFeature 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.
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:
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.
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.
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_TOKENmakes 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
identitiesmap 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 asaudience, 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
Workload identity overview: Understand how Harness issues and secures tokens.
Subject templates: Customize the subject claim in your tokens.
Last updated
Was this helpful?