Configure AWS Credentials (aws-actions/configure-aws-credentials)

Configure AWS Credentials

https://github.com/aws-actions/configure-aws-credentials
Admin
A GitHub Action that authenticates to AWS in GitHub Actions workflows, supporting various methods...

Tokens:9,129
Snippets:96
Trust Score:8.3
Update:3 weeks ago
Show doc for...
Context Summary (auto-generated)
Raw
# Configure AWS Credentials for GitHub Actions

The `configure-aws-credentials` GitHub Action enables secure AWS authentication within GitHub Actions workflows. It supports multiple authentication methods including GitHub OIDC (recommended), static IAM credentials, web identity tokens, and role chaining. The action configures AWS credentials as environment variables or named AWS profiles, allowing subsequent workflow steps to interact with AWS services seamlessly.

The action integrates with AWS Security Token Service (STS) to assume IAM roles with temporary credentials, supporting session policies, session tagging, and automatic credential rotation. It handles proxy configurations, credential validation, retry logic with exponential backoff, and automatic cleanup of sensitive environment variables when jobs complete. Version 6.1.0 targets Node.js 24 runtime and uses the AWS SDK v3.

## GitHub OIDC Authentication (Recommended)

Authenticate using GitHub's built-in OIDC provider to assume an IAM role without storing long-lived credentials. This method provides short-lived, automatically rotated credentials and is the most secure approach.

```yaml
name: Deploy to AWS
on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
          aws-region: us-east-1
          role-session-name: GitHubActionsSession
          role-duration-seconds: 3600

      - name: Verify credentials
        run: aws sts get-caller-identity
        # Output: Account: 123456789012, Arn: arn:aws:sts::123456789012:assumed-role/GitHubActionsRole/GitHubActionsSession
```

## Static IAM Credentials Authentication

Use IAM user access keys stored in GitHub Secrets to authenticate directly or to assume a role. This method requires storing long-lived credentials but may be necessary in some environments.

```yaml
name: Deploy with IAM Credentials
on: workflow_dispatch

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-west-2
          role-to-assume: arn:aws:iam::123456789012:role/DeployRole
          role-external-id: ${{ secrets.AWS_ROLE_EXTERNAL_ID }}
          role-duration-seconds: 1200

      - name: Deploy application
        run: |
          aws s3 sync ./dist s3://my-bucket/
          aws cloudformation deploy --template-file template.yml --stack-name my-stack
```

## Role Chaining Authentication

Use credentials from a previous authentication step or existing environment to assume a different role. This is useful for cross-account access or progressive privilege escalation.

```yaml
name: Cross-Account Deployment
on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Configure AWS Credentials (Account A)
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: arn:aws:iam::111111111111:role/GitHubActionsRole
          aws-region: us-east-1

      - name: Assume role in Account B
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: arn:aws:iam::222222222222:role/CrossAccountRole
          aws-region: us-east-1
          role-chaining: true
          role-skip-session-tagging: true

      - name: Access resources in Account B
        run: aws s3 ls s3://account-b-bucket/
```

## Named AWS Profiles Configuration

Write credentials to AWS profile files instead of environment variables. This enables configuring multiple profiles for multi-account workflows or when tools require profile-based authentication.

```yaml
name: Multi-Account Operations
on: workflow_dispatch

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Configure Dev Profile
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: arn:aws:iam::111111111111:role/DevRole
          aws-region: us-east-1
          aws-profile: dev

      - name: Configure Prod Profile
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: arn:aws:iam::222222222222:role/ProdRole
          aws-region: us-west-2
          aws-profile: prod

      - name: Deploy to both environments
        run: |
          # Deploy to dev
          aws sts get-caller-identity --profile dev
          cdk deploy --profile dev

          # Deploy to prod
          aws sts get-caller-identity --profile prod
          cdk deploy --profile prod
```

## Session Policies for Least Privilege

Restrict assumed role permissions using inline or managed session policies. This applies additional constraints beyond what the IAM role allows.

