OIDC Authentication in GitHub Actions

1. Introduction

OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol that allows clients to verify the identity of end-users based on the authentication performed by an Authorization Server. GitHub Actions can utilize OIDC to authenticate and authorize workflows securely without the need for managing credentials.

2. Key Concepts

What is OIDC?

OIDC allows applications to authenticate users and obtain their profile information securely. It uses JSON Web Tokens (JWT) to provide a standard way to represent claims securely between parties.

OIDC in GitHub Actions

GitHub Actions supports OIDC to allow secure access to cloud providers like AWS, Azure, and Google Cloud without storing access tokens in your repository.

3. Setup

3.1 Enable OIDC in Your Cloud Provider

Configure your cloud provider to trust GitHub as an identity provider.
Set up an OIDC application in your cloud provider's console.
Record the client ID and issuer URL provided by your cloud provider.

3.2 Create a Workflow in GitHub Actions

Create a new GitHub Actions workflow file in your repository:

name: OIDC Authentication Example

on: [push]

jobs:
  authenticate:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v2

      - name: Authenticate to AWS
        id: aws-auth
        uses: aws-actions/configure-aws-credentials@v1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1
          role-to-assume: arn:aws:iam::123456789012:role/MyGitHubActionsRole
          role-session-name: GitHubActionsSession
          oidc-provider-url: https://token.actions.githubusercontent.com
          audience: sts.amazonaws.com

4. Workflow Example

Here's how to implement OIDC authentication within a GitHub Actions workflow to deploy to AWS:

name: Deploy to AWS with OIDC

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          role-to-assume: arn:aws:iam::123456789012:role/MyGitHubActionsRole
          aws-region: us-east-1
          oidc-provider-url: https://token.actions.githubusercontent.com
          audience: sts.amazonaws.com

      - name: Deploy to AWS
        run: |
          aws s3 cp my-app s3://my-bucket --recursive

5. Best Practices

Always use short-lived tokens to reduce the risk of token theft.
Limit the permissions of the OIDC role to only what is necessary.
Regularly rotate secrets and credentials.
Monitor and log OIDC usage in your cloud provider.
Use environment variables to securely manage access keys and secrets.

6. FAQ

What is an OIDC token?

An OIDC token is a JSON Web Token (JWT) that contains claims about the user's identity and is issued by an OIDC provider.

How do I know if my OIDC setup is correct?

You can test your setup by monitoring the token requests and verifying that your cloud provider receives and accepts the tokens.

Can I use OIDC with other CI/CD tools?

Yes, many CI/CD tools support OIDC authentication, but the setup process may vary based on the tool.