OIDC With AWS

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

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

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

Add a sub Claim

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 Action section add the following:
   1. sts:AssumeRoleWithWebIdentity
   2. sts:TagSession
5. 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"
6. 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",
                }
            }
        }
    ]
}

📘

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:

1. organizationId - The env0 Organization ID
2. projectId - The env0 Project ID
3. templateId - The env0 Template ID
4. environmentId - The env0 Environment ID
5. deployerEmail - 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:

1. Go to the AWS IAM Role you created in the previous step
2. In the Trust relationships tab click on the Edit trust policy button
3. Under the Condition > StringEquals section of the Policy JSON add the designated claim as aws: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.
4. 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"
                    ]
                }
            }
        }
    ]
}

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 previously
• Duration - 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