General OIDC Integrations

Using OpenID Connect Tokens

OpenID Connect (OIDC) allows your deployments to exchange short-lived tokens directly from your cloud provider. env zero provides an OIDC token (JWT) as an environment variable. A deployment can use this to access compatible cloud services without a long-lived credential stored in env zero.

Token versions: v2 (per-provider audience) and v1 (legacy)

env zero issues OIDC tokens in two formats, selected per credential:

v2 (recommended) - each cloud provider receives a token whose aud claim identifies that provider (for example, sts.amazonaws.com for AWS). A token minted for one provider is not valid against another, which closes the token-substitution (“confused deputy”) risk described in RFC 8725.
v1 (legacy) - every provider in a deployment receives the same token, whose aud claim is https://prod.env0.com. This is the original behavior and remains the default for existing credentials. AWS is the exception on the configuration side: because v1 tokens also carry an azp claim, AWS matches <provider>:aud against azp, so AWS v1 trust is keyed on the env zero client ID (hoMiq9PdkRh9LUvVpH4wIErWg50VSG1b) rather than on https://prod.env0.com (the aud claim itself is unchanged).

You select the format per credential with the Use v2 OIDC token checkbox when creating or editing an OIDC credential. The value each provider expects is:

Provider	v2 audience (`aud`)	v1 audience to configure
AWS	`sts.amazonaws.com`	env zero client ID `hoMiq9PdkRh9LUvVpH4wIErWg50VSG1b` (matched via `azp`; the `aud` claim is `https://prod.env0.com`)
Azure	`api://AzureADTokenExchange`	`https://prod.env0.com`
GCP	`api://env0-gcp`	`https://prod.env0.com`
Vault	`api://env0-vault`	`https://prod.env0.com`

Enabling v2 changes the token’s audience, so a credential stops working against your existing cloud trust until you update that trust to expect the new audience. Configure the v2 audience on your cloud provider first, then enable the checkbox. The checkbox means “my cloud trust already expects the v2 audience”, not “make this credential more secure with one click”. Each provider guide covers both the initial v2 setup and migrating an existing v1 credential.

v2 tokens also omit the deprecated https://env0.com/* namespaced claims. If you condition trust on any of those, switch to the non-namespaced equivalents before enabling v2.

Enabling OIDC Token Availability

A JWT token could be available during deployment as an environment variable called ENV0_OIDC_TOKEN. This feature can be enabled by selecting an OIDC credential when creating a credential in the organization’s credentials page.
In addition, organization admins can enable this feature by toggling the related checkbox in the organization’s policies tab.

Organization policies page showing the Enable OIDC during deployments checkbox

Setting Up Your 3rd Party Service Integration

Consult your 3rd party service’s documentation for how to add an identity provider.
For example, Vault’s JWT Authentication, or AWS’s Creating OpenID Connect (OIDC) identity providers. The OIDC token is unique to your organization. The custom claims attached to the token contain your organization ID. You can find your env zero organization ID by navigating to the Organization Settings page in our web app and copying the UUID from the URL. The token’s aud claim depends on the credential’s token version: provider-specific for v2 credentials, or https://prod.env0.com for v1 (the same for every provider). For AWS v1 you configure trust on the env zero client ID rather than this aud value, because v1 tokens carry an azp claim. See Token versions above.

Format of the OpenID Connect ID token

The OpenID Connect ID token contains the following standard claims.

Claims	Description
`iss`	The issuer. The issuer is specific to env zero and the value is: `https://login.app.env0.com/`
`sub`	The subject. It contains the user ID that represents your organization’s OIDC user. If you like to get this ID please contact us
`aud`	The audience, identifying the intended recipient. For v2 credentials it is provider-specific (see Token versions); for v1 credentials it is `https://prod.env0.com` for all providers. (For AWS v1, trust is keyed on the client ID via the `azp` claim, but the `aud` claim itself is still `https://prod.env0.com`.)
`iat`	The time of issuance. This is when the token was created, which is shortly before the deployment starts.
`exp`	The expiration time. Its value is 24 hours after the time of issuance.

The OpenID Connect ID token also contains some additional custom claims that you should validate:

Additional Claims	Description
`apiKeyType`	The value should be `oidc`. Claim that the provided JWT should be from type `oidc` only
`organizationId`	Unique organization ID
`projectId`	Unique project ID
`projectName`	Project name
`templateId`	Unique template ID
`templateName`	Template name
`environmentId`	Unique environment ID
`environmentName`	Environment name
`workspaceName`	Workspace name
`deploymentLogId`	Unique deployment ID
`deploymentType`	Deployment type such as `deploy`, `destroy`, `prPlan`, or `task`. See the full list.
`deployerEmail`	Email of the person that triggered the deployment
`env0Tag`	User-controlled free-form string (when `ENV0_OIDC_TAG` environment variable is set). Informational context only, not an identity claim. See Using claims in IAM trust policies.

