Configuring OpenID Connect for AWS with Pulumi Deployments

This document outlines the steps required to configure Pulumi Deployments 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 Pulumi Cloud.

Configuring OIDC for AWS involves two sides:

1. AWS — register Pulumi Cloud as an OIDC identity provider and create an IAM role that trusts it. You can do this in the AWS console or programmatically.
2. Pulumi Deployments — enable the AWS OIDC integration for your stack so that each deployment exchanges its OIDC token for credentials from that role. You can do this in the Pulumi Cloud console or programmatically with the Pulumi Service provider.

Configure AWS

Using the AWS console

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, click 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, enter the name of your Pulumi organization. Then select Add provider.

Configure the IAM role and trust policy

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 your Pulumi deployments. Then select Next.
6. Provide a name and optional description for the IAM role. Then select Create role.

Make a note of the IAM role’s ARN; it will be necessary to enable OIDC for your deployment.

Restricting role assumption to Pulumi Cloud scopes

The following restricts to any deployment in your organization:

"Condition": {
  "StringEquals": {
    "api.pulumi.com/oidc:aud": "<your-org-name>"
  },
  "StringLike": {
    "api.pulumi.com/oidc:sub": "pulumi:deploy:org:<your-org-name>:*"
  }
}

The following restricts to any stack within a specific project:

"Condition": {
  "StringEquals": {
    "api.pulumi.com/oidc:aud": "<your-org-name>"
  },
  "StringLike": {
    "api.pulumi.com/oidc:sub": "pulumi:deploy:org:<your-org-name>:project:<your-project-name>:*"
  }
}

The subject claim also includes the stack name and operation, so you can restrict further. See the full subject format and custom claims for details.

Using infrastructure as code

You can register the identity provider and create the IAM role with a Pulumi program instead of the console. The following example uses TypeScript and the AWS provider; the same resources are available in every Pulumi language.

import * as aws from "@pulumi/aws";
import * as pulumi from "@pulumi/pulumi";

const org = "<your-org-name>";

// Register Pulumi Cloud as an OIDC identity provider. The audience (clientIdLists)
// is your Pulumi organization name.
const provider = new aws.iam.OpenIdConnectProvider("pulumi-deployments-oidc", {
    url: "https://api.pulumi.com/oidc",
    clientIdLists: [org],
});

// Create the IAM role that deployments will assume, trusting the provider above.
const role = new aws.iam.Role("pulumi-deployments-oidc", {
    assumeRolePolicy: pulumi.jsonStringify({
        Version: "2012-10-17",
        Statement: [{
            Effect: "Allow",
            Principal: { Federated: provider.arn },
            Action: "sts:AssumeRoleWithWebIdentity",
            Condition: {
                StringEquals: { "api.pulumi.com/oidc:aud": org },
                StringLike: { "api.pulumi.com/oidc:sub": `pulumi:deploy:org:${org}:*` },
            },
        }],
    }),
});

// Attach the permissions your deployments need. Scope this down for production.
new aws.iam.RolePolicyAttachment("pulumi-deployments-oidc", {
    role: role.name,
    policyArn: "arn:aws:iam::aws:policy/AdministratorAccess",
});

export const roleArn = role.arn;

aws iam add-client-id-to-open-id-connect-provider \
  --open-id-connect-provider-arn arn:aws:iam::<account-id>:oidc-provider/api.pulumi.com/oidc \
  --client-id <your-org-name>

Configure Pulumi Deployments

Using the Pulumi Cloud console

1. Navigate to your stack in the Pulumi Console.
2. Open the stack’s “Settings” tab.
3. Choose the “Deploy” panel.
4. Under the “OpenID Connect” header, toggle “Enable AWS Integration”.
5. Enter the ARN of the IAM role created above in the “Role ARN” field.
6. Enter a name for the assumed role session in the “Session Name” field. See Session name for the supported template variables.
7. If you would like to use additional policies to further constrain the session’s capabilities, enter the policies’ ARNs separated by commas in the “Policy ARNs” field.
8. If you would like to constrain the duration of the assumed role session, enter a duration in the form “XhYmZs” in the “Session Duration” field.
9. Select the “Save deployment configuration” button.

Using infrastructure as code

You can manage the same deployment settings in source control with the pulumiservice.DeploymentSettings resource (the OIDC configuration is set under operationContext.oidc.aws). Deployment settings can also be configured via the REST API.

import * as pulumiservice from "@pulumi/pulumiservice";

new pulumiservice.DeploymentSettings("deployment-settings", {
    organization: "<your-org-name>",
    project: "<your-project-name>",
    stack: "<your-stack-name>",
    operationContext: {
        oidc: {
            aws: {
                roleARN: "<your-oidc-iam-role-arn>",
                sessionName: "pulumi-deployments",
                // Optional: further constrain the session.
                // policyARNs: ["arn:aws:iam::aws:policy/ReadOnlyAccess"],
                // duration: "1h",
            },
        },
    },
});

With this configuration, each deployment of this stack will attempt to exchange the deployment’s OIDC token for AWS credentials using the specified IAM role prior to running any pre-commands or Pulumi operations. The fetched credentials are published in the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN environment variables. The raw OIDC token is also available for advanced scenarios in the PULUMI_OIDC_TOKEN environment variable and the /mnt/pulumi/pulumi.oidc file.

Session name

The session name becomes the RoleSessionName on the AWS STS AssumeRoleWithWebIdentity call and surfaces in every subsequent CloudTrail event as the last segment of the assumed-role principal ARN, so a templated session name makes each API call traceable to a specific Pulumi deployment.

Template variables

The session name supports ${var} placeholders that Pulumi substitutes when the deployment runs:

1. ${organization.name}: Pulumi organization name.
2. ${project.name}: Pulumi project name.
3. ${stack.name}: Pulumi stack name.
4. ${deployment.operation}: operation type (for example, update, preview, or destroy).
5. ${deployment.version}: deployment version number.
6. ${deployment.id}: deployment UUID.

A literal value with no ${...} placeholders is passed through unchanged.

Length and truncation

AWS caps RoleSessionName at 64 characters. If a rendered template would exceed that limit, Pulumi trims the truncatable name variables (${organization.name}, ${project.name}, ${stack.name}) from the end until the result fits. The protected variables (${deployment.operation}, ${deployment.version}, ${deployment.id}) are never trimmed, so each deployment remains identifiable.

For example, given the template:

${organization.name}-${project.name}-${stack.name}-${deployment.id}

with organization.name = "pulumi-local", project.name = "test-nocode-rtct-3", stack.name = "dev", and deployment.id = "806bf21f-444f-4825-a80c-afd12cd2526a", the full-length result would be 72 characters. Pulumi caps the three name variables to fit the budget while preserving the deployment UUID:

pulumi-loca-test-nocode-dev-806bf21f-444f-4825-a80c-afd12cd2526a

The result is exactly 64 characters: ${organization.name} and ${project.name} are each capped to 11 characters, ${stack.name} is 3 characters and fits as-is, and the deployment UUID is preserved in full.