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

Pipeline identities

Declare identities in pipeline YAML so a pipeline, stage, or step can authenticate to external systems such as AWS and GCP.

When a pipeline interacts with an external system, such as AWS, GCP, Azure, or a secrets manager, the external system requires a verifiable identity to authenticate the request.

Pipeline identities enable OIDC-based authentication in pipelines without relying on long-lived credentials. Harness generates an OpenID Connect (OIDC) ID token through Harness ID on behalf of the pipeline identity. External systems that support OIDC and trust Harness as an OIDC identity provider can verify this token to authenticate the pipeline and authorize access to their resources.

You can use pipeline identities with any external system that supports OIDC and trusts Harness as an OIDC identity provider, such as AWS, GCP, Azure, and HashiCorp Vault.

You define the required identity in the identities map in your pipeline YAML. Harness passes the identity details to the module responsible for executing the work, which uses them to authenticate with the external system.

You can define identities at the pipeline, stage, or step level, as well as in templates. Identities are not limited to Shell Script steps. They can be used with any step that supports identities, as well as with OIDC-type connectors.

YAML only feature

Pipeline identities are available only in YAML. There is no UI for creating or editing them.

What you will learn from this topic

Before you begin

  • Feature flag: Enable PIPE_PIPELINE_IDENTITY for your account. Contact Harness Support to enable it.

  • Harness ID: Pipeline identities build on Harness ID. This topic covers only what the pipeline supports. For more information on how Harness generates the token, see Harness ID tokens for the Shell Script step.

  • Permissions: You need the View and Edit pipeline permissions to add or change identities in an existing pipeline, and Create to add them to a new pipeline. Identities are part of the pipeline definition, so they are subject to pipeline-level access control. For more information, see Permissions reference.

Identity configuration and execution

An identity is the information that Harness presents to an external system to say who is making the request.

The identities field is a map, so a single pipeline can declare several identities. For example, you can declare one identity for AWS and another for GCP, each with its own audience. The key for each entry is the identity's name.

Harness does not interpret how the external system uses the identity. Harness resolves the fields you define and hands them to the module that performs the work, such as a step that supports identities or an OIDC connector. That module sends them to the external system.

The Shell Script step is one example of a step that uses identities. In a Shell Script step, the identity name is the name of the environment variable that holds the generated token. For example, TOKEN is available as an environment variable in the step, and you access it as $TOKEN.


Declare an identity

Add an identities map at the level where you want the identity to be available. The placement of the map follows the level.

Level

Where to add identities

Pipeline

Under pipeline, alongside name, identifier, and stages.

Stage

Under stage, alongside name, identifier, and spec.

Step

Under step, alongside type, name, and spec.

Perform the following steps to declare an identity:

  1. Open the pipeline and select the YAML tab. To edit a template, open the template and select its YAML tab.

  2. Add an identities map at the level where you want the identity to be available.

  3. Add an entry for each identity. The key to the entry is the identity name.

  4. Set the identity fields for the entry.

  5. Save the pipeline.

Pipeline-level identity

The following example declares an identity named TOKEN at the pipeline level. Every stage and step in the pipeline can use it. The example uses a Shell Script step to decode the token so you can inspect its claims.

Pipeline-level identity

Step-level identity

The following example declares an identity at the step level. It is available only in that step.

Step-level identity with a subject template and custom claims

Go to Shell Script step to see how one step that supports identities injects a generated token into a script.


Identity fields

Each entry in the identities map supports the following fields.

Field
Description

cloudProvider

The cloud provider that the identity is used with. This field is optional. Supported values include AWS and GCP. For other external systems, such as Azure or HashiCorp Vault, omit cloudProvider and specify the expected value in audience. You cannot override this field at a lower level.

audience

The URL of the external system that the identity is created for. The external system checks this value to confirm that the identity is meant for it.

subjectTemplate

Identifies the pipeline to the external system, based on the pipeline identifier. Set it so the subject the external system receives matches the pipeline. The template uses the account/{account_id}:project/{project_id}:pipeline/{pipeline_id} format.

customClaims

Key-value pairs that you define for your own use case. Harness does not interpret them. Harness passes them to the module and the external system.

tokenMode

Controls how Harness uses the identity token. Supported values are STANDARD and CLIENT_ASSERTION. The default is STANDARD. Go to Token mode for details.

workloadUri

Required when tokenMode is CLIENT_ASSERTION. Specifies the URI that identifies the workload to the identity provider.

adfsEndpoint

Required when tokenMode is CLIENT_ASSERTION. Specifies the identity provider endpoint (for example, an AD FS endpoint) that receives the client assertion and exchanges it for an access token.

disabled

Set to true to make the identity unavailable. Set to false to make it available. A disabled identity is not resolved, and referencing it returns no value.


Token mode

Token mode controls how Harness uses the identity token it creates for your pipeline, stage, or step. You set it per identity with the tokenMode field.

Token mode
What it does
When to use it

STANDARD (default)

Harness issues a signed OIDC ID token for the identity. Your step receives the token, and you present it directly to the service you want to access, such as AWS, GCP, Azure, or Vault.

Most cases, where the service trusts Harness as an OIDC provider and accepts the token as is.

CLIENT_ASSERTION

The ID token is used as a client assertion. It proves the identity of your workload to your own identity provider, such as AD FS, which then issues the access token.

Your organization requires its own identity provider to issue the final credentials, rather than trusting Harness tokens directly.

The following example declares one identity in each mode.

Identities with different token modes

Token mode defaults and requirements

If you do not set tokenMode, Harness uses STANDARD. The CLIENT_ASSERTION mode requires the workloadUri and adfsEndpoint fields, which identify your workload and the endpoint of your identity provider. Go to Identity fields for details.


Scope and inheritance

Where you declare an identity decides where it is available.

  • An identity declared at the pipeline level is available in every stage and step of the pipeline.

  • An identity declared at the stage level is available in that stage and in the steps inside it. It is not available in other stages.

  • An identity declared at the step level is available only in that step.

For example, if you declare AWS_ID_TOKEN in one stage, you cannot use it in another stage. Declare it at the pipeline level if all stages need it.

Override an identity at a lower level

You can declare an identity with the same name at a lower level to change part of it. The lower-level definition is merged with the upper-level definition, and the lower-level values take precedence. You only need to list the fields you want to change. Every other field remains as defined at the upper level.

The override applies only to the stage or step where you make it. Other stages and steps continue to use the upper-level definition.

In the following example, the pipeline declares AWS_ID_TOKEN with an audience. One stage overrides only the audience. The cloud provider and custom claims still come from the pipeline-level definition.

Stage-level override of a pipeline-level identity

Disable an identity for selected stages

Use disabled to declare an identity once and use it only where you need it. Set disabled: true at the pipeline level so the identity is not available by default. Then set disabled: false in the stages where you want it.

In the following example, the identity is available in the Publish stage. In all other stages, referencing it returns no value.

Enable a disabled pipeline-level identity in one stage

Use identities in templates

Pipeline, stage, and step templates support the identities map in the same way as pipeline YAML. Declare the identities in the template definition, and they apply wherever the template is used.


Important notes

The following limitations apply to pipeline identities.

  • YAML only: Pipeline identities are configured in YAML. There is no UI for creating or editing them.

  • Expressions: Expressions are not supported in pipeline-level identities.

  • Cloud provider: The cloudProvider field cannot be overridden at the stage or step level.


Next steps

  • Shell Script step: An example of a step that injects a generated identity token into a script.

Last updated

Was this helpful?