Authenticating GitHub Actions to AWS using IAM Roles

We've all been there: creating AWS access keys for authentication, worrying about keeping them safe, and trying to remember to rotate them periodically.

But do we really need to use long-lived access keys for every situation? For GitHub Actions, the answer is no.

In this article, you'll learn how to authenticate a GitHub Actions workflow to AWS using IAM roles and OpenID Connect (OIDC). This approach lets you eliminate access keys and avoid manually rotating them.

✅Prerequisites:

You need the following:

• An AWS account with sufficient IAM permissions.


• A GitHub repository

🔐Step 1: Create an OpenID Connect Provider in your AWS account

An IAM identity provider (IdP) enables AWS to trust identities that originate outside AWS. In this step, you create an OpenID Connect (OIDC) provider that allows GitHub Actions to request temporary AWS credentials.

1. Go to the IAM Console


2. Click Identity Providers in the left navigation menu


3. Click Add Provider and select OpenID Connect as the provider type


4. For Provider URL, enter token.actions.githubusercontent.com
   


5. For Audience enter: sts.amazonaws.com
   


6. Click Add provider to create the Identity Provider

🧩Step 2: Create an IAM role

The IAM role defines what GitHub Actions can access in your AWS account. You will also scope the role's trust policy so that only a specific GitHub organisation, repository, and branch can assume the role.

1. Select the Identity Provider you just created


2. Click the Assign Role button and choose Create a new role
   


3. For the Trusted entity type, Web Identity is already pre-selected, and the Identity provider field is populated with the IdP you just created


4. In the Audience list, select sts.amazonaws.com
   


5. Fill in the GitHub Organisation, Repository, and Branch according to your needs and click Next
   


6. For the permissions, we will add them after we have created the role, so click Next
   


7. On the Review page, add a role name GitHub-Actions-Role and optionally add a description


8. Click Create role after reviewing the role details

🔑Step 3: Assign Permissions to the role

For this example, the workflow uploads files to Amazon S3, so the role requires S3 permissions.

1. In the dashboard of the newly created role, select Add permissions → Create inline policy
   


2. Change the view from Visual to JSON
   


3. Paste the following policy and click Next
   

{

    "Version": "2012-10-17",

    "Statement": [

        {

            "Effect": "Allow",

            "Action": [

                "s3:PutObject",

                "s3:PutObjectAcl",

                "s3:GetObject"

            ],

            "Resource": "arn:aws:s3:::your-bucket-name/*"

        }

    ]

}

Name the policy S3-permissions and click Create policy.

⚙️Step 4: Create your GitHub Action

In this step, we will create a GitHub Actions workflow that will authenticate to AWS and upload a file to S3.

Create a file in your repository at .github/workflows/s3-upload.yml

name: Upload File to S3



on:

  push:

    branches: [ main ]



env:

  AWS_REGION: us-east-1 #Change to reflect your Region



jobs:

  upload:

    runs-on: ubuntu-latest



    # This allows the actions to get temporary credentials

    permissions:

      id-token: write

      contents: read



    steps:

    - name: Checkout code

      uses: actions/checkout@v4



    - name: Configure AWS credentials

      uses: aws-actions/configure-aws-credentials@v5

      with:

        role-to-assume: arn:aws:iam::YOUR-ACCOUNT-ID:role/YOUR-ROLE-NAME

        aws-region: ${{ env.AWS_REGION }}



    - name: Upload files to S3

      run: |

        aws s3 cp ./your-file s3://your-bucket-name/

Replace the following values:

• YOUR-ACCOUNT-ID with your AWS Account ID


• YOUR-ROLE-NAME with the name of the role you created


• your-file with the file you want to upload


• your-bucket-name with your s3 bucket name

📌Summary

You have now configured GitHub Actions to authenticate to AWS using an IAM role and OIDC, eliminating the need for long-lived access keys.

🛠️Troubleshooting

If the workflow fails, verify the following:

• The IAM role has the required permissions.


• The GitHub organisation, repository, and branch values in the role trust policy are correct.


• The workflow includes the id-token: write permission.