Introduction: The Need for Enhanced Security in GitHub Actions and AWS Integration
As more development teams adopt continuous integration and continuous deployment (CI/CD) practices, integrating GitHub Actions with AWS has become increasingly common. However, traditional API key authentication poses significant security risks, including key leakage and management complexity. To address these issues, OpenID Connect (OIDC) offers a more secure and streamlined alternative. This guide will explore the benefits of OIDC and provide a step-by-step tutorial on implementing OIDC in Terraform to securely connect GitHub Actions with AWS.
Understanding OIDC: A Superior Alternative to Traditional API Key Authentication
OpenID Connect (OIDC) is an identity layer built on the OAuth 2.0 protocol. It allows clients, such as GitHub Actions, to verify an end-user’s identity based on the authentication performed by an authorization server. Unlike API keys, OIDC tokens are short-lived and can be dynamically issued, reducing the risk of unauthorized access.
Critical Advantages of Implementing OIDC for GitHub Actions and AWS
- Enhanced Security: OIDC tokens are ephemeral and scoped, minimizing the risk of long-term exposure.
- Simplified Key Management: Eliminates the need to manage and rotate long-lived API keys.
- Fine-Grained Access Control: Allows precise control over permissions through IAM roles and policies.
- Improved Auditability: Provides better tracking of access and usage through AWS CloudTrail.
Step-by-Step Guide: Creating the OIDC Provider in AWS Using Terraform
Step 1: Initialize Terraform Configuration
Create a new directory for your Terraform configuration files and initialize Terraform:
mkdir terraform-oidc
cd terraform-oidc
terraform init
Step 2: Define the OIDC Provider
Create a file named main.tf and add the following configuration to define the OIDC provider:
provider “aws” {
region = “us-west-2”
}
resource “aws_iam_openid_connect_provider” “github” {
url = “https://token.actions.githubusercontent.com”
client_id_list = [“sts.amazonaws.com”]
thumbprint_list = [“6938fd4d98bab03faadb97b34396831e3780aea1”]
}
Step 3: Configure the IAM Role and Trust Policy
Add the following configuration to define the IAM role and its trust policy:
resource “aws_iam_role” “github_actions_role” {
name = “GitHubActionsRole”
assume_role_policy = <<EOF
{
“Version”: “2012-10-17”,
“Statement”: [
{
“Effect”: “Allow”,
“Principal”: {
“Federated”: “${aws_iam_openid_connect_provider.github.arn}”
},
“Action”: “sts:AssumeRoleWithWebIdentity”,
“Condition”: {
“StringLike”: {
“token.actions.githubusercontent.com:sub”: “repo:<your_github_repo>:ref:refs/heads/<your_branch>”
}
}
}
]
}
EOF
}
resource “aws_iam_role_policy” “github_actions_policy” {
role = aws_iam_role.github_actions_role.id
policy = <<EOF
{
“Version”: “2012-10-17”,
“Statement”: [
{
“Effect”: “Allow”,
“Action”: [
“ecr:GetDownloadUrlForLayer”,
“ecr:BatchGetImage”,
“ecr:CompleteLayerUpload”,
“ecr:UploadLayerPart”,
“ecr:InitiateLayerUpload”,
“ecr:PutImage”
],
“Resource”: “*”
}
]
}
EOF
}
Step 4: Apply the Terraform Configuration
Deploy the configuration to AWS:
terraform apply
Empowering GitHub Actions: Implementing the OIDC Workflow with Terraform
Step 1: Create the GitHub Actions Workflow
In your GitHub repository, create a new workflow file in .github/workflows directory:
name: Build and Push Docker Image to ECR
on:
push:
branches:
– main
jobs:
build:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: read
steps:
– name: Checkout code
uses: actions/checkout@v2
– name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v1
with:
role-to-assume: arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/GitHubActionsRole
aws-region: us-west-2
– name: Login to Amazon ECR
id: login-ecr
uses: aws-actions/amazon-ecr-login@v1
– name: Build, tag, and push image to ECR
env:
ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
ECR_REPOSITORY: your-ecr-repository
IMAGE_TAG: ${{ github.sha }}
run: |
docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
Complete Example: Building and Uploading a Docker Image to ECR Using GitHub Actions and Terraform
This example demonstrates how to securely connect GitHub Actions to AWS using OIDC, build a Docker image, and push it to Amazon ECR. By following these steps, you can ensure a secure and streamlined CI/CD pipeline.
Conclusion
Implementing OIDC for GitHub Actions and AWS integration enhances security, simplifies critical management, and provides fine-grained access control. By leveraging Terraform, you can automate the setup process, ensuring consistency and repeatability in your infrastructure.
References
Integrating with GitHub Actions – CI/CD pipeline to deploy a Web App to Amazon EC2
Automate Microsoft web application deployments with GitHub Actions and Terraform.