Configuring OpenID Connect in Amazon Web Services

Use OpenID Connect within your workflows to authenticate with Amazon Web Services.

In this article

Note

GitHub-hosted runners are not currently supported on GitHub Enterprise Server. You can see more information about planned future support on the GitHub public roadmap.

Overview

OpenID Connect (OIDC) allows your GitHub Actions workflows to access resources in Amazon Web Services (AWS), without needing to store the AWS credentials as long-lived GitHub secrets.

This guide explains how to configure AWS to trust GitHub's OIDC as a federated identity, and includes a workflow example for the aws-actions/configure-aws-credentials that uses tokens to authenticate to AWS and access resources.

Note

Support for custom claims for OIDC is unavailable in AWS.

Prerequisites

  • To learn the basic concepts of how GitHub uses OpenID Connect (OIDC), and its architecture and benefits, see OpenID Connect.

  • Before proceeding, you must plan your security strategy to ensure that access tokens are only allocated in a predictable way. To control how your cloud provider issues access tokens, you must define at least one condition, so that untrusted repositories can’t request access tokens for your cloud resources. For more information, see OpenID Connect.

  • You must ensure the following OIDC endpoints are accessible by your cloud provider:

    • https://HOSTNAME/_services/token/.well-known/openid-configuration
    • https://HOSTNAME/_services/token/.well-known/jwks

    Note

    You can restrict access to the OIDC endpoints by allowing only AWS IP address ranges.

    Note

    GitHub does not natively support AWS session tags.

Adding the identity provider to AWS

To add the GitHub OIDC provider to IAM, see the AWS documentation.

  • For the provider URL: Use https://HOSTNAME/_services/token
  • For the "Audience": Use sts.amazonaws.com if you are using the official action.

Configuring the role and trust policy

To configure the role and trust in IAM, see the AWS documentation Configure AWS Credentials for GitHub Actions and Configuring a role for GitHub OIDC identity provider.

Note

AWS Identity and Access Management (IAM) recommends that users evaluate the IAM condition key, token.actions.githubusercontent.com:sub, in the trust policy of any role that trusts GitHub’s OIDC identity provider (IdP). Evaluating this condition key in the role trust policy limits which GitHub actions are able to assume the role.

Edit the trust policy, adding the sub field to the validation conditions. For example:

JSON
"Condition": {
  "StringEquals": {
    "HOSTNAME/_services/token:aud": "sts.amazonaws.com",
    "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch"
  }
}

If you use a workflow with an environment, the sub field must reference the environment name: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME. For more information, see OpenID Connect reference.

Note

When environments are used in workflows or in OIDC policies, we recommend adding protection rules to the environment for additional security. For example, you can configure deployment rules on an environment to restrict which branches and tags can deploy to the environment or access environment secrets. For more information, see Managing environments for deployment.

JSON
"Condition": {
  "StringEquals": {
    "HOSTNAME/_services/token:aud": "sts.amazonaws.com",
    "HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:environment:prod"
  }
}

In the following example, StringLike is used with a wildcard operator (*) to allow any branch, pull request merge branch, or environment from the octo-org/octo-repo organization and repository to assume a role in AWS.

JSON
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::123456123456:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:*"
                },
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}

Updating your GitHub Actions workflow

To update your workflows for OIDC, you will need to make two changes to your YAML:

  1. Add permissions settings for the token.
  2. Use the aws-actions/configure-aws-credentials action to exchange the OIDC token (JWT) for a cloud access token.

Adding permissions settings

The job or workflow run requires a permissions setting with id-token: write to allow GitHub's OIDC provider to create a JSON Web Token for every run.

Note

Setting id-token: write in the workflow’s permissions does not give the workflow permission to modify or write to any resources. Instead, it only allows the workflow to request (fetch) and use (set) an OIDC token for an action or step. This token is then used to authenticate with external services using a short-lived access token.

For detailed information on required permissions, configuration examples, and advanced scenarios, see OpenID Connect reference.

Requesting the access token

The aws-actions/configure-aws-credentials action receives a JWT from the GitHub OIDC provider, and then requests an access token from AWS. For more information, see the AWS documentation.

  • BUCKET-NAME: Replace this with the name of your S3 bucket.
  • AWS-REGION: Replace this with the name of your AWS region.
  • ROLE-TO-ASSUME: Replace this with your AWS role. For example, arn:aws:iam::1234567890:role/example-role
YAML
# Sample workflow to access AWS resources when workflow is tied to branch
# The workflow Creates static website using aws s3
name: AWS example workflow
on:
  push
env:
  BUCKET_NAME : "BUCKET-NAME"
  AWS_REGION : "AWS-REGION"
# permission can be added at job level or workflow level
permissions:
  id-token: write   # This is required for requesting the JWT
  contents: read    # This is required for actions/checkout
jobs:
  S3PackageUpload:
    runs-on: ubuntu-latest
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v4
      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502
        with:
          role-to-assume: ROLE-TO-ASSUME
          role-session-name: samplerolesession
          aws-region: ${{ env.AWS_REGION }}
      # Upload a file to AWS s3
      - name: Copy index.html to s3
        run: |
          aws s3 cp ./index.html s3://${{ env.BUCKET_NAME }}/

Further reading