> 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/subject-templates.md).

# 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](#security-model), and what that prevents.
* [How to write a template](#pattern-syntax) with the supported segment and delimiter syntax.
* [Which structural segments are available](#structural-segments) and the claim each one requires.
* [How to add custom context](#free-form-segments) with free-form segments and custom claims.
* [Which claims are reserved](#claims-you-cannot-use) and rejected in a template.
* [When Harness validates a template](#validation-workflow), at registration and at token generation.
* [Which template granularity to choose](#examples) 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](https://developer.harness.io/harness-platform/use-harness-platform/pipelines/workload-identity/workload-identity-overview.md) 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:

```
account/{account_id}:org/{org_id}:project/{project_id}:pipeline/{pipeline_id}:execution/{execution_id}
```

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.

```
key/{claim_placeholder}:key/{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:

```
account/{account_id}:project/{project_id}:pipeline/{pipeline_id}
```

{% hint style="warning" %}
A template is not a free-text label or a Harness expression string. A value such as `<+pipeline.identifier>-<+stage.identifier>` is rejected, because Harness resolves the expressions first and the resolved value is a literal with no `key/{claim}` segments. To scope a subject to the pipeline, use the `pipeline/{pipeline_id}` segment and let Harness supply the value from the execution context.
{% endhint %}

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

```json
{
  "account_id": "acc-123",
  "project_id": "proj-456",
  "custom_claims": {
    "purpose": "deploy",
    "environment": "production"
  },
  "sub_template": "account/{account_id}:project/{project_id}:purpose/{purpose}:env/{environment}"
}
```

Harness flattens those claims to the top level:

```json
{
  "account_id": "acc-123",
  "project_id": "proj-456",
  "purpose": "deploy",
  "environment": "production"
}
```

Harness then substitutes the values to produce the subject:

```
account/acc-123:project/proj-456:purpose/deploy:env/production
```

***

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

```
account/{account_id}:project/{project_id}
```

**Pipeline-level**, for AWS role assumption scoped to one pipeline:

```
account/{account_id}:project/{project_id}:pipeline/{pipeline_id}
```

**Step-level**, the most specific scope available:

```
account/{account_id}:project/{project_id}:pipeline/{pipeline_id}:step/{step_id}
```

**Environment-specific**, for CD deployments:

```
account/{account_id}:org/{org_id}:project/{project_id}:environment/{environment_id}
```

**Purpose-based**, where `purpose` is a custom claim such as deploy, read, or write:

```
account/{account_id}:project/{project_id}:purpose/{purpose}
```

**Multi-dimensional**, combining several custom claims:

```
account/{account_id}:project/{project_id}:pipeline/{pipeline_id}:env/{environment}:region/{region}
```

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

***

## Related articles

* [Workload identity overview](https://developer.harness.io/harness-platform/use-harness-platform/pipelines/workload-identity/workload-identity-overview.md): Understand how Harness issues tokens that carry execution context.
* [OIDC ID tokens for the Shell Script step](https://developer.harness.io/docs/continuous-delivery/x-platform-cd-features/cd-steps/utilities/shell-script-step#oidc-id-tokens-for-the-shell-script-step): Declare named identities on the Shell Script step.
