OIDC With AWS
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.
Overview
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. 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
- Login to your desired AWS account and go to
Identity and Access Management (IAM)
- In the left side menu under
Access management
click on theIdentity providers
- Click on the
Add provider
button - Choose the
OpenID Connect
option - In the
Provider URL
enterhttps://login.app.env0.com/
and click on theGet thumbprint
button - In the
Audience
enterhoMiq9PdkRh9LUvVpH4wIErWg50VSG1b
- Add tags if you wish, and click on the
Add provider
button to create the identity provider

Add an Identity Provider
Assign an IAM Role
- Go to the Identity Provider you created in the previous step
- In the
Audiences
table select thehoMiq9PdkRh9LUvVpH4wIErWg50VSG1b
and click on the action button and selectAssign role
- Select the
Create a new role
option which will open theCreate role
wizard - Select the
Web Identity
option. In theIdentity provider
selectlogin.app.env0.com/:aud
and in theAudience
selecthoMiq9PdkRh9LUvVpH4wIErWg50VSG1b
and click on theNext: Permissions
button - 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.
- In the
Add tags
add the tags you desire - In the
Review
phase give the role a name and a description and click on theCreate role
button

Create a Role
Add a sub
Claim
sub
Claim- Retrieve your organization
sub
identifier using this guide - Go to the AWS IAM Role you created in the previous step
- In the
Trust relationships
tab click on theEdit trust policy
button - Under the
Action
section add the following:sts:AssumeRoleWithWebIdentity
sts:TagSession
- 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 thesub
value you retrieved in the first step, so it should be something like"login.app.env0.com/:sub": "auth0|632b8219674bde0224a96141"
- Now click on the
Update policy
button
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::XXXXXXXXXXXX:oidc-provider/login.app.env0.com/"
},
"Action": [
"sts:AssumeRoleWithWebIdentity",
"sts:TagSession"
],
"Condition": {
"StringEquals": {
"login.app.env0.com/:aud": "hoMiq9PdkRh9LUvVpH4wIErWg50VSG1b",
"login.app.env0.com/:sub": "auth0|632b8219674bde0224a96141",
}
}
}
]
}

Trust Relationships
Self-Hosted Agent Users
For EKS users, you will also need to add
"Action": "sts:AssumeRoleWithWebIdentity"
to either your node role or service account role where your agent is running.
Custom Claims With AWS Session Tags (Optional)
AWS OIDC identity providers support only a few out-of-the-box claims, which is a limitation when you want to control who inside env0 can access this AWS role. You can read more about available claims for AWS here.
For that, AWS offers to pass Session tags inside the JWT token so that you would be able to have more control and define the right access level.
When running a deployment inside env0, it will create a JWT token with claims for AWS under https://aws.amazon.com/tags
with a section called principal_tags
which will include the following claims:
organizationId
- The env0 Organization IDprojectId
- The env0 Project IDtemplateId
- The env0 Template IDenvironmentId
- The env0 Environment IDdeployerEmail
- The email address of the user who created this deployment
AWS Session Tags Limitation
As sessions tags has a length limitation, we are only adding specific claims. We are confident that the provided claims will enable you to get the desired access control for your AWS role.
You can read more about AWS Session Tags limitation here.
In order to configure the AWS Session Tags, you need to edit the role you created in the previous steps:
- Go to the AWS IAM Role you created in the previous step
- In the
Trust relationships
tab click on theEdit trust policy
button - Under the
Condition > StringEquals
section of the Policy JSON add the designated claim asaws:RequestTag/{custom_claim}
, as an example, if I would like to make sure that only a specific project ID has access to this AWS role, you should add the following:"aws:RequestTag/projectId": ["1a433171-217e-4f58-9b4e-308d4d77902f"]
- This is applicable to all custom claims mentioned above. See this full example in the image below. - Now click on the
Update policy
button
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::XXXXXXXXXXXX:oidc-provider/login.app.env0.com/"
},
"Action": [
"sts:AssumeRoleWithWebIdentity",
"sts:TagSession"
],
"Condition": {
"StringEquals": {
"login.app.env0.com/:aud": "hoMiq9PdkRh9LUvVpH4wIErWg50VSG1b",
"login.app.env0.com/:sub": "auth0|632b8219674bde0224a96141",
"aws:RequestTag/projectId": [
"1a433171-217e-4f58-9b4e-308d4d77902f"
]
}
}
}
]
}

Trust Relationships With Custom Claims
Configure Env0 OIDC Credential
Go to the organization's credentials page and create a new deployment credential. Select AWS OIDC
type and enter the following fields:
Role ARN
- The ARN of the role that was created previouslyDuration
- Default to 5 hours. How long will the token be valid. The token is being generated when the deployment starts not when the credential is being created.
Configure Your Code With OIDC
If you don't want to use the env0 OIDC credential you can configure your terraform and use custom flow to setup what is needed to make OIDC work.
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
deploy:
steps:
terraformInit:
before:
- 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 created
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"
}
}
Using AWS CLI
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
deploy:
steps:
terraformInit:
before:
- 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 --region us-east-1
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
Updated 10 days ago