Securely Configuring AWS Credentials in GitHub Actions Workflows

Integrating Amazon Web Services (AWS) with GitHub Actions requires a robust authentication mechanism to ensure that CI/CD pipelines can interact with cloud resources safely and efficiently. The aws-actions/configure-aws-credentials action serves as the primary utility for this purpose, establishing the necessary environment variables that allow subsequent workflow steps to execute AWS API calls. While earlier approaches relied on storing static long-term credentials as repository secrets, modern best practices strongly favor using OpenID Connect (OIDC) to generate short-lived, temporary credentials. This shift significantly reduces the security surface area by eliminating the need to hardcode sensitive access keys within the repository, adhering to the principle of least privilege and automatic credential rotation.

The configure-aws-credentials Action

The aws-actions/configure-aws-credentials GitHub Action is a specialized utility designed to configure AWS authentication for subsequent steps within a workflow. Its primary function is to implement the AWS JavaScript SDK credential resolution chain and export the appropriate environment variables that are automatically detected by both the AWS SDKs and the AWS Command Line Interface (CLI). By setting these variables, the action enables seamless interaction with AWS services such as S3, EC2, and Lambda, facilitating automated testing, deployment, and infrastructure management directly from the GitHub environment.

When this action is executed, it resolves credentials based on the configured authentication method and sets specific environment variables. These variables include AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, and AWS_REGION. The presence of these variables allows downstream actions and scripts to authenticate against AWS without requiring explicit credential handling in the user code. This abstraction layer simplifies the workflow definition and reduces the likelihood of configuration errors.

The action supports multiple authentication methods, but its design emphasizes security best practices. Specifically, it facilitates the use of GitHub's OIDC provider to obtain short-lived credentials. This approach is particularly valuable for teams looking to automate cloud operations while maintaining a high security posture. For organizations using GitHub Enterprise Server, the setup requires adjustments to accommodate the enterprise environment, specifically regarding URLs and identity providers, but the core utility of the action remains consistent.

Authentication Methods and Security Best Practices

The method used to configure AWS credentials determines the security profile of the CI/CD pipeline. Historically, users configured static long-term credentials by creating IAM users with access keys and storing those keys as repository secrets. While functional, this method poses significant security risks. Long-lived credentials have a broad exposure window, and if compromised, they grant persistent access to AWS resources until manually rotated or revoked. This practice contradicts AWS security recommendations, which advocate for short-lived credentials and automated rotation.

A more secure alternative involves using GitHub's OIDC provider to assume an AWS IAM role. This method allows workflows to obtain temporary credentials by authenticating against GitHub's OIDC endpoint. The temporary credentials are valid only for the duration of the workflow execution, drastically reducing the exposure window. This approach enhances the overall resilience of the authentication process and aligns with the principle of least privilege, as the assumed role can be granted only the specific permissions required for the deployment or testing task.

The choice between static credentials and OIDC depends on the specific use case and security requirements. For delegating the deployment of AWS infrastructure as code, OIDC is the preferred method. It eliminates the need to manage secret keys in the repository, reducing the administrative overhead and risk associated with credential leaks. The configure-aws-credentials action abstracts the complexity of this authentication process, handling the OIDC token exchange and role assumption behind the scenes.

Configuring OIDC with AWS

Implementing OIDC authentication requires establishing a trust relationship between AWS IAM and GitHub's OIDC provider. This process involves several steps that ensure only authorized GitHub workflows can assume the designated IAM role.

First, an IAM OIDC Identity Provider must be created in AWS. This provider is linked to GitHub's OIDC endpoint, allowing AWS to validate tokens issued by GitHub. Next, an IAM role is created with a trust policy that specifies the conditions under which the role can be assumed. This trust policy typically includes conditions related to the GitHub repository, branch, or environment, ensuring that only specific workflows from authorized repositories can assume the role.

Once the trust relationship is established, the configure-aws-credentials action can be configured in the workflow YAML to use OIDC authentication. The action requires the role-to-assume parameter, which specifies the ARN of the IAM role. The action then automatically handles the OIDC token retrieval and exchange, obtaining temporary credentials that are exported as environment variables. This setup allows workflows to interact with AWS services securely, without the need for static secrets.

For GitHub Enterprise Server users, the OIDC provider URL and other parameters may differ from the standard GitHub.com endpoint. The setup must be adjusted to reflect the specific enterprise environment, ensuring that the trust policy and action configuration align with the enterprise identity provider.

