OIDC With 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 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

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

Authenticating to Vault With Terraform

If you are using Vault provider to retrieve your secrets you can specify it using Terraform

provider "vault" {
  address = "https://vault.example.net:8200"
  auth_login_jwt {
    namespace = "namespace"
    role = "my_role"
  }
}

You will also need to set the TERRAFORM_VAULT_AUTH_JWT as an environment variable to your environment and set the value to be $ENV0_OIDC_TOKEN. We will do so by adding the following command in your env0.yml file:

version: 2
deploy:
  steps:
    setupVariables:
      after:
        - name: Set OIDC Token For Vault
          run: echo TERRAFORM_VAULT_AUTH_JWT=$ENV0_OIDC_TOKEN >> $ENV0_ENV

Authenticating to Vault Using Vault CLI

This will require you to install the Vault CLI during the deployment and then use the CLI to get a token for your Vault cluster. Here is an example env0.yml that will install Vault CLI and get a new Vault token using the JWT token. This requires 3 environment variables, VAULT_VERSION to specify the version of the CLI, VAULT_ROLE_NAME to specify the role name you would like to login to, and VAULT_ADDR to specify the Vault Cluster URL:

version: 2
deploy:
  steps:
    setupVariables:
      after:
        - name: Get Vault Token Using CLI
          run: |
          	curl https://releases.hashicorp.com/vault/${VAULT_VERSION}/vault_${VAULT_VERSION}_linux_amd64.zip --output vault.zip
            unzip vault.zip
            ./vault write auth/jwt/login role="${VAULT_ROLE_NAME}" jwt="${ENV0_OIDC_TOKEN}"