Repository files navigation

Configure your AWS credentials and region environment variables for use in otherGitHub Actions. This action implements the AWS SDK credential resolution chainand exports environment variables for your other Actions to use. Environmentvariable exports are detected by both the AWS SDKs and the AWS CLI for AWS APIcalls.

If you use OIDC, you may need to update your identity provider

There are nowtwo possible intermediary certificates for the Actions SSL certificate. Previously, the certificate with the thumbprint6938fd4d98bab03faadb97b34396831e3780aea1 was guaranteed to return. Now, the certificate with the thumbprint1c58a3a8518e8759bf075b76b750d4f2df264fcd can also be returned, so you will need toupdate your identity provider with this additional new thumbprint.

• Usage
• Credentials
• Assuming a Role
  • Session tagging
  • Sample IAM Role Permissions
• Self-Hosted Runners
  • Proxy Configuration
• License Summary
• Security Disclosures

We support four methods for fetching credentials from AWS, but we recommend thatyou use GitHub's OIDC provider in conjunction with a configured AWS IAMIdentity Provider endpoint.

To do that, you would add the following step to your workflow:

    -name:Configure AWS Credentialsuses:aws-actions/configure-aws-credentials@v2with:role-to-assume:arn:aws:iam::123456789100:role/my-github-actions-roleaws-region:us-east-2

This will cause the action to perform anAssumeRoleWithWebIdentity call andreturn temporary security credentials for use by other actions. In order forthis to work, you'll need to preconfigure the IAM IdP in your AWS account(seeAssuming a Role for details).

You can use this action with the AWS CLI available inGitHub's hosted virtual environments or run this action multiple timesto use different AWS accounts, regions, or IAM roles in the same GitHub Actionsworkflow. As an example, here is a complete workflow file that uploads artifactsto Amazon S3.

jobs:deploy:name:Upload to Amazon S3runs-on:ubuntu-latest# These permissions are needed to interact with GitHub's OIDC Token endpoint.permissions:id-token:writecontents:readsteps:    -name:Checkoutuses:actions/checkout@v3    -name:Configure AWS credentials from Test accountuses:aws-actions/configure-aws-credentials@v2with:role-to-assume:arn:aws:iam::111111111111:role/my-github-actions-role-testaws-region:us-east-1    -name:Copy files to the test website with the AWS CLIrun:|        aws s3 sync . s3://my-s3-test-website-bucket    -name:Configure AWS credentials from Production accountuses:aws-actions/configure-aws-credentials@v2with:role-to-assume:arn:aws:iam::222222222222:role/my-github-actions-role-prodaws-region:us-west-2    -name:Copy files to the production website with the AWS CLIrun:|        aws s3 sync . s3://my-s3-prod-website-bucket

Seeaction.yml for the full documentation for this action's inputsand outputs.

We recommend followingAmazon IAM best practicesfor the AWS credentials used in GitHub Actions workflows, including:

• Do not store credentials in your repository's code.
• Grant least privilege to the credentials used in GitHub Actionsworkflows. Grant only the permissions required to perform the actions in yourGitHub Actions workflows.
• Monitor the activity of the credentials used in GitHub Actions workflows.

There are four different supported ways to retrieve credentials. We recommendusingGitHub's OIDC providerto get short-lived credentials needed for your actions. Specifyingrole-to-assumewithout providing anaws-access-key-id or aweb-identity-token-file, or settingrole-chaining, will signal to the action that you wish to use theOIDC provider. Ifrole-chaining istrue, existing credentials in the environment will be used to assumerole-to-assume.

The following table describes which identity is used based on which values are supplied to the Action:

The default session duration is1 hour when using the OIDC provider todirectly assume an IAM Role or when anaws-session-token is directly provided.The default session duration is6 hours when using an IAM User to assume anIAM Role (by providing anaws-access-key-id,aws-secret-access-key, and arole-to-assume) .

If you would like to adjust this you can pass a duration torole-duration-seconds, but the duration cannot exceed the maximum that was defined when the IAM Role was created.The default session name is GitHubActions, and you can modify it by specifying the desired name inrole-session-name.The default audience issts.amazonaws.com which you can replace by specifying the desired audience name inaudience.

    -name:Configure AWS Credentialsuses:aws-actions/configure-aws-credentials@v2with:aws-region:us-east-2role-to-assume:arn:aws:iam::123456789100:role/my-github-actions-rolerole-session-name:MySessionName

