OIDC With Vault

How to authenticate the env0 runner using Vault and OIDC

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 env0 to utilize OIDC to authenticate to your vault cluster to retrieve secrets. Refer to env0's OIDC configuration.

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

JWT Authentication Method

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

Configure JWT

Add Custom Claims

To add custom claims we will use the vault CLI. Make sure you have it installed on your machine and that you have access to the vault cluster. You will need to set the following environment variables:

  1. VAULT_ROLE_NAME
  2. VAULT_NAMESPACE
  3. VAULT_ADDR
  4. VAULT_TOKEN - You can also use the vault login command instead

Now let's execute the following command, and make sure you substitute Your_Vault_Role_Name with the role name and Your env0 Organization Id with your actual env0 organization Id.

vault write auth/jwt/role/Your_Vault_Role_Name - <<EOF
{
  "user_claim": "sub",
  "role_type": "jwt",
  "bound_audiences": ["https://prod.env0.com"],
  "bound_claims": {
    "organizationId": "Your env0 Organization Id",
    "apiKeyType": "oidc"
  }
}
EOF

🚧

More Claims

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

Authenticating to Vault With Env0 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

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