```yaml
name: Restricted S3 Access
on: workflow_dispatch

permissions:
  id-token: write
  contents: read

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - name: Configure AWS Credentials with Session Policy
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: arn:aws:iam::123456789012:role/BackupRole
          aws-region: us-east-1
          inline-session-policy: >-
            {
              "Version": "2012-10-17",
              "Statement": [
                {
                  "Sid": "AllowS3ListOnly",
                  "Effect": "Allow",
                  "Action": ["s3:ListBucket", "s3:GetObject"],
                  "Resource": [
                    "arn:aws:s3:::backup-bucket",
                    "arn:aws:s3:::backup-bucket/*"
                  ]
                }
              ]
            }
          managed-session-policies: |
            arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess

      - name: Perform backup
        run: aws s3 sync s3://backup-bucket/ ./local-backup/
```

## Web Identity Token File Authentication

Authenticate using a web identity token from an external identity provider (e.g., within Amazon EKS pods). The token is read from a file on the runner.

```yaml
name: EKS Pod Authentication
on: workflow_dispatch

jobs:
  process:
    runs-on: self-hosted
    steps:
      - name: Configure AWS Credentials from Token File
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: arn:aws:iam::123456789012:role/EKSPodRole
          aws-region: us-east-1
          web-identity-token-file: /var/run/secrets/eks.amazonaws.com/serviceaccount/token
          role-session-name: EKSPodSession

      - name: Access AWS services
        run: aws s3 ls
```

## Credentials Output and Retrieval

Export credentials as step outputs for use in subsequent steps that require explicit credential passing.

```yaml
name: Pass Credentials to Docker
on: workflow_dispatch

permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Configure AWS Credentials
        id: aws-creds
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: arn:aws:iam::123456789012:role/ECRPushRole
          aws-region: us-east-1
          output-credentials: true

      - name: Build and push to ECR
        run: |
          echo "Account ID: ${{ steps.aws-creds.outputs.aws-account-id }}"
          echo "Session expires: ${{ steps.aws-creds.outputs.aws-expiration }}"

          # Use credentials explicitly
          docker build -t my-app .
          aws ecr get-login-password | docker login --username AWS --password-stdin \
            ${{ steps.aws-creds.outputs.aws-account-id }}.dkr.ecr.us-east-1.amazonaws.com
```

## HTTP Proxy Configuration

Route AWS API calls through an HTTP proxy for environments with restricted network access.

```yaml
name: Deploy via Proxy
on: workflow_dispatch

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: self-hosted
    steps:
      - name: Configure AWS Credentials with Proxy
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: arn:aws:iam::123456789012:role/DeployRole
          aws-region: us-east-1
          http-proxy: http://proxy.company.com:3128
          no-proxy: 169.254.169.254,localhost

      - name: Deploy through proxy
        run: aws cloudformation deploy --template-file template.yml --stack-name app
```

## Retry and Special Characters Handling

Configure retry behavior for transient failures and handle environments that cannot process special characters in secret keys.

```yaml
name: Resilient Deployment
on: workflow_dispatch

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Configure AWS Credentials with Retries
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: arn:aws:iam::123456789012:role/DeployRole
          aws-region: us-east-1
          retry-max-attempts: 5
          special-characters-workaround: true
          action-timeout-s: 120

      - name: Deploy application
        run: ./deploy.sh
```

## Account ID Validation

Validate that credentials belong to expected AWS accounts to prevent accidental deployments to wrong accounts.

```yaml
name: Validated Deployment
on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: arn:aws:iam::123456789012:role/ProdRole
          aws-region: us-east-1
          allowed-account-ids: 123456789012,234567890123
          mask-aws-account-id: true

      - name: Deploy to production
        run: |
          # Fails if credentials are for unexpected account
          aws cloudformation deploy --template-file prod.yml --stack-name prod-app
```

## AWS IAM OIDC Provider Setup (CloudFormation)

Create the required IAM OIDC identity provider and role using CloudFormation before using OIDC authentication in workflows.

