GitHub Actions: OpenID Connect

Benefits of using OIDC #

By updating your workflows to use OIDC tokens, you can adopt the following good security practices:

• No cloud secrets: You won’t need to duplicate your cloud credentials as long-lived GitHub secrets. Instead, you can configure the OIDC trust on your cloud provider, and then update your workflows to request a short-lived access token from the cloud provider through OIDC.
• Authentication and authorization management: You have more granular control over how workflows can use credentials, using your cloud provider’s authentication (authN) and authorization (authZ) tools to control access to cloud resources.
• Rotating credentials: With OIDC, your cloud provider issues a short-lived access token that is only valid for a single job, and then automatically expires.

How OIDC integrates with GitHub Actions #

The following diagram gives an overview of how GitHub’s OIDC provider integrates with your workflows and cloud provider:

1. You establish an OIDC trust relationship in the cloud provider, allowing specific GitHub workflows to request cloud access tokens on behalf of a defined cloud role.
2. Every time your job runs, GitHub’s OIDC provider auto-generates an OIDC token. This token contains multiple claims to establish a security-hardened and verifiable identity about the specific workflow that is trying to authenticate.
3. A step or action in the workflow job can request a token from GitHub’s OIDC provider, which can then be presented to the cloud provider as proof of the workflow’s identity.
4. Once the cloud provider successfully validates the claims presented in the token, it then provides a short-lived cloud access token that is available only for the duration of the job.

Source: https://docs.github.com/en/actions/concepts/security/openid-connect

OIDC in AWS #

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.

Example Get AWS permissions GitHub Action o assume an IAM role.

      - name: Get AWS permissions
        uses: aws-actions/configure-aws-credentials@v1
        with:
          role-to-assume: arn:aws:iam::450226343468:role/GitHubDemo1 # Role ARN
          aws-region: us-east-1 # Location of the S3 Bucket

ℹ️ Note: Refer to below documentation to set up OIDC in AWS:

More Information:

• Configuring OpenID Connect in Amazon Web Services
• Create an OpenID Connect (OIDC) identity provider in IAM

GitHub Actions Workflow to generate OIDC #

name: Terraform AWS GH1 Build - DEV

# NOTE: Fetch AWS Credentials

on:
  workflow_dispatch:
permissions:
  id-token: write
  contents: read

defaults:
  run:
    shell: bash
    working-directory: ./terraform-manifests

jobs:
  iac-aws-gh1-build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Configure AWS Credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::390157243794:role/tf-core-oidcRole
          aws-region: eu-west-2 # NOTE: STS API endpoint that GitHub Actions calls to assume the role is regional. Region must match where OIDC Provider have been deployed (terraform-core/aws-oidc/c5-oidc-provider.tf)

» Sources « #

• OpenID Connect
• Configuring OpenID Connect in Amazon Web Services
• Create an OpenID Connect (OIDC) identity provider in IAM

More On GitHub Actions Security:

• General overview & important concepts: https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions
• More on Secrets: https://docs.github.com/en/actions/security-guides/encrypted-secrets
• Using GITHUB_TOKEN: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
• Advanced - Preventing Fork Pull Requests Attacks: https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
• Security Hardening with OpenID Connect: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect

» Disclaimer « #