> ## Documentation Index > Fetch the complete documentation index at: https://docs.envzero.com/llms.txt > Use this file to discover all available pages before exploring further. # General OIDC Integrations > Configure OpenID Connect (OIDC) in env zero to issue short-lived JWT tokens for authenticating with AWS, Azure, GCP, and HashiCorp Vault. ## Using OpenID Connect Tokens [OpenID Connect](https://openid.net/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](https://datatracker.ietf.org/doc/html/rfc8725#section-3.9). * **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 `: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](https://www.vaultproject.io/docs/auth/jwt#jwt-authentication), or [AWS’s Creating OpenID Connect (OIDC) identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html). 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](#token-versions-v2-per-provider-audience-and-v1-legacy) above. ## Format of the OpenID Connect ID token The OpenID Connect ID token contains the following standard [claims](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). | 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](mailto:support@env0.com) | | `aud` | The audience, identifying the intended recipient. For v2 credentials it is provider-specific (see [Token versions](#token-versions-v2-per-provider-audience-and-v1-legacy)); 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](/api-reference/credentials/create-api-key). | | `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](#using-claims-in-iam-trust-policies). | Deprecated Additional Claims In 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](#token-versions-v2-per-provider-audience-and-v1-legacy)), 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](#using-claims-in-iam-trust-policies). | When writing an AWS IAM trust policy that references `aws:PrincipalTag/` or `aws:RequestTag/`, 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](#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](#token-versions-v2-per-provider-audience-and-v1-legacy)), the `azp` claim is absent (replaced by `client_id`), and the deprecated `https://env0.com/*` claims are omitted. The `iss` is unchanged: ```json theme={null} { "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: ```json theme={null} { "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/`. `aws:RequestTag/` is also valid in AWS trust policies and can be used interchangeably for these conditions. ##### Unsafe vs. safe examples Unsafe, `env0Tag` is user-controlled: ```json theme={null} { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam:::oidc-provider/" }, "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: ```json theme={null} { "Condition": { "StringEquals": { "aws:PrincipalTag/organizationId": "" } } } ``` Safe, scope further to a specific project: ```json theme={null} { "Condition": { "StringEquals": { "aws:PrincipalTag/organizationId": "", "aws:PrincipalTag/projectId": "" } } } ``` ##### 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](/guides/integrations/oidc-integrations/oidc-with-aws) - Configure OIDC authentication for AWS environments. * [OIDC for Azure](/guides/integrations/oidc-integrations/oidc-with-azure) - Configure OIDC authentication for Azure environments. * [OIDC for GCP](/guides/integrations/oidc-integrations/oidc-with-google-cloud-platform) - Configure OIDC authentication for GCP environments. * [OIDC for Vault](/guides/integrations/oidc-integrations/oidc-with-vault) - Use OIDC tokens to authenticate with HashiCorp Vault.