iTranslated by AI
Secure AWS Deployments with Terraform and GitHub OIDC
Introduction
When deploying to AWS from GitHub Actions, the first problem you face is "how to handle authentication."
Using IAM user access keys in GitHub Secrets is simple, but it carries the risk of storing long-term credentials in your repository. Managing key rotation is also quietly troublesome.
By using GitHub OIDC (OpenID Connect), you can access AWS without long-term credentials. Furthermore, by managing that configuration with Terraform, you can ensure both reproducibility and visibility of your settings.
In this article, I will introduce the GitHub OIDC × Terraform design that I actually built for my personal development diary app, Storyie.
Why OIDC?
Let's compare the traditional method with OIDC.
IAM User + Access Key Method
- Store
AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEYin GitHub Secrets - If the keys leak, the account is permanently accessible
- Requires periodic rotation (which is easy to forget)
GitHub OIDC Method
- Authenticate to AWS using short-lived tokens issued by GitHub
- No long-term credentials exist
- Access can be restricted by branch or repository
- Validates the request based on the "which repository and which branch" in the AWS trust policy
Even in personal development, I don't want to cut corners on security. OIDC doesn't have a high setup cost, and once you build it, you are freed from rotation management.
Overview
The configuration is simple.
terraform/github-oidc/
├── main.tf # OIDC provider + IAM role + policy
├── variables.tf # Variable definitions
├── outputs.tf # Outputs (role ARN, etc.)
└── terraform.tfvars.example # Configuration example
There are three resources managed by Terraform:
- OIDC Provider — Registers GitHub Actions as a trusted identity provider in AWS
- IAM Role — The target assumed by GitHub Actions. Restricts by repository and branch via the trust policy
- IAM Policy — Contains the AWS permissions necessary for SST deployment
Terraform Design
OIDC Provider
resource "aws_iam_openid_connect_provider" "github" {
url = "https://token.actions.githubusercontent.com"
client_id_list = [
"sts.amazonaws.com",
]
thumbprint_list = [
"6938fd4d98bab03faadb97b34396831e3780aea1",
"1c58a3a8518e8759bf075b76b750d4f2df264fcd"
]
}
Specify sts.amazonaws.com for client_id_list. This is the audience used when GitHub Actions performs token exchange with AWS STS.
thumbprint_list contains the TLS certificate fingerprints for GitHub's OIDC endpoint. AWS uses these to verify tokens from GitHub.
Trust Policy — Allowing specific repositories and branches
data "aws_iam_policy_document" "github_actions_assume_role" {
statement {
effect = "Allow"
principals {
type = "Federated"
identifiers = [aws_iam_openid_connect_provider.github.arn]
}
actions = ["sts:AssumeRoleWithWebIdentity"]
condition {
test = "StringEquals"
variable = "token.actions.githubusercontent.com:aud"
values = ["sts.amazonaws.com"]
}
condition {
test = "StringLike"
variable = "token.actions.githubusercontent.com:sub"
values = [
for branch in var.github_branches :
"repo:${var.github_org}/${var.github_repo}:ref:refs/heads/${branch}"
]
}
}
}
This is the core of the security. Using the sub claim condition, we allow requests only from specific branches of a specific repository.
In Storyie, I only allow the main and develop branches. Since direct deployment from feature branches is rejected by the trust policy, it enforces the deployment flow.
Because it is managed by variables, adding or changing branches is as easy as editing terraform.tfvars and running apply.
variable "github_branches" {
description = "List of GitHub branches allowed to assume the role"
type = list(string)
default = ["develop", "main"]
}
IAM Policy for SST Deployment
SST (Serverless Stack) internally operates many AWS services such as CloudFormation, S3, Lambda, and CloudFront. I have aggregated the necessary permissions in a policy document.
data "aws_iam_policy_document" "sst_deploy" {
# CloudFormation — SST stack management
statement {
sid = "CloudFormation"
effect = "Allow"
actions = ["cloudformation:*"]
resources = ["*"]
}
# S3 — Asset delivery and SST state management
statement {
sid = "S3"
effect = "Allow"
actions = ["s3:*"]
resources = ["*"]
}
# Lambda — Next.js Server Functions
statement {
sid = "Lambda"
effect = "Allow"
actions = ["lambda:*"]
resources = ["*"]
}
# CloudFront — CDN delivery
# Route53 — DNS management
# ACM — SSL certificates
# SQS + DynamoDB — Next.js ISR Revalidation
# ... Same for other services
}
To be honest, the heavy use of * is a trade-off in personal development. For corporate projects, you should tighten resource ARNs for stricter control. However, for personal projects, this balances against the stress of deployment failing due to insufficient permissions when SST creates new resources during version updates.
GitHub Actions Configuration
Use the role created with Terraform in GitHub Actions.
jobs:
deploy:
runs-on: self-hosted
permissions:
id-token: write # Required to obtain the OIDC token
contents: read
steps:
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
aws-region: us-east-1
- name: Deploy to AWS with SST
run: pnpm sst:deploy:prod
There are two key points:
permissions.id-token: write: Without this, GitHub will not issue an OIDC token. The id-token permission is not granted by default, so it must be explicitly written.
aws-actions/configure-aws-credentials@v4: Simply passing the role ARN to role-to-assume handles everything internally: fetching the OIDC token, performing AssumeRoleWithWebIdentity against STS, and setting the temporary credentials.
Since AWS_ROLE_ARN is displayed in the Terraform output, register it in your GitHub Secrets.
Setup Procedure
1. Execute Terraform
cd terraform/github-oidc
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars (set github_org, github_repo)
terraform init
terraform plan
terraform apply
2. Configure GitHub Secrets
Register the role ARN displayed in the terraform apply output as AWS_ROLE_ARN in your GitHub repository's Secrets.
I also included setup instructions in the Terraform outputs.
output "github_secret_instructions" {
value = <<-EOT
1. Copy the role ARN above
2. Go to Settings → Secrets and variables → Actions
3. Name: AWS_ROLE_ARN
4. Value: (Role ARN)
EOT
}
Embedding instructions in the output is surprisingly useful for ensuring that team members or your future self don't get lost.
3. Run the Workflow
After this, pushing to main or develop will trigger an automatic deployment via OIDC authentication.
Regarding State Management
In this setup, I store the Terraform state locally.
backend "local" {
path = "terraform.tfstate"
}
I decided it wasn't worth setting up a remote backend with S3 + DynamoDB because OIDC settings are rarely changed after the initial build. Since I am the only one working on this personal project, state conflicts will not occur.
However, don't forget to add terraform.tfstate to your .gitignore. The state file contains sensitive information like AWS account IDs and role ARNs.
Reflections After Actual Use
Pros
- Zero rotation management: Once built, you can completely forget about it. This is the biggest benefit.
- Branch restrictions act as natural guardrails: I no longer accidentally deploy from feature branches.
-
Configuration visualized via Terraform: Even if I wonder, "What permissions does this role have?" six months from now, I can just check the
.tffile. - Setup instructions remain in the output: I don't get lost when creating the same setup in a new repository.
Points of Caution
-
Forgetting to specify
id-token: write: This was a point where I got stuck at the beginning. You will get anAccessDeniederror because the OIDC token cannot be retrieved. - Updating the thumbprint: If GitHub updates its certificate, the thumbprint may change. Check if you encounter errors.
- Combination with self-hosted runners: Storyie uses self-hosted runners, but OIDC works the same way for both GitHub-hosted and self-hosted runners.
Conclusion
The combination of GitHub OIDC and Terraform is an investment that pays off even for personal development.
- Freed from long-term credential management
- Deployment permissions can be controlled at the branch level
- Configuration becomes reproducible via Terraform
Personal development often tends to put security on the back burner as "too much trouble," but by solving it with a mechanism from the start, you can focus on coding with peace of mind.
The configuration introduced in this article is the actual deployment infrastructure for the diary app Storyie.
📝 Web: https://storyie.com
🍎 iOS: App Store
🤖 Android Beta: https://storyie.com/android-beta
Discussion