Workflow Configuration and Implementation

To use the configure-aws-credentials action in a workflow, it must be added as a step in the workflow YAML file. At a minimum, the aws-region parameter is required to specify the AWS region where the resources are located. The action can be configured to use either static secrets or OIDC, depending on the authentication method chosen.

For workflows using static credentials, the action references GitHub secrets to populate the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. The workflow file must be created in the .github/workflows/ directory, with a specific file name such as run-tests.yml. Within this file, the workflow is defined using YAML syntax, specifying the triggers, jobs, and steps.

The following example illustrates a complete workflow for a Node.js project that uses the aws-actions/configure-aws-credentials action to set up credentials using static secrets. This workflow runs unit tests that interact with AWS services using the aws-sdk.

```yaml
name: Run Tests

on:
push:
branches: [ main ]

jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3

  - name: Configure AWS Credentials
    uses: aws-actions/configure-aws-credentials@v4
    with:
      aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
      aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      aws-region: us-east-1

  - name: Install dependencies
    run: npm install

  - name: Run unit tests
    run: npm test

```

In this example, the aws-actions/configure-aws-credentials action is used to set the environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION. The values for the access key and secret key are retrieved from the repository secrets using the ${{ secrets.AWS_ACCESS_KEY_ID }} and ${{ secrets.AWS_SECRET_ACCESS_KEY }} syntax. The region is set to us-east-1, but this can be replaced with any valid AWS region, such as eu-west-1.

When using OIDC, the configuration differs slightly. The action does not require the aws-access-key-id or aws-secret-access-key parameters. Instead, it uses the role-to-assume parameter to specify the IAM role ARN. The action then automatically handles the OIDC token exchange and assumes the role.

```yaml
name: Deploy to AWS

on:
push:
branches: [ main ]

jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3

  - name: Configure AWS Credentials
    uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
      aws-region: us-east-1

  - name: Deploy infrastructure
    run: aws cloudformation deploy --template-file template.yaml --stack-name my-stack

```

In this OIDC-based example, the role-to-assume parameter specifies the ARN of the IAM role that the workflow will assume. The action retrieves a short-lived OIDC token from GitHub, exchanges it for temporary AWS credentials, and exports them as environment variables. The subsequent step can then use these credentials to deploy infrastructure using the AWS CLI.

Practical Application and Testing

The configuration of AWS credentials is essential for enabling safe and effective interactions between GitHub workflows and AWS services. Once the credentials are set up, workflows can authenticate and send API queries to AWS services, ensuring that AWS resources and GitHub repositories integrate seamlessly. This integration allows teams to automate testing, deployment, and other tasks directly from their CI/CD pipelines.

For example, unit tests can be written to use the aws-sdk to interact with AWS services. The test code can leverage the environment variables set by the configure-aws-credentials action to authenticate against AWS. This allows for comprehensive testing of AWS-dependent code within the CI/CD pipeline, ensuring that changes do not break existing functionality.

The configure-aws-credentials action simplifies this process by handling the authentication details. It leverages the AWS JavaScript SDK to resolve credentials and then exports them as environment variables, so other actions in the workflow can use them seamlessly. This avoids the unsafe practice of embedding long-term IAM credentials in the repository and reduces the complexity of the workflow definition.

Conclusion

The aws-actions/configure-aws-credentials action is a critical component of secure and efficient GitHub Actions workflows that interact with AWS. By providing a standardized way to configure AWS authentication, it simplifies the process of integrating AWS services into CI/CD pipelines. The action supports multiple authentication methods, with a strong emphasis on using OIDC to obtain short-lived credentials. This approach enhances security by reducing the exposure window and adhering to best practices for credential management.

For teams looking to automate cloud operations, the choice of authentication method is paramount. While static credentials are easier to set up, they pose significant security risks. OIDC-based authentication, although requiring more initial configuration, offers a much higher level of security and resilience. By leveraging the configure-aws-credentials action with OIDC, teams can ensure that their GitHub workflows interact with AWS securely and efficiently, enabling robust and reliable CI/CD pipelines.

Sources

1. CICube: GitHub's Actions AWS Credentials
2. DeepWiki: Configure AWS Credentials Installation and Usage
3. GeeksforGeeks: Setting AWS Credentials in GitHub Actions
4. CodeGenes: How AWS Credentials Works at GitHub Actions
5. DeepWiki: Configure AWS Credentials Overview
6. Dev.to: Configure Authentication to Your AWS Account in GitHub Actions CI