Subject templates
Customize the subject claim in Harness-issued OIDC tokens using subject templates, and understand the structural, free-form, and validation rules that apply.
Subject templates let you customize the sub (subject) claim in OIDC tokens that Harness issues. The subject claim is critical for cloud provider trust policies, including AWS Identity and Access Management (IAM) roles, Azure Managed Identities, and GCP Workload Identity, because it determines which workload can assume which cloud permissions. This topic explains the template syntax, the segment types available, and the validation Harness applies.
What you will learn in this topic
By the end of this topic, you will understand:
Why a template specifies structure rather than values, and what that prevents.
How to write a template with the supported segment and delimiter syntax.
Which structural segments are available and the claim each one requires.
How to add custom context with free-form segments and custom claims.
Which claims are reserved and rejected in a template.
When Harness validates a template, at registration and at token generation.
Which template granularity to choose for the scope you want to grant.
Before you begin
Before you configure a subject template, ensure you have the following:
Workload identity context: Familiarity with how Harness issues tokens to pipeline workloads. Go to Workload identity overview to review the model.
A relying party trust policy: The exact subject format your cloud provider or identity provider expects.
The claims your workload carries: Knowledge of which execution context claims are present for your workload type.
Security model
Harness enforces structure-based security for subject templates. You specify the template structure, and Harness supplies the values from the execution context of the running workload, so a template cannot assert an identity that the workload does not have.
Four rules define this model:
No literal values allowed: You cannot specify hardcoded values such as
account/abc123orproject/marketing.Only claim placeholders: You must use the placeholder format, such as
account/{account_id}, where Harness supplies the values.Key-to-claim mapping: Structural segments have fixed key-to-claim mappings. For example, the
accountkey must use the{account_id}claim.Values from the execution context: Harness substitutes every placeholder value from the server-side execution context, which the workload cannot modify.
Default subject format
If you do not configure a subject template on an identity, Harness issues a token using the following default subject format:
The platform substitutes all placeholder values from the execution context at runtime.
Pattern syntax
A subject template is a sequence of segments, where each segment pairs a key with a claim placeholder.
Two delimiters apply:
/: Separates the key from the claim placeholder within a segment.:: Separates one segment from the next.
The following template produces a pipeline-scoped subject:
Pattern components
Structural segments
Fixed key-to-claim mappings for core identity
account/{account_id}
At least account
Free-form segments
Custom segments with user-defined keys
purpose/{purpose}
Optional
Segment delimiter
Separates segments
:
Required between segments
Key-value delimiter
Separates key from claim placeholder
/
Required within each segment
Claim placeholder
References a claim available to the workload
{claim_name}
Required, no literal values
Structural segments
Structural segments have predefined key-to-claim mappings that you cannot change. These mappings ensure consistent subject patterns across Harness.
account
{account_id}
account/{account_id}
Harness account identifier
org
{org_id}
org/{org_id}
Organization identifier
project
{project_id}
project/{project_id}
Project identifier
pipeline
{pipeline_id}
pipeline/{pipeline_id}
Pipeline identifier
stage
{stage_id}
stage/{stage_id}
Stage identifier
step
{step_id}
step/{step_id}
Step identifier
execution
{execution_id}
execution/{execution_id}
Execution identifier
environment
{environment_id}
environment/{environment_id}
CD environment identifier
service
{service_id}
service/{service_id}
CD service identifier
infrastructure
{infrastructure_id}
infrastructure/{infrastructure_id}
Infrastructure identifier
connector
{connector_id}
connector/{connector_id}
Connector identifier
Validation rules for structural segments
Three security rules govern structural segments. Each rule prevents a template from claiming an identity that does not belong to the workload.
The key must match the claim: The
accountkey can only use the{account_id}claim.account/{account_id}is valid, andaccount/{project_id}is invalid because it pairs a key with the wrong claim.No literal values: Structural segments must use claim placeholders.
project/{project_id}is valid, andproject/marketingis invalid.Structural claims cannot be reused: Claims that have structural mappings cannot appear in free-form segments.
account/{account_id}:project/{project_id}:purpose/{purpose}is valid becausepurposeis custom, andaccount/{account_id}:cost/{project_id}is invalid becauseproject_idmust use theprojectkey.
Free-form segments
Free-form segments let you add custom identity context using custom claims. They appear as a suffix after the structural segments.
Position
Must appear after all structural segments
account/{account_id}:project/{project_id}:purpose/{purpose}
Key naming
Can use any key name, and is not restricted to structural keys
purpose, cost, env, region
Value format
Must use a claim placeholder, with no literal values
purpose/{purpose} is valid, env/prod is invalid
Claim source
Claims must exist for the workload, typically from custom_claims
Custom claims are flattened to top level
Use custom claims in templates
Custom claims provided in the custom_claims field are flattened into top-level claims, which is what makes them referenceable as placeholders.
The following request declares two custom claims and references them in the template:
Harness flattens those claims to the top level:
Harness then substitutes the values to produce the subject:
Claims you cannot use
The following claims are reserved. A template that references one is rejected at registration, because these claims describe the token request itself rather than the identity of the workload.
workload_id
Internal identifier for the token request
workload_type
Type of workload, such as PIPELINE, STAGE, or STEP
sub_template
The subject template itself, which is metadata about token generation
workload_uri
Uniform Resource Identifier (URI) representation of the workload
custom_claims
Container for custom claims, which are flattened into top-level claims
adfs_token_endpoint
ADFS-specific endpoint
Validation workflow
Harness validates subject templates in two phases, so structural mistakes surface at registration and unresolvable claims surface at token generation.
Phase 1: Registration time
When a workload registers with a subject template, Harness validates the structure:
The template format follows the
key/{claim}:key/{claim}pattern.There are no leading or trailing segment delimiters.
Structural segments use the correct key-to-claim mappings.
Structural segments contain no literal values.
The template contains no reserved claims.
Structural claims are not used in free-form segments.
If validation fails, Harness rejects the registration with a specific error message.
Phase 2: Token generation time
When Harness generates an OIDC token, it validates that the template resolves:
All placeholders resolve to claims that exist for the workload.
No placeholder resolves to a null or empty value.
Substitution produces a valid subject string.
If validation fails, token generation fails with a specific error message.
Examples
Use the following examples to select a template granularity that matches the scope of the permissions you want to grant.
Valid templates
Each template below adds granularity to the one before it. The more segments you include, the narrower the set of workloads that can assume the matching cloud permissions.
Minimal, for simple pipelines:
Pipeline-level, for AWS role assumption scoped to one pipeline:
Step-level, the most specific scope available:
Environment-specific, for CD deployments:
Purpose-based, where purpose is a custom claim such as deploy, read, or write:
Multi-dimensional, combining several custom claims:
Invalid templates
account/abc123:project/{project_id}
Structural segments must use claim placeholders
Literal value in a structural segment
account/{project_id}:project/{project_id}
Key 'account' must use claim {account_id}, not {project_id}
Wrong claim for the key
account/{account_id}:cost/{org_id}
Claim 'org_id' can only be used with key 'org', not 'cost'
Structural claim in a free-form segment
account/{account_id}:id/{workload_id}
Claim 'workload_id' is a Harness internal claim
Reserved claim in the template
:account/{account_id}:project/{project_id}
Template must not start or end with segment delimiter
Leading delimiter
account/{account_id}:project/{project_id}:
Template must not start or end with segment delimiter
Trailing delimiter
account/:project/{project_id}
Segment must have format key/value
Missing placeholder
account/{}:project/{project_id}
Segment has missing or empty value
Empty placeholder
account:project/{project_id}
Segment must have format key/value
Missing slash delimiter
account/{account_id}:env/prod
Free-form segment must use claim placeholder
Literal value in a free-form segment
<+pipeline.identifier>-<+stage.identifier>
Segment must have format key/value
Harness resolves the expressions first, and the resolved string contains no key/{claim} segments
Related articles
Workload identity overview: Understand how Harness issues tokens that carry execution context.
OIDC ID tokens for the Shell Script step: Declare named identities on the Shell Script step.
Last updated
Was this helpful?