1. Docs
  2. Deployments & Workflows
  3. Deployments
  4. OIDC Setup
  5. AWS

Configuring OpenID Connect for AWS with Pulumi Deployments

    There are multiple approaches for supplying cloud credentials to Pulumi Deployments. For guidance on choosing between Deployments OIDC and Pulumi ESC, see Supplying Cloud Credentials to 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.

    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.

    Many Pulumi programs create IAM roles, policies, or instance profiles (e.g., for Lambda, ECS, or EKS), which require IAM permissions. While AdministratorAccess is the simplest policy that covers all services including IAM, it is broader than most workloads need. For better security, consider one of these alternatives:

    • PowerUserAccess + IAMFullAccess — provides broad service access with IAM permissions but excludes AWS Organizations management.
    • Custom least-privilege policy — scoped to only the AWS services and IAM actions your Pulumi program uses (e.g., ec2:*, s3:*, iam:CreateRole, iam:AttachRolePolicy, iam:PassRole).
    • Permissions boundary — use a broader role policy but attach an IAM permissions boundary to cap the privileges of any IAM entities that Pulumi creates, preventing privilege escalation.

    You can also further constrain the assumed role session using the Policy ARNs field in the Pulumi Deployments OIDC configuration.

    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.

    Configure OIDC via the Pulumi console

    In addition to the Pulumi Console, deployment settings including OIDC can be configured for a stack using the pulumiservice.DeploymentSettings resource or via the REST API.
    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.
    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.

    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.