With this blog, we will show you how to access your AWS environment without storing IAM credentials in GitHub by using OpenID Connect (OIDC).
OpenID Connect has been around since 2014, and in reality, it’s a simplified identity layer on top of the OAuth 2.0 protocol. This gives your clients and applications an easy process to authenticate against an Authorization Server and get information about the end-users (in this case AWS) but in a process flow that’s easier for applications to do so. For a deeper look into OpenID Connect check out https://openid.net/connect/.
So using OpenID Connect we can remove the need to have keys stored in GitHub Actions, saving the headache of rotating the keys or the other headaches.
The first step to this whole process is to configure AWS to allow GitHub to communicate with it via OpenID Connect. Here are a few different ways to do it.
We've got three different ways to do this AWS Console, AWS CLI, and Terraform.
Once you are logged into the AWS Console, head to IAM and select Identity providers
:
Select the Add provider
button in the top right corner
On the Add an Identity provider
screen, you will want to select OpenID Connect
as the Provider type
, and then add the following information to the fields
https://token.actions.githubusercontent.com
https://github.com/(org name)
(so in our case https://github.com/cloudquery
)Make sure to select Get thumbprint
to get the certificates, and then Add provider
in the bottom right.
The next step is to add a role for the provider to assume when the GitHub Action accesses AWS. head to Roles
within IAM
:
Select Create role
in the top right.
Now we need to identify our OpenID Connect provider. Select Web identity
from the Trusted entity types
, select the token.actions.githubusercontent.com
from the Identity provider
drop-down, and then select the Audience
you added a moment ago. Then hit next
.
The next step is to either assign or create the permissions the role will need, so what permissions do your GitHub Actions need to work within AWS. This is entirely up to your needs, so best to do reading around AWS Roles and service permissions.
The final step in creating the Role is to name it and provide a relevant description. You can also add more permissions or even adapt the trusted entities
( which Identity providers have access to the role).
Now that we have a working OpenID Connect provider within AWS, we need to add the configuration to GitHub for use in our GitHub Actions. To do this, we simply add another step to the desired yml
workflow. At CloudQuery we already have a fully working version in our Integration Test.
The relevant blocks look like so:
permissions:
id-token: write
contents: read # This is required for actions/checkout@v2
Adding the permissions
to the job allows the action that gets the credentials from AWS to store them for use in further steps. The permission that is specifically required is id-token: write
.
The next step
is where the credential retrieving magic actually happens
steps:
[…]
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v1
with:
role-to-assume: arn:aws:iam::000000000000:role/cq-provider-aws-github-action
aws-region: us-east-1
[…]
An AWS action already exists, so we point to aws-actions/configure-aws-credentials@v1
then within the with
section we add the role we want it to assume (like arn:aws:iam::000000000000:role/GitHubActionRole
), which AWS region it operates within, and we can optionally add the Role session name.
Now, no matter which way you’ve chosen to configure the AWS component your GitHub Actions are able to communicate without the need for stored keys and the access can be managed entirely on the AWS side of things.