GitHub Actions
GitHub Actions is GitHub's CI/CD platform that automates software testing and deployment through workflows. Many developers use IAM access keys to access AWS resources in these workflows. They create an IAM user and configure these credentials in their workflows. However, once configured, these keys remain static—often for years—introducing significant security risks.
A better approach is to use GitHub OpenID Connect (OIDC), which allows workflows to dynamically obtain temporary AWS credentials, eliminating the need for long-term IAM access keys.
The Problem with IAM Access Keys
IAM access keys are long-term credentials that provide authentication for an AWS account. While they are commonly used, they pose several security risks:
-
Access keys remain permanent once generated unless manually rotated, increasing the risk of forgotten or compromised credentials.
-
A small misconfiguration in IAM policies can unintentionally expose sensitive AWS resources.
-
If access keys are accidentally exposed in logs or repositories, attackers can exploit them to gain unauthorized access.
-
Since manual key rotation requires updates across AWS and application code, it is often neglected, leading to security risks.
These risks make IAM access keys unsuitable for modern CI/CD pipelines.
Solution: IAM Roles with GitHub OIDC
Previously, GitHub Actions required storing IAM access keys as secrets in workflows to access AWS services. This meant that keys were stored indefinitely, creating security vulnerabilities.
With GitHub OpenID Connect (OIDC), you no longer need to manage static credentials. Instead, GitHub Actions assumes an IAM role dynamically, generating short-lived temporary credentials for each workflow run. This eliminates the risk of exposed access keys and simplifies security management.
How to Set Up IAM Roles with GitHub OIDC
1. Create GitHub OIDC Identity Provider in AWS
In the AWS console, go to IAM console and go to Identity providers
Click Add provider and select OpenID Connect and enter:
-
https://token.actions.githubusercontent.comfor Provider URL field -
sts.amazonaws.comfor the Audience and Add provider -
Click Add provider
2. Create an IAM Role
Now that we’ve added the identity provider we will create an IAM role to establish a trust relationship.
-
Go to Roles and click Create role.
-
Select Web identity as trusted entity type.
-
For Identity provider and Audience, select the ones you created earlier
-
And enter your GitHub organization, repository and branch as per your need and click Next.
-
Now add the necessary Permissions policy and click Next.
-
Give a suitable name for your Role and click Create role
3. Configure GitHub Actions Workflow
To use OIDC authentication in GitHub Actions, you need to update your workflow file by adding the required permissions and configuring AWS credentials.
First, include the following permissions in your workflow:
permissions:
id-token: write
contents: read
Then, in the aws-actions/configure-aws-credentials@v4 step, add the AWS credentials configuration with the ARN of the IAM role created above and the AWS region where your resources are located:
uses: aws-actions/configure-aws-credentials@v4
with:
aws-region:
Complete example workflow
Here’s a complete example of a GitHub Actions workflow that assumes an IAM role using OIDC and deploys an application to an S3 bucket:
name: Deploy to AWS
on:
push:
branches:
- main
permissions:
id-token: write
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/MyOIDC
aws-region: us-east-1
- name: Deploy application
run: |
aws s3 cp ./build s3://my-bucket/ --recursive
4. Test and Verify
Once you’ve updated your workflow file, GitHub Actions will now use OIDC to assume the IAM role and retrieve short-lived tokens. You can verify them through workflow run logs under Configure AWS credentials.
Best Practices
Although this is a safer method, there are some best practices we can follow up on to ensure we do not leave any security risk.
-
To enhance security, assign only the necessary permissions for the workflow to function, following the least privilege principle.
-
Ensure a scoped trust relationship by limiting IAM roles to specific GitHub organizations, repositories, and branches.
-
Be cautious with wildcard (*) conditions in trust policies, as they can allow unauthorized repositories or organizations to assume roles, exposing AWS resources.
Conclusion
By switching to OIDC-based authentication, you eliminate the risks associated with long-term IAM access keys in GitHub Actions. While this setup requires a little extra effort initially, it provides stronger security, automatic credential management, and peace of mind.
That said, IAM access keys may still exist in your AWS account—whether for legacy workflows, third-party integrations, or unintended use. It’s crucial to regularly audit and ensure that access keys are rotated or removed when no longer needed.
With GuardKite, you can easily identify IAM access keys that haven’t been rotated, detect misconfigurations, and maintain a strong cloud security posture.