Deprecated Additional ClaimsIn addition to all the Custom Claims that are mentioned above, we also have all those claims with a prefix of https://env0.com/ (for example: https://env0.com/organizationId)
Those claims are deprecated and will be removed in the future. v2 tokens already omit them (see Token versions), so do not rely on the https://env0.com/* claims when configuring v2.

Specific AWS Session Tags:

In addition to the claims mentioned above, there is also a specific section for AWS tags inside a https://aws.amazon.com/tags and inside principal_tags:

Additional Claims	Description
`https://aws.amazon.com/tags[principal_tags][organizationId]`	Unique organization ID
`https://aws.amazon.com/tags[principal_tags][projectId]`	Unique project ID
`https://aws.amazon.com/tags[principal_tags][templateId]`	Unique template ID
`https://aws.amazon.com/tags[principal_tags][environmentId]`	Unique environment ID
`https://aws.amazon.com/tags[principal_tags][deployerEmail]`	Email of the person that triggered the deployment
`https://aws.amazon.com/tags[principal_tags][deploymentType]`	Deployment Type
`https://aws.amazon.com/tags[principal_tags][env0Tag]`	User-controlled free-form string. Informational context only, not safe as an IAM trust condition. See Using claims in IAM trust policies.

When writing an AWS IAM trust policy that references aws:PrincipalTag/<claim> or aws:RequestTag/<claim>, always gate on organizationId (and optionally projectId). Do not use env0Tag as a trust condition. It is user-controlled and not unique per tenant. See Using claims in IAM trust policies.

Here is an example of a full JWT Token. The example below is a v1 token. A v2 token differs in three ways: aud is the provider-specific value (see Token versions), the azp claim is absent (replaced by client_id), and the deprecated https://env0.com/* claims are omitted. The iss is unchanged:

{
  "https://aws.amazon.com/tags": {
    "principal_tags": {
      "organizationId": [ "66a38abf-69bc-4cb7-ad73-7f61e389079f" ],
      "projectId": [ "5b44fa6d-ecfd-40ab-8e69-14d6fe7c638c" ],
      "templateId": [ "dc9808e2-44d3-48dd-b12a-31a08927ee6e" ],
      "environmentId": [ "9c3ca3cf-870d-4db4-9c60-5adf37faab45" ],
      "deployerEmail": [ "test@test.com" ],
      "deploymentType": [ "deploy" ],
      "env0Tag": [ "production-workload" ]
    }
  },
  "apiKeyType": "oidc",
  "organization": "66a38abf-69bc-4cb7-ad73-7f61e389079f",
  "organizationId": "66a38abf-69bc-4cb7-ad73-7f61e389079f",
  "projectId": "5b44fa6d-ecfd-40ab-8e69-14d6fe7c638c",
  "projectName": "Test Project",
  "templateId": "dc9808e2-44d3-48dd-b12a-31a08927ee6e",
  "templateName": "Test Template",
  "environmentId": "9c3ca3cf-870d-4db4-9c60-5adf37faab45",
  "environmentName": "Dev Test Environment",   
  "workspaceName": "env09c3ca3",
  "deployerEmail": "test@test.com",
  "deploymentLogId": "96e2b169-5e4a-44a4-876b-4a5d26f4412c",  
  "deploymentType": "deploy",  
  "https://env0.com/apiKeyType": "oidc",
  "https://env0.com/organization": "66a38abf-69bc-4cb7-ad73-7f61e389079f",
  "https://env0.com/organizationId": "66a38abf-69bc-4cb7-ad73-7f61e389079f",
  "https://env0.com/projectId": "5b44fa6d-ecfd-40ab-8e69-14d6fe7c638c",
  "https://env0.com/projectName": "Test Project",
  "https://env0.com/templateId": "dc9808e2-44d3-48dd-b12a-31a08927ee6e",
  "https://env0.com/templateName": "Test Template",
  "https://env0.com/environmentId": "9c3ca3cf-870d-4db4-9c60-5adf37faab45",
  "https://env0.com/environmentName": "Dev Test Environment",
  "https://env0.com/workspaceName": "env09c3ca3",  
  "https://env0.com/deploymentLogId": "96e2b169-5e4a-44a4-876b-4a5d26f4412c",
  "https://env0.com/deploymentType": "deploy",
  "https://env0.com/deployerEmail": "test@test.com",
  "https://env0.com/env0Tag": "production-workload",
  "env0Tag": "production-workload",
  "iss": "https://login.app.env0.com/",
  "sub": "auth0|63021f2ce98a11d0678ed6fe",
  "aud": "https://prod.env0.com",
  "iat": 1685696926,
  "exp": 1685783326,
  "azp": "hoMiq9PdkRh9LUvVpH4wIErWg50VSG1b",
  "gty": "password"
}

Custom Claims

You can add a custom claim to the OIDC token by setting the ENV0_OIDC_TAG environment variable in env zero.