In this example, the Action will load the OIDC token from the GitHub-provided environment variable and use it to assume the rolearn:aws:iam::123456789100:role/my-github-actions-role with the session nameMySessionName.

    -name:Configure AWS Credentialsuses:aws-actions/configure-aws-credentials@v2with:aws-region:us-east-2role-to-assume:arn:aws:iam::123456789100:role/my-github-actions-rolerole-session-name:MySessionName    -name:Configure other AWS Credentialsuses:aws-actions/configure-aws-credentials@v2with:aws-region:us-east-2role-to-assume:arn:aws:iam::987654321000:role/my-second-rolerole-session-name:MySessionNamerole-chaining:true

In this two-step example, the first step will use OIDC to assume the rolearn:aws:iam::123456789100:role/my-github-actions-role just as in the prior example. Following that, a second step will use this role to assume a different role,arn:aws:iam::987654321000:role/my-second-role.

    -name:Configure AWS Credentialsuses:aws-actions/configure-aws-credentials@v2with:aws-access-key-id:${{ secrets.AWS_ACCESS_KEY_ID }}aws-secret-access-key:${{ secrets.AWS_SECRET_ACCESS_KEY }}aws-region:us-east-2role-to-assume:${{ secrets.AWS_ROLE_TO_ASSUME }}role-external-id:${{ secrets.AWS_ROLE_EXTERNAL_ID }}role-duration-seconds:1200role-session-name:MySessionName

In this example, the secretAWS_ROLE_TO_ASSUME contains a string likearn:aws:iam::123456789100:role/my-github-actions-role. To assume a role in the same account as the static credentials, you can simply specify the role name, likerole-to-assume: my-github-actions-role.

    -name:Configure AWS Credentials for Beta Customersuses:aws-actions/configure-aws-credentials@v2with:audience:beta-customersaws-region:us-east-3role-to-assume:arn:aws:iam::123456789100:role/my-github-actions-rolerole-session-name:MySessionName

In this example, the audience has been changed from the default to use a different audience namebeta-customers. This can help ensure that the role can only affect those AWS accounts whose GitHub OIDC providers have explicitly opted in to thebeta-customers label.

Changing the default audience may be necessary when using non-defaultAWS partitions.

    -name:Configure AWS Credentialsuses:aws-actions/configure-aws-credentials@v2with:aws-region:us-east-2role-to-assume:arn:aws:iam::123456789100:role/my-github-actions-rolerole-session-name:MySessionNamemask-aws-account-id:false

In this example, account ID masking has been disabled. By default, the AWSaccount ID will be obscured in the action's output. This may be helpful whendebugging action failures.

If you choose to use GitHub's OIDC provider, you must first set up federationwith the provider in as an IAM IdP. The GitHub OIDC provider only needs to becreated once per account (i.e. multiple IAM Roles that can be assumed by theGitHub's OIDC can share a single OIDC Provider).

This CloudFormation template will configure the IdP for you.

Parameters:GitHubOrg:Description:Name of GitHub organization/user (case sensitive)Type:StringRepositoryName:Description:Name of GitHub repository (case sensitive)Type:StringOIDCProviderArn:Description:Arn for the GitHub OIDC Provider.Default:""Type:StringOIDCAudience:Description:Audience supplied to configure-aws-credentials.Default:"sts.amazonaws.com"Type:StringConditions:CreateOIDCProvider:!Equals    -!RefOIDCProviderArn    -""Resources:Role:Type:AWS::IAM::RoleProperties:AssumeRolePolicyDocument:Statement:          -Effect:AllowAction:sts:AssumeRoleWithWebIdentityPrincipal:Federated:!If                -CreateOIDCProvider                -!RefGithubOidc                -!RefOIDCProviderArnCondition:StringEquals:token.actions.githubusercontent.com:aud:!Ref OIDCAudienceStringLike:token.actions.githubusercontent.com:sub:!Sub repo:${GitHubOrg}/${RepositoryName}:*GithubOidc:Type:AWS::IAM::OIDCProviderCondition:CreateOIDCProviderProperties:Url:https://token.actions.githubusercontent.comClientIdList:         -sts.amazonaws.comThumbprintList:        -6938fd4d98bab03faadb97b34396831e3780aea1        -1c58a3a8518e8759bf075b76b750d4f2df264fcdOutputs:Role:Value:!GetAtt Role.Arn

To align with the Amazon IAM best practice ofgranting least privilege, the assume role policy document should contain aCondition that specifies a subject allowed to assume the role. Without a subjectcondition, any GitHub user or repository could potentially assume the role. Thesubject can be scoped to a GitHub organization and repository as shown in theCloudFormation template. Additional claim conditions can be added for higherspecificity as explained in theGitHub documentation.Due to implementation details, not every OIDC claim is presently supported byIAM.