```yaml
# github-actions-oidc-federation.yml
AWSTemplateFormatVersion: "2010-09-09"
Description: GitHub Actions OIDC Provider and Role

Parameters:
  GitHubOrganization:
    Type: String
    Description: GitHub organization or username (case sensitive)
  RepositoryName:
    Type: String
    Default: "*"
    Description: Repository name (* for all repos)
  BranchName:
    Type: String
    Default: "*"
    Description: Branch name (* for all branches)
  RoleName:
    Type: String
    Description: Name for the IAM role

Resources:
  GitHubOIDCProvider:
    Type: AWS::IAM::OIDCProvider
    Properties:
      Url: https://token.actions.githubusercontent.com
      ClientIdList:
        - sts.amazonaws.com
      ThumbprintList:
        - 6938fd4d98bab03faadb97b34396831e3780aea1

  GitHubActionsRole:
    Type: AWS::IAM::Role
    Properties:
      RoleName: !Ref RoleName
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Action: sts:AssumeRoleWithWebIdentity
            Principal:
              Federated: !Ref GitHubOIDCProvider
            Condition:
              StringLike:
                token.actions.githubusercontent.com:sub: !Sub repo:${GitHubOrganization}/${RepositoryName}:ref:refs/heads/${BranchName}
              StringEquals:
                token.actions.githubusercontent.com:aud: sts.amazonaws.com
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/ReadOnlyAccess

Outputs:
  RoleArn:
    Value: !GetAtt GitHubActionsRole.Arn
    Description: ARN of the GitHub Actions role
```

```bash
# Deploy the CloudFormation stack
aws cloudformation deploy \
  --template-file github-actions-oidc-federation.yml \
  --stack-name github-actions-oidc \
  --parameter-overrides \
    GitHubOrganization=my-org \
    RepositoryName=my-repo \
    BranchName=main \
    RoleName=GitHubActionsRole \
  --capabilities CAPABILITY_NAMED_IAM

# Get the role ARN for use in workflows
aws cloudformation describe-stacks \
  --stack-name github-actions-oidc \
  --query 'Stacks[0].Outputs[?OutputKey==`RoleArn`].OutputValue' \
  --output text
```

## Cleanup and Environment Variable Control

Control credential cleanup behavior and environment variable export settings.

```yaml
name: Custom Credential Handling
on: workflow_dispatch

permissions:
  id-token: write
  contents: read

jobs:
  multi-step:
    runs-on: ubuntu-latest
    steps:
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: arn:aws:iam::123456789012:role/MyRole
          aws-region: us-east-1
          unset-current-credentials: true
          output-env-credentials: true
        env:
          AWS_SKIP_CLEANUP_STEP: 'false'

      - name: Use credentials
        run: aws sts get-caller-identity

      - name: Reconfigure with different role
        uses: aws-actions/configure-aws-credentials@v6.1.0
        with:
          role-to-assume: arn:aws:iam::123456789012:role/OtherRole
          aws-region: us-west-2
          use-existing-credentials: false
          unset-current-credentials: true

      - name: Use new credentials
        run: aws sts get-caller-identity
```

## Summary

The `configure-aws-credentials` action provides comprehensive AWS authentication for GitHub Actions workflows across diverse security requirements and deployment scenarios. The recommended approach uses GitHub OIDC for keyless authentication, eliminating the need to store long-lived AWS credentials as repository secrets. For environments requiring static credentials or complex role assumption chains, the action supports IAM user access keys, web identity token files, and role chaining with configurable session policies.

Integration patterns typically involve setting up an IAM OIDC identity provider in AWS (done once per account), creating IAM roles with appropriate trust policies scoped to specific repositories and branches, and then referencing those roles in workflow files. The action handles credential export as environment variables or named profiles, supports multi-account deployments through role chaining or multiple profile configurations, and provides built-in security features including automatic credential masking in logs, session tagging for audit trails, and cleanup of sensitive environment variables when jobs complete.