Securely integrate AWS Credentials with GitHub Actions using OpenID Connect

Recently, I had a request come up where I had to interact with AWS resources from GitHub Actions. In the past, I had done this using Azure Pipelines. I did that by: (a) storing the credentials (access_key and secret_key of the IAM user) as secure variables in the Azure DevOps Library variable group and (b) by allowing Azure Pipelines builder to access the secure variables in the variable group.

In the case of GitHub actions, I could use a similar approach: store the secrets securely (GitHub repo page -> Settings -> Security -> Secrets and variables -> Actions -> New repository secret) in the repository, which would enable the GitHub Actions builder to access to them. And although the credentials are stored as secrets, they can get accidentally exposed if someone gains access to the build runner machine. And to prevent long-lived access keys, one will have to create new security credentials (access and secret keys in Amazon Identity and Access Management (IAM)) and then update the same in GitHub Actions secrets regularly, which could become tedious. But there is a better option than that from a security and maintainability standpoint which I discuss here.

In this note, as the title suggests, I explain in detail how to securely integrate AWS Credentials with GitHub Actions using OpenID Connect. I also have a link to my GitHub repo with the actions YAML file that you may fork.

It is best to understand this concept via a use case. The example use case is to check if an S3 bucket exists in my AWS account and delete it if it does. This use case covers the broader objective of interacting with the AWS cloud using an OpenID Connect with GitHub Actions.

As a reader of this note, I assume you are familiar with IAM credentials like user, role, policy, and GitHub Actions. This popular CI-CD platform enables developers to build and deploy the code stored in their GitHub repository.

Before I start, I want to share a couple of references that helped me understand this concept: (1) AWS-Docs: Creating OpenID Connect identity providers, (2) GitHub-Docs: Configuring OpenId Connect in Amazon Web Services and (3) glick.stream’s YouTube video: E6 – GitHub Actions: Learn OpenID Connect (OIDC) and deploy securely to AWS || Full Tutorial.

The use case consists of four steps, which are:
1. Create an OpenID Connect identity provider in IAM.
2. Create a new IAM role.
3. Edit the IAM role.
4. Store the IAM role details in GitHub Actions and refer to that in the YAML file.

Step 1: Create an OpenID Connect identity provider in IAM for GitHub Actions
This page –Creating and managing an OIDC provider (console) provides a detailed step-by-step guide to add the Identity provider. The provider URL and the client ID (also known as the audience) are available at this link –adding the identity provider to AWS.

Once done, click on Add provider. Now, we have the identity provider created. The next step is to create a role associated with the Identity provider.

Step 2: Create a new role
On the AWS IAM console, navigate to Access Management -> Roles -> Create Role -> Web identity.

You can assign a permission policy if you have specific permissions that you would want the GitHub action to acquire and then click on next. The easiest option is to associate an AdministratorAccess Policy. However, it is not following the principle of least privilege, so please create a new permission policy with only those permissions that the GitHub Actions builder requires. Once done, click next.
On the next page, name the role and review the trusted entities. Below is a similar screenshot.

Step 3: Edit the role
After creating the role, I edited the trust relationship based on the advice at adding-the-identity-provider-to-AWS. After making the change, the trust entity looked like the below image.

As you can see, I updated the trusted entity with my GitHub repository name, and the wildcard represents any branch in that repository. The trust policy editor might complain because of the wildcard. I ignored that because I wanted the GitHub action step to work for all branches.
The final step is to refer to the role in the project pipeline’s YAML file.

Step 4: Store the IAM role ARN in GitHub Actions secret and refer to that in the YAML file
In my case, I stored the role ARN as a secret in the GitHub repository and referred to that in the YAML file. You can access that from my GitHub repo: TestProjects.

Also, please do not forget to update the YAML file with the permissions settings described in this step -adding-permissions-settings.

If you are interested in the build logs, please access them at GitHub Actions.

I can think of two benefits of the above process:
-I no longer have to store the aws access and secret key in GitHub, and I no longer have to rotate the access_key and secret key, which frees up my time and strengthens the security posture of my AWS Account and the GiHub Actions workflow.

This note must have been helpful, and you will also try to use the federated login option to integrate GitHub Actions and your AWS account. Let me know if you have any questions or suggestions.