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

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:


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/abc123 or project/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 account key 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

Component
Description
Example
Required

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.

Subject key
Required claim
Example segment
Description

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 account key can only use the {account_id} claim. account/{account_id} is valid, and account/{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, and project/marketing is 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 because purpose is custom, and account/{account_id}:cost/{project_id} is invalid because project_id must use the project key.


Free-form segments

Free-form segments let you add custom identity context using custom claims. They appear as a suffix after the structural segments.

Rule
Description
Example

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.

Reserved claim
Purpose

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

Invalid template
Error
Reason

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


Last updated

Was this helpful?