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 - Configure to 1 hour for OIDC. How long will the token be valid. The token is being generated when the deployment starts not when the credential is being created.

🚧

Troubleshooting

Not authorized to perform sts:AssumeRoleWithWebIdentity

• Make sure your assume role durations match in the env0 credential and your maximum session in the role. Otherwise, try setting your duration to 1 hour