Security warning: do not use env0Tag as the sole IAM trust condition.env0Tag is a free-form string set by the user configuring the env zero project. env zero does not validate or namespace this value, and it is not unique per tenant. Because every env zero installation signs OIDC tokens with the same issuer, any env zero user in any organization who knows or guesses the string can produce a token carrying the same env0Tag and assume your role.If you use env0Tag in an AWS IAM trust policy, you must also constrain the policy on an immutable, env zero issued claim such as aws:PrincipalTag/organizationId. Never rely on env0Tag alone.

Usage:

Set ENV0_OIDC_TAG as an environment variable in env zero.
The value is included in the token as both env0Tag and https://env0.com/env0Tag claims.
For AWS integrations, it is also included in the https://aws.amazon.com/tags principal_tags.

Example: If you set ENV0_OIDC_TAG=production-workload, the token includes:

{
  "env0Tag": "production-workload",
  "https://env0.com/env0Tag": "production-workload",
  "https://aws.amazon.com/tags": {
    "principal_tags": {
      "env0Tag": ["production-workload"]
    }
  }
}

Treat this value as informational context (for example, a log label or a marker surfaced in downstream tools). Do not treat it as identity.

Using claims in IAM trust policies

Because env0Tag is user-controlled, it is not safe as an authorization gate. Use system-issued claims (organizationId, projectId, environmentId, templateId) for IAM trust conditions instead, and keep env0Tag for informational use only. The examples below use aws:PrincipalTag/<claim>. aws:RequestTag/<claim> is also valid in AWS trust policies and can be used interchangeably for these conditions.

Unsafe vs. safe examples

Unsafe, env0Tag is user-controlled:

{
  "Effect": "Allow",
  "Principal": { "Federated": "arn:aws:iam::<acct>:oidc-provider/<env0-issuer>" },
  "Action": "sts:AssumeRoleWithWebIdentity",
  "Condition": {
    "StringEquals": {
      "aws:PrincipalTag/env0Tag": "my-secret-string"
    }
  }
}

Anyone in any env zero org who sets ENV0_OIDC_TAG=my-secret-string can assume this role. Safe, bind to immutable org identity:

{
  "Condition": {
    "StringEquals": {
      "aws:PrincipalTag/organizationId": "<your-env0-org-id>"
    }
  }
}

Safe, scope further to a specific project:

{
  "Condition": {
    "StringEquals": {
      "aws:PrincipalTag/organizationId": "<your-env0-org-id>",
      "aws:PrincipalTag/projectId": "<your-project-id>"
    }
  }
}

Which claims are safe for trust conditions?

Claim	Source	Safe as IAM trust condition?
`organizationId`	env zero	Yes. Immutable, unique per tenant.
`projectId`	env zero	Yes. Immutable, scopes to a single project.
`environmentId`	env zero	Yes. Immutable.
`templateId`	env zero	Yes. Immutable.
`deployerEmail`	env zero	Use with care. Immutable per deploy but the org can change who deploys. Combine with `organizationId`.
`env0Tag`	End user	No. Never as a sole condition. Informational context only.

JWT Verification

JWT signatures will be verified against public keys from the issuer.
A JSON Web Key Set (JWKS) URL should be configured on your 3rd party service side.
Keys will be fetched from this endpoint during authentication.
Our JWKS URL is: https://login.app.env0.com/.well-known/jwks.json

Next steps

OIDC for AWS - Configure OIDC authentication for AWS environments.
OIDC for Azure - Configure OIDC authentication for Azure environments.
OIDC for GCP - Configure OIDC authentication for GCP environments.
OIDC for Vault - Use OIDC tokens to authenticate with HashiCorp Vault.

GET STARTED

AUTOMATE INFRASTRUCTURE

STANDARDIZE OPERATIONS

CLOUD MANAGEMENT

COLLABORATE SECURELY

GOVERNANCE & USAGE OPTIMIZATION

COMMUNITY & LEARNING RESOURCES

BILLING & PRICING

General OIDC Integrations

Using OpenID Connect Tokens

Token versions: v2 (per-provider audience) and v1 (legacy)

Enabling OIDC Token Availability

Setting Up Your 3rd Party Service Integration

Format of the OpenID Connect ID token

Specific AWS Session Tags:

Custom Claims

Using claims in IAM trust policies

Unsafe vs. safe examples

Which claims are safe for trust conditions?

JWT Verification

Next steps

​Using OpenID Connect Tokens

​Token versions: v2 (per-provider audience) and v1 (legacy)

​Enabling OIDC Token Availability

​Setting Up Your 3rd Party Service Integration

​Format of the OpenID Connect ID token

​Specific AWS Session Tags:

​Custom Claims

​Using claims in IAM trust policies

Unsafe vs. safe examples

Which claims are safe for trust conditions?

​JWT Verification

​Next steps

Using OpenID Connect Tokens

Token versions: v2 (per-provider audience) and v1 (legacy)

Enabling OIDC Token Availability

Setting Up Your 3rd Party Service Integration

Format of the OpenID Connect ID token

Specific AWS Session Tags:

Custom Claims

Using claims in IAM trust policies

JWT Verification

Next steps