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.
What you will learn from this topic
What an identity is and how Harness passes it to an external system.
How to declare an identity at the pipeline, stage, and step levels in YAML.
How to set each identity field.
How to choose a token mode for each identity.
How to control where an identity is available using scope and inheritance, overrides, and the disabled field.
How to use identities in templates.
Before you begin
Feature flag: Enable
PIPE_PIPELINE_IDENTITYfor 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:
Open the pipeline and select the YAML tab. To edit a template, open the template and select its YAML tab.
Add an
identitiesmap at the level where you want the identity to be available.Add an entry for each identity. The key to the entry is the identity name.
Set the identity fields for the entry.
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.
Step-level identity
The following example declares an identity at the step level. It is available only in that step.
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.
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.
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.
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.
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.
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
cloudProviderfield 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?