OIDC for Vault

This guide is to help you connect to Vault with OIDC.

Overview

This guide will show you how to create a JWT Authentication Method, and how to configure env zero to utilize OIDC to authenticate to your vault cluster to retrieve secrets. Refer to env zero’s OIDC configuration.

This guide configures a v2 OIDC credential (the recommended format), where the token audience is api://env0-vault. See Token versions for background. If you already authenticate to Vault with a v1 credential (the role’s bound_audiences set to https://prod.env0.com), see Migrating an existing v1 credential below.

We are going to follow the Vault documentation on how to create a JWT Authentication

JWT Authentication Method

Login to your vault cluster
In the side navigation bar click on Access
Choose Authentication Methods in the left side menu
Click on the Enable new method button and it will open the Authentication method creation wizard
Choose JWT
Expand Method Options add a description and the relevant configuration and click on the Enabled Method button
In the Configure JWT page under the Jwks url enter https://login.app.env0.com/.well-known/jwks.json
Expand JWT Options and set the Bound issuer to be https://login.app.env0.com/
Click on the Save button

Vault JWT configuration interface showing OIDC authentication setup

Setup Secrets Store and Create Policy

Create a KV store in vault to save and fetch secrets.

vault secrets enable -path=secrets-for-env0/ kv

A policy needs to be created to define which secrets can be accessed. Here’s an example:

vault policy write env0-access - <<EOF
path "secrets-for-env0/*" {
    capabilities = ["read", "create", "update"]
}
EOF

To create the role that binds the policy, sub, aud and env0 custom claims we will use the vault CLI. Make sure you have it installed on your machine and that you have access to vault. Export the following environment variables:

export ENV0_ORG_ID="your_env_zero_org_id"
export VAULT_ROLE_NAME="your_vault_role_name"
export VAULT_ADDR="your_vault_address_url"
export VAULT_NAMESPACE="your_vault_namespace" (optional)
export VAULT_TOKEN="your_vault_token"

Vault CLI uses the VAULT_TOKEN environment variable to authenticate but if you prefer, you can skip it and use vault login instead. Now execute the following command to create the role:

vault write auth/jwt/role/$VAULT_ROLE_NAME - <<EOF
{
  "user_claim": "sub",
  "role_type": "jwt",
  "policies": ["env0-access"],
  "bound_audiences": ["api://env0-vault"],
  "bound_claims": {
    "organizationId": "$ENV0_ORG_ID",
    "apiKeyType": "oidc"
  }
}
EOF

More ClaimsIn this example we only set the aud, the organizationId and the apiKeyType claims, however you can also set any additional claims you would like from the list of claims we support. The list is located here

Authenticating to Vault with env zero Credential

Go to the organization’s credentials page and create a new deployment credential. Select Vault OIDC type and enter the following fields:

Address - The vault address, including port
Version- The vault version to use
Role Name - Vault role name
JWT Auth Backend Path - Path to the new authentication method
Namespace- Optional, the vault namespace
Use v2 OIDC token - check this box so env zero mints a token with the api://env0-vault audience set in the role’s bound_audiences above. The form shows the resulting Audience (aud) value. Leaving it unchecked produces a v1 token (aud: https://prod.env0.com), which the role will reject unless that audience is also bound.

env zero Vault OIDC credential form with the Use v2 OIDC token checkbox enabled and Audience set to api://env0-vault

After creating the credential you will need to go to the relevant project and assign that credential to the project in the project’s credentials page. Now all environments within the project will have the relevant environment variables available.

Authenticating to Vault with Terraform Provider

To configure the vault terraform provider all you need is the vault provider block and the VAULT OIDC deployment credentials set on the project. Example:

provider "vault" {
  address          = var.vault_address
  skip_child_token = true # (depends on your role vault policy)
}

The VAULT OIDC deployment credentials are used to authenticate with the vault server along with the ENV0_OIDC_TOKEN JWT token which then sets the VAULT_TOKEN variable with the actual session token that is returned from the vault server used for authentication/authorization.

Migrating an existing v1 credential

If you already authenticate to Vault with a v1 env zero OIDC credential, your JWT role’s bound_audiences is ["https://prod.env0.com"]. Because bound_audiences is a list, you can bind the v2 audience alongside the old one and migrate without downtime:

Add the v2 audience to the role. Update the role to bind both audiences, keeping the old one for now:

vault write auth/jwt/role/$VAULT_ROLE_NAME - <<EOF
{
  "user_claim": "sub",
  "role_type": "jwt",
  "policies": ["env0-access"],
  "bound_audiences": ["https://prod.env0.com", "api://env0-vault"],
  "bound_claims": {
    "organizationId": "$ENV0_ORG_ID",
    "apiKeyType": "oidc"
  }
}
EOF

Enable v2 on the credential. Edit the Vault OIDC credential in env zero and check Use v2 OIDC token. The next deployment mints a token with aud: api://env0-vault.
Remove the old audience once migration is complete. After confirming v2 deployments authenticate successfully, you can drop https://prod.env0.com from bound_audiences so the role accepts only the provider-specific audience.

Next steps

Retrieve OIDC Subject Identifier - Find the subject identifier for your OIDC token.
OIDC for AWS - Set up OIDC for AWS cloud authentication.
OIDC for Azure - Set up OIDC for Azure cloud authentication.

GET STARTED

AUTOMATE INFRASTRUCTURE

STANDARDIZE OPERATIONS

CLOUD MANAGEMENT

COLLABORATE SECURELY

GOVERNANCE & USAGE OPTIMIZATION

COMMUNITY & LEARNING RESOURCES

BILLING & PRICING

Overview

JWT Authentication Method

Setup Secrets Store and Create Policy

Authenticating to Vault with env zero Credential

Authenticating to Vault with Terraform Provider

Migrating an existing v1 credential

Next steps

​Overview

​JWT Authentication Method

​Setup Secrets Store and Create Policy

​Create Login Role

​Authenticating to Vault with env zero Credential

​Authenticating to Vault with Terraform Provider

​Migrating an existing v1 credential

​Next steps

Overview

JWT Authentication Method

Setup Secrets Store and Create Policy

Create Login Role

Authenticating to Vault with env zero Credential

Authenticating to Vault with Terraform Provider

Migrating an existing v1 credential

Next steps