For further information on OIDC and GitHub Actions, please see:

• AWS docs: Creating OpenID Connect (OIDC) identity providers
• AWS docs: IAM JSON policy elements: Condition
• GitHub docs: About security hardening with OpenID Connect
• GitHub docs: Configuring OpenID Connect in Amazon Web Services
• GitHub changelog: GitHub Actions: Secure cloud deployments with OpenID Connect

The session will have the name "GitHubActions" and be tagged with the followingtags: (GITHUB_ environment variable definitions can befound here)

Note: all tag values must conform tothe requirements.Particularly,GITHUB_WORKFLOW will be truncated if it's too long. IfGITHUB_ACTOR orGITHUB_WORKFLOW contain invalid characters, the characterswill be replaced with an '*'.

The action will use session tagging by default during role assumption.Note that for WebIdentity role assumption, the session tags have to be includedin the encoded WebIdentity token. This means that Tags can only be supplied bythe OIDC provider and not set during the AssumeRoleWithWebIdentity API callwithin the Action. You can skip this session tagging by providingrole-skip-session-tagging as true in the action's inputs:

uses:aws-actions/configure-aws-credentials@v2with:role-skip-session-tagging:true

An IAM policy in stringified JSON format that you want to use as an inline session policy.Depending on preferences, the JSON could be written on a single line like this:

uses:aws-actions/configure-aws-credentials@v2with:inline-session-policy:'{"Version":"2012-10-17","Statement":[{"Sid":"Stmt1","Effect":"Allow","Action":"s3:List*","Resource":"*"}]}'

Or we can have a nicely formatted JSON as well:

uses:aws-actions/configure-aws-credentials@v2with:inline-session-policy:>-          {           "Version": "2012-10-17",           "Statement": [            {             "Sid":"Stmt1",             "Effect":"Allow",             "Action":"s3:List*",             "Resource":"*"            }           ]          }

The Amazon Resource Names (ARNs) of the IAM managed policies that you want to use as managed session policies.The policies must exist in the same account as the role. You can pass a single managed policy like this:

uses:aws-actions/configure-aws-credentials@v2with:managed-session-policies:arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess

And we can pass multiple managed policies likes this:

uses:aws-actions/configure-aws-credentials@v2with:managed-session-policies:|          arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess          arn:aws:iam::aws:policy/AmazonS3OutpostsReadOnlyAccess

If you run your GitHub Actions in aself-hosted runner that already has access to AWS credentials, such asan EC2 instance, then you do not need to provide IAM user access key credentialsto this action. We will use the standard AWS JavaScript SDK credentialresolution methods to find your credentials, so if the AWS JS SDK canauthenticate on your runner, this Action will as well.

If no access key credentials are given in the action inputs, this action willuse credentials from the runner environment using thedefault methods for the AWS SDK for Javascript.

You can use this action to simply configure the region and account ID in theenvironment, and then use the runner's credentials for all AWS API calls made byyour Actions workflow:

uses:aws-actions/configure-aws-credentials@v2with:aws-region:us-east-2

In this case, your runner's credentials must have permissions to call any AWSAPIs called by your Actions workflow.

Or, you can use this action to assume a role, and then use the role credentialsfor all AWS API calls made by your Actions workflow:

uses:aws-actions/configure-aws-credentials@v2with:aws-region:us-east-2role-to-assume:my-github-actions-role

In this case, your runner's credentials must have permissions to assume therole.

You can also assume a role using a web identity token file, such as if usingAmazon EKS IRSA. Pods running in EKSworker nodes that do not run as root can use this file to assume a role with aweb identity.

If you run in self-hosted environments and in secured environment where you needuse a specific proxy you can set it in the action manually.

Additionally this action will always consider already configured proxy in theenvironment.

Manually configured proxy:

uses:aws-actions/configure-aws-credentials@v2with:aws-region:us-east-2role-to-assume:my-github-actions-rolehttp-proxy:"http://companydomain.com:3128"

Proxy configured in the environment variable:

# Your environment configurationHTTP_PROXY="http://companydomain.com:3128"

The action will read the underlying proxy configuration from the environment andyou don't need to configure it in the action.

This workflow doesnot install theAWS CLIinto your environment. Self-hosted runners that intend to run this action priorto executingaws commands need to have the AWS CLIinstalledif it's not already present.MostGitHub hosted runner environmentsshould include the AWS CLI by default.

This code is made available under the MIT license.

If you would like to report a potential security issue in this project, please do not create a GitHub issue. Instead, please follow the instructionshere oremail AWS security directly.