The transition from static IAM credentials to OpenID Connect (OIDC) authentication represents a paradigm shift in cloud security for continuous integration and continuous deployment (CI/CD) pipelines. Historically, developers embedded long-term access keys directly into repository secrets, creating a persistent security liability. The aws-actions/configure-aws-credentials action facilitates this migration by leveraging GitHub’s OIDC provider to request short-lived, temporary credentials dynamically. This approach enforces the principle of least privilege, eliminates the risk of credential leakage, and aligns with AWS and GitHub’s modern security standards.
The Security Imperative: Eliminating Static Credentials
Traditional workflows relied on hardcoding aws-access-key-id and aws-secret-access-key within GitHub Actions secrets. This method poses significant risks: static keys are potential targets for exfiltration, lack automatic rotation mechanisms, and often grant excessive permissions across the AWS account. The adoption of OIDC mitigates these risks by removing the need for long-term credentials entirely. Instead, the workflow authenticates using a JSON Web Token (JWT) issued by GitHub’s OIDC provider.
In the specific context of the v1-node16 tag, the configuration explicitly removes static credential inputs. The workflow relies solely on the role-to-assume parameter to define the target IAM role. This role is configured to accept OIDC tokens from GitHub, allowing the action to assume the role and generate temporary session credentials. By stripping away static keys, the attack surface is drastically reduced, ensuring that no long-lived secrets reside in the GitHub repository.
Workflow Configuration and Permission Requirements
Implementing this security model requires precise configuration of both the GitHub Actions workflow and the underlying infrastructure. The action aws-actions/configure-aws-credentials@v1-node16 must be invoked with specific parameters to facilitate OIDC authentication. The role-session-name is typically set to GitHubActions for auditability, while role-duration-seconds can be configured to 3600 (one hour) to limit the lifespan of the generated credentials.
Crucially, the workflow file itself must declare the necessary permissions to interact with the OIDC token service. Without these explicit permissions, the action cannot retrieve the token required for authentication.
id-token: write— Grants the workflow the ability to obtain the OIDC token from GitHub’s identity provider.contents: read— Allows the workflow to access repository contents, which is often required for deployment tasks such as reading configuration files or source code.
yaml
permissions:
id-token: write
contents: read
Infrastructure Setup: IAM Roles and Trust Policies
The backend configuration involves establishing an IAM role that trusts the GitHub OIDC provider. This trust relationship is defined using a trust policy that specifies the GitHub organization, repository, and branch as conditions. The role must also be attached to an IAM policy that grants only the specific permissions required for the deployment task, such as s3:ListBucket or s3:GetObject.
For enterprise environments, the setup may require adjustments to identity provider URLs and configuration templates. AWS provides CloudFormation templates to automate the creation of the OIDC provider and IAM roles.
yaml
Resources:
GithubOidc:
Type: AWS::IAM::OIDCProvider
Properties:
Url: https://token.actions.githubusercontent.com
ClientIdList:
- sts.amazonaws.com
ThumbprintList:
- "fffffffffffffffffffffffffffffffffffffff"
This configuration ensures that only authorized GitHub Actions can assume the role, preventing unauthorized entities from gaining access to AWS resources.
Operational Patterns: Credential Passing and Profiles
The configure-aws-credentials action supports advanced operational patterns, including the passing of credentials between steps and the use of named AWS profiles. By setting output-credentials: true, the action exposes the generated access key ID, secret access key, and session token as step outputs. These outputs can be referenced in subsequent steps, enabling complex multi-step workflows.
```yaml
- name: Configure AWS Credentials 1
id: creds
uses: aws-actions/[email protected]
with:
aws-region: us-east-2
role-to-assume: arn:aws:iam::123456789100:role/my-github-actions-role
output-credentials: true
- name: get caller identity 1
run: |
aws sts get-caller-identity
```
For environments requiring interaction with multiple AWS accounts or roles, the action supports the aws-profile parameter. This writes credentials to the standard AWS configuration files (~/.aws/credentials and ~/.aws/config), allowing the AWS CLI, SDKs, and tools like CDK to reference specific profiles.
```yaml
- name: Configure AWS Credentials for Dev
uses: aws-actions/[email protected]
with:
aws-region: us-east-1
role-to-assume: arn:aws:iam::111111111111:role/dev-role
aws-profile: dev
name: Configure AWS Credentials for Prod
uses: aws-actions/[email protected]
with:
aws-region: us-west-2
role-to-assume: arn:aws:iam::222222222222:role/prod-role
aws-profile: prodname: Use multiple profiles
run: |
# Check caller identity for dev account
aws sts get-caller-identity --profile dev
# Check caller identity for prod account
aws sts get-caller-identity --profile prod
# Deploy to dev using CDK
cdk deploy --profile dev
```
This profile-based approach enables a single workflow to manage deployments across different environments (e.g., Dev and Prod) by assuming distinct roles and writing to separate configuration entries.
Troubleshooting and Version Considerations
While the v1-node16 tag is referenced in specific configurations, users may encounter module resolution errors if the underlying Node.js environment is incompatible. A common error involves the inability to find the aws-sdk module, resulting in a MODULE_NOT_FOUND exception.
Error: Cannot find module 'aws-sdk'
Require stack:
- /home/runner/work/_actions/aws-actions/configure-aws-credentials/v1-node16/dist/index.js
This issue highlights the importance of using stable, supported versions of the action. The v1-node16 tag may be deprecated or incompatible with current runner environments. Upgrading to a newer version (e.g., v4 or v6.1.0) typically resolves such dependency conflicts, as newer versions bundle their dependencies statically or update their module resolution logic. When migrating from static credentials to OIDC, ensuring the action version is compatible with the runner’s Node.js runtime is critical for stability.
Conclusion
The shift to aws-actions/configure-aws-credentials with OIDC authentication marks a significant advancement in CI/CD security. By replacing static keys with dynamically generated, short-lived credentials, organizations can enforce least-privilege access and eliminate the risks associated with long-term secret management. Proper configuration of workflow permissions, IAM trust policies, and profile handling ensures that deployments are both secure and scalable. As infrastructure-as-code tools like CDK become more prevalent, the ability to manage multiple AWS profiles within a single workflow provides the flexibility needed for complex multi-account architectures. This approach not only secures the pipeline but also simplifies the maintenance of access strategies across development and production environments.