GitHub workflow can communicate with our AWS resources, directly (via AWS CLI commands) or indirectly (via e.g. Terraform AWS provider).
Before running AWS CLI commands, deploying AWS infrastructure with Terraform, or interacting with AWS services in any way we need to include a step which configures AWS credentials. It ensures that the workflow runner is authenticated with AWS and knows which region to target.
This step should contain configure-aws-credentials action provided by AWS. This action sets up the necessary environment variables so that AWS CLI commands and SDKs can authenticate with AWS services.
aws-region input sets the default AWS region to us-east-2 (Ohio). All AWS commands run in later steps will use this region unless overridden.
We can use either IAM user or OIDC (temp token) authentication.
IAM User Authentication
If using IAM user authentication, we can store user's credentials in a dedicated GitHub secrets:
env:
AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
AWS_REGION: us-east-2
// Define this step before steps which are accessing AWS:
- name: Configure AWS Credentials
uses: aws-actions/configure-aws-credentials@v2
with:
aws-region: ${{ env.AWS_REGION }}
OpenID Connect (OIDC) Authentication
In this authentication, configure-aws-credentials GitHub Action uses GitHub's OpenID Connect (OIDC) for secure authentication with AWS. It leverages the OIDC token provided by GitHub to request temporary AWS credentials from AWS STS, eliminating the need to store long-lived AWS access keys in GitHub Secrets.
Note that we now need to grant the workflow run a permissions for write access to the id-token:
id-token: write allows the workflow to request and use OpenID Connect (OIDC) tokens. The write level is required for actions that need to generate or use OIDC tokens to authenticate with external systems. Granting id-token: write is essential for workflows that use OIDC-based authentication, such as securely assuming AWS IAM roles via GitHub Actions. This enables secure, short-lived authentication to AWS and other cloud providers. This permission is a security best practice for modern CI/CD workflows that use OIDC to authenticate with cloud providers, reducing the need for static secrets.
env:
AWS_REGION: us-east-2
permissions:
id-token: write # aws-actions/configure-aws-credentials (OIDC)
...
- name: Configure AWS Credentials
uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/github-actions-role
role-session-name: my-app
aws-region: ${{ env.AWS_REGION }}
Here's how it works:
- GitHub OIDC Provider: GitHub acts as an OIDC provider, issuing signed JWTs (JSON Web Tokens) to workflows that request them.
- configure-aws-credentials Action: This action, when invoked in a GitHub Actions workflow, receives the JWT from the OIDC provider.
- AWS STS Request: The action then uses the JWT to request temporary security credentials from AWS Security Token Service (STS).
- Credential Injection: AWS STS returns temporary credentials (access key ID, secret access key, and session token) which the action injects as environment variables into the workflow's execution environment.
- AWS SDKs and CLI: AWS SDKs and the AWS CLI automatically detect and use these environment variables for authenticating with AWS services.
Benefits of using OIDC with configure-aws-credentials:
- Enhanced Security: Eliminates the need to store long-lived AWS access keys, reducing the risk of compromise.
- Simplified Credential Management: Automatic retrieval and injection of temporary credentials, simplifying workflow setup and maintenance.
- Improved Auditing: Provides better traceability of actions performed within AWS, as the identity is linked to the GitHub user or organization.
Before using the action:
- Configure an OpenID Connect provider in AWS: We need to establish an OIDC trust relationship between GitHub and our AWS account.
- Create an IAM role in AWS: Define the permissions for the role that the configure-aws-credentials action will assume.
- Set up the GitHub workflow: Configure the configure-aws-credentials action with the appropriate parameters, such as the AWS region and the IAM role to assume.
In an OpenID Connect (OIDC) authentication scenario, the aws-actions/configure-aws-credentials action creates the following environment variables when assuming a role with temporary credentials: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN. These variables are used by the AWS SDK and CLI to interact with AWS resources.
Here's a breakdown:
- AWS_ACCESS_KEY_ID: This environment variable stores the access key ID of the temporary credentials.
- AWS_SECRET_ACCESS_KEY: This environment variable stores the secret access key of the temporary credentials.
- AWS_SESSION_TOKEN: This environment variable stores the session token associated with the temporary credentials, which is required for operations with AWS Security Token Service (STS).
These environment variables are populated by the action after successful authentication with the OIDC provider and assuming the specified IAM role. The action retrieves the temporary credentials from AWS and makes them available to subsequent steps in the workflow.
Once AWS authentication is done and this env variables are created, the next steps in the workflow can access our AWS resources, e.g. read secrets from AWS Secrets Manager:
- name: Read secrets from AWS Secrets Manager into environment variables
uses: aws-actions/aws-secretsmanager-get-secrets@v2
with:
secret-ids: |
my-secret
parse-json-secrets: true
- name: deploy
run: |
echo $AWS_ACCESS_KEY_ID
echo $AWS_SECRET_ACCESS_KEY
env:
MY_KEY: ${{ env.MY_SECRET_MY_KEY }}
This example assumes that in AWS secret my-secret we have a key MY_KEY, set to the secret value we want to fetch and use.
