Configuring OpenID Connect for AWS

This document outlines the steps required to configure Pulumi to use OpenID Connect to authenticate with AWS. OIDC in AWS uses a web identity provider to assume an IAM role. Access to the IAM role is authorized using a trust policy that validates the contents of the OIDC token issued by the Pulumi Cloud.

Prerequisites

• You must have sufficient AWS IAM privileges to create identity providers and IAM roles.

Automated setup with the Pulumi CLI

If you would rather not walk through the AWS console by hand, the pulumi env setup aws command (Pulumi CLI v3.261.0 and later) creates the identity provider, an IAM role scoped to your Pulumi organization, and its trust policy, then creates the ESC environment that uses it. Log in to Pulumi Cloud first with pulumi login, then run:

pulumi env setup aws --policy AdministratorAccess

Pass --account to target one or more specific AWS accounts, or --sso to sign in through AWS SSO and configure multiple accounts in one run. Use --policy ReadOnlyAccess instead of AdministratorAccess if the environment is only needed for Discovery; AdministratorAccess is required for Deployments. Add --yes to skip confirmation prompts once you are comfortable with what the command creates.

Reach for the manual steps below instead when you already have an OIDC identity provider you want to reuse, when your organization provisions IAM roles through its own infrastructure as code, or when you need trust-policy conditions the command does not yet expose, such as restricting subjectAttributes to a specific environment.

Create the identity provider

1. In the navigation pane of the IAM console, choose Identity providers, and then choose Add provider.
2. In the Provider type section, select the radio button next to OpenID Connect.
3. For the Provider URL, provide the following URL: https://api.pulumi.com/oidc
4. For the Audience field, the value is the name of your Pulumi organization prefixed with aws: (e.g. aws:{org}). Then select Add provider.
   For the default project, the audience will use just the Pulumi organization name. This is to prevent regressions for legacy environments.

Configure the IAM role

Once you have created the identity provider, you will see a notification at the top of your screen prompting you to assign an IAM role.

1. Select the Assign role button.
2. Select the Create a new role option, then select Next.
3. On the IAM Create role page, ensure the Web identity radio button is selected.
4. In the Web identity section:
   • Select api.pulumi.com/oidc under Identity provider.
   • Select the name of your Pulumi organization under Audience. Then select Next.
5. On the Add permissions page, select the permissions that you want to grant to Pulumi Cloud. Then select Next.
6. Provide a name and optional description for the IAM role. Then select Create role.

Review trust policy

Next, select the trust relationships tab, which is where the trust policy of the role is defined.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::123456789012:oidc-provider/api.pulumi.com/oidc"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "api.pulumi.com/oidc:aud": "aws:<pulumi-org-name>"
                },
                "StringLike": {
                    "api.pulumi.com/oidc:sub": "pulumi:environments:org:<pulumi-org-name>:env:*"
                }
            }
        }
    ]
}

This definition allows any Pulumi ESC environment in your organization to assume this role. The sub condition uses a wildcard to permit any environment within your org. You can make the policy more granular by restricting access to a specific environment. For more detailed configuration, see Custom token claim.

Before you log out of the AWS console, make sure to make a note of your role’s ARN value as you will need it in the next step.

Configure ESC for OIDC

To configure OIDC for Pulumi ESC, create a new environment in the Pulumi Cloud console. Make sure that you have the correct organization selected in the left-hand navigation menu. Then:

1. Select the Environments link.

2. Select the Create environment button.

3. Provide a project to create your new environment in and a name for your environment.

4. Select the Create environment button.

5. You will be presented with a split-pane editor. Delete the default placeholder content in the editor and replace it with the following code:

   values:
     aws:
       login:
         fn::open::aws-login:
           oidc:
             duration: 1h
             roleArn: <your-oidc-iam-role-arn>
             sessionName: pulumi-environments-session
     environmentVariables:
       AWS_ACCESS_KEY_ID: ${aws.login.accessKeyId}
       AWS_SECRET_ACCESS_KEY: ${aws.login.secretAccessKey}
       AWS_SESSION_TOKEN: ${aws.login.sessionToken}
   

6. Replace <your-oidc-iam-role-arn> with the value from the previous steps.

7. Click Save.

You can validate that your configuration is working by running the pulumi env open command of the Pulumi CLI:

pulumi env open <your-org>/<your-project>/<your-environment>

Make sure to replace <your-org>, <your-project>, and <your-environment> with the values of your Pulumi organization, project, and environment file respectively. You should see output similar to the following:

{
  "aws": {
    "login": {
      "accessKeyId": "ASIA....",
      "secretAccessKey": "rtBS....",
      "sessionToken": "Fwo...."
    }
  },
  "environmentVariables": {
    "AWS_ACCESS_KEY_ID": "ASIA....",
    "AWS_SECRET_ACCESS_KEY": "rtBS....",
    "AWS_SESSION_TOKEN": "Fwo...."
  }
}

Subject claim customization

You can customize the subject claim in the OIDC token to control which Pulumi environments or users are allowed to assume a given IAM role. This allows for more granular access control than the default organization-level permissions. Use the subjectAttributes property in your login configuration; see Custom token claim for the full list of available attributes and how the subject is composed.

Subject claim example

Consider the following ESC definition for project/development environment opened by user personA:

values:
  aws:
    login:
      fn::open::aws-login:
        oidc:
          ...
          subjectAttributes:
            - currentEnvironment.name
            - pulumi.user.login

The OIDC subject claim for this environment would be pulumi:environments:pulumi.organization.login:contoso:currentEnvironment.name:project/development:pulumi.user.login:personA. The role may only be assumed by project/development environment and user personA within the contoso organization:

"Condition": {
  "StringEquals": {
    "api.pulumi.com/oidc:aud": "aws:contoso",
    "api.pulumi.com/oidc:sub": "pulumi:environments:pulumi.organization.login:contoso:currentEnvironment.name:project/development:pulumi.user.login:personA"
  }
}