How GitHub OIDC Works with AWS

This guide explains how GitHub OpenID Connect (OIDC) integrates with AWS to enable secure authentication for GitHub Actions without permanent credentials. Understanding OIDC is helpful for troubleshooting and extending your GitHub Actions workflows.

Deployment Note

The GitHub OIDC Provider is deployed as part of the Identity layer. This page is a reference explaining how OIDC works—you don't need to deploy anything separately.

GitHub OIDC (OpenID Connect) for AWS refers to the integration between GitHub as an identity provider using OpenID Connect and AWS services. This integration allows users to use their GitHub credentials to authenticate and access AWS resources securely. By configuring GitHub as an OIDC provider in AWS Identity and Access Management (IAM), organizations can establish a federated identity model. This enables GitHub users to sign in to AWS using their GitHub credentials, streamlining access management and eliminating the need for separate AWS-specific usernames and passwords. The integration also provides a centralized way to manage access permissions and enables Single Sign-On (SSO) capabilities, enhancing security and user experience in the AWS environment. Organizations can configure OIDC settings in AWS, including client IDs, client secrets, and the GitHub OIDC discovery URL, to establish a trust relationship between GitHub and AWS. For the most accurate and up-to-date information, it's recommended to check the official documentation of GitHub and AWS.

OpenID Connect

OIDC is short for OpenID Connect and, like SAML, is a way to federate identities. Federating Identities is a fancy way of saying we trust a 3rd party (the OIDC provider) to handle two tasks:

1. Authentication: verify who the user is
2. Authorization: verify what the user has access to (claims)

You can think of this process as similar to arriving at an airport. You present your passport to airport personnel (authentication) so they can identify you along with your boarding pass (authorization claim) indicating you are authorized to pass through security and board a specific flight.

This is similar to how OpenID connect works with DataDog

We share this here only if it helps, as the process is conceptually similar for GitHub and GitHub Actions.

GitHub OIDC and AWS

tip

The primary reason we want to use GitHub OIDC with AWS is so GitHub Actions can assume various AWS Roles without the need to store permanent credentials (e.g. without hardcoding AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY) in GitHub.

Creating IAM Roles for GitHub Actions

Once the GitHub OIDC Provider is deployed (via the Identity layer), you can create IAM roles that GitHub Actions workflows can assume. There are two approaches:

1 Option 1: Configure GitHub OIDC Mixin Role and Policy

Use the mixin to grant GitHub the ability to assume a role for a specific component.

• Add the GitHub OIDC Mixin to any component that needs to generate an IAM Role for GitHub Actions
• Implement a custom IAM Policy with least privilege for the role. See example policies here

2 Option 2: Deploy GitHub OIDC Role Component

Deploy the GitHub OIDC Role component to create a generalized role for GitHub to access several resources in AWS.

3 Configure GitHub Action Workflows

First, give the GitHub Action Workflow the proper permissions

permissions:
  id-token: write # This is required for requesting the JWT
  contents: read  # This is required for actions/checkout

Then, use the official aws-actions/configure-aws-credentials action to automatically obtain a token from the GitHub OIDC provider, exchange that token for AWS temporary credentials and set the proper env vars in your GitHub Action Workflow

- name: Configure AWS credentials
  uses: aws-actions/configure-aws-credentials@v4
  with:
    aws-region: us-east-2
    role-to-assume: arn:aws:iam::111111111111:role/my-github-actions-role
    role-session-name: my-github-actions-role-session

FAQ

Should I use the Mixin or the component to deploy a GitHub OIDC role?

Use the mixin when deploying a role tightly coupled with a specific component. For example, use the mixin with ecr to grant GitHub access to push and pull ECR images.

However, sometimes we need a role with access to many components or resources. In this case, we use the github-oidc-role component to define a generalized role for GitHub to assume. For example, we use the component for the gitops role.