How to authenticate the env0 runner using AWS and OIDC

This guide is to help you connect to AWS with OIDC, instead of using a static API Key and Secret.


This guide will show you how to create an AWS Identity provider and IAM Role to go along with it, and configure env0 to utilize OIDC with your Terraform code. This will allow you to authenticate to AWS and get temporary credentials by accepting env0's OIDC token. Refer to env0's OIDC configuration.

AWS Identity Provider And IAM Role

In order to be able to authenticate with OIDC we will need to create an Identity provider in your AWS account and attach an IAM role to it. We will follow this guide by AWS.

Create an Identity Provider

  1. Login to your desired AWS account and go to Identity and Access Management (IAM)
  2. In the left side menu under Access management click on the Identity providers
  3. Click on the Add provider button
  4. Choose the OpenID Connect option
  5. In the Provider URL enter https://login.app.env0.com/and click on the Get thumbprint button
  6. In the Audience enter hoMiq9PdkRh9LUvVpH4wIErWg50VSG1b
  7. Add tags if you wish, and click on the Add provider button to create the identity provider
Add an Identity Provider

Add an Identity Provider

Assign an IAM Role

  1. Go to the Identity Provider you created in the previous step
  2. In the Audiences table select the hoMiq9PdkRh9LUvVpH4wIErWg50VSG1b and click on the action button and select Assign role
  3. Select the Create a new role option which will open the Create role wizard
  4. Select the Web Identity option. In the Identity provider select login.app.env0.com/:aud and in the Audience select hoMiq9PdkRh9LUvVpH4wIErWg50VSG1b and click on the Next: Permissions button
  5. In the permissions phase select the designer permission you would like this role to have. Remember those permissions will be used to deploy your IaC so make sure they are correlated to the permissions your code needs.
  6. In the Add tags add the tags you desire
  7. In the Review phase give the role a name and a description and click on the Create role button
Create a Role

Create a Role

Add a sub Claim (Optional)

  1. Retrieve your organization sub identifier using this guide
  2. Go to the AWS IAM Role you created in the previous step
  3. In the Trust relationships tab click on the Edit trust policy button
  4. Under the Condition > StringEquals section of the Policy JSON add "login.app.env0.com/:sub": "{your_organization_sub}" - Make sure you substitute the {your_organization_sub} with the sub value you retrieved in the first step, so it should be something like "login.app.env0.com/:sub": "auth0|632b8219674bde0224a96141"
  5. Now click on the Update policy button
Trust Relationships

Trust Relationships


Custom Claims

AWS OIDC identity providers supports only the aud and sub claims, so you won't be able to configure any other claims from the JWT token.

You can read more about it here

Configure Your Code With OIDC

Terraform Usage

To use Terraform with OIDC we will assume an IAM Role using A Web Identity method that is also defined here. Since this method requires a file we will need to add a Custom Flows to write the OIDC token into a file.

version: 2
        - name: Set OIDC Token 
          run: echo $ENV0_OIDC_TOKEN > web-identity-token.txt

In your Terraform code you need to point to the file you have creaed

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"

# Configure the AWS Provider
provider "aws" {
  assume_role_with_web_identity {
    role_arn                = "{The OIDC Role ARN you have creatred}"
    session_name            = "env0_OIDC_session"
    web_identity_token_file = "web-identity-token.txt"


If you like to use the AWS CLI to get temporary credentials using OIDC you can use the AWS CLI using a custom flow. To use it you will need to execute the aws sts assume-role-with-web-identity command inside your env0.yml file.

Here is an example of an env0.yml file that will get temporary AWS credentials and will set them inside environment variables. Make sure you replace the ENV0_OIDC_ROLE_ARN environment variable with the role ARN you've created in previous steps, and if you like you can also change the session name:

version: 2
        - name: Set OIDC 
          run: echo $ENV0_OIDC_TOKEN > web-identity-token.txt
        - name: Using AWS CLI
          run: | 
            aws sts assume-role-with-web-identity --role-arn "${ENV0_OIDC_ROLE_ARN}" --role-session-name "env0_OIDC_session" --web-identity-token $ENV0_OIDC_TOKEN --duration-seconds 3600 --query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' --output json > aws-sts-get-session-token.json
            echo AWS_ACCESS_KEY_ID=$(jq '.[0]' aws-sts-get-session-token.json) >> $ENV0_ENV
            echo AWS_SECRET_ACCESS_KEY=$(jq '.[1]' aws-sts-get-session-token.json) >> $ENV0_ENV
            echo AWS_SESSION_TOKEN=$(jq '.[2]' aws-sts-get-session-token.json) >> $ENV0_ENV
            rm aws-sts-get-session-token.json