impl

AWS IAM User Setup Library for Open Source Projects

This module provides automated IAM user credential setup for open source projects that need AWS access in their CI/CD pipelines. While OIDC (OpenID Connect) is the most secure approach for AWS authentication from GitHub Actions, this library offers a simpler, more automated alternative that’s suitable for rapid deployment and testing scenarios.

The primary motivation for this approach is to provide:

• Automated IAM user creation with minimal required permissions

• Seamless integration with GitHub Secrets for CI/CD workflows

• Quick setup for open source projects without complex OIDC configuration

• Proper cleanup capabilities to avoid resource accumulation

Security considerations:

• IAM users have long-lived credentials (less secure than temporary OIDC tokens)

• Permissions are scoped to the minimum required for the specific use case

• Access keys are stored securely in GitHub Secrets (encrypted at rest)

• Cleanup methods ensure resources don’t persist unnecessarily

This approach trades some security for simplicity and automation, making it ideal for open source projects that need quick AWS integration without the overhead of OIDC setup and management.

class simple_gh_aws_creds.impl.SetupGitHubRepo(boto_ses: Session, aws_region: str, iam_user_name: str, tags: dict[str, str], policy_document: dict[str, Any], attached_policy_arn_list: list[str], path_access_key_json: Path, github_user_name: str, github_repo_name: str, github_token: str, github_secret_name_aws_default_region: str = 'AWS_DEFAULT_REGION', github_secret_name_aws_access_key_id: str = 'AWS_ACCESS_KEY_ID', github_secret_name_aws_secret_access_key: str = 'AWS_SECRET_ACCESS_KEY')

Automated IAM User Setup for GitHub Actions Integration

This class orchestrates the complete lifecycle of IAM user credentials for open source projects. It addresses the common challenge of securely providing AWS access to GitHub Actions workflows without the complexity of OIDC setup.

The automation handles both setup and cleanup phases, ensuring that credentials are properly managed throughout their lifecycle. This is particularly important for open source projects where multiple contributors may need to manage AWS resources but shouldn’t have access to long-lived credentials.

Key automation benefits:

• Eliminates manual IAM user creation and policy attachment

• Automatically configures GitHub Secrets with proper naming conventions

• Provides idempotent operations (safe to run multiple times)

• Includes comprehensive cleanup to prevent credential sprawl

Security design principles:

• Principle of least privilege (minimal required permissions only)

• Automated credential rotation capability through recreate operations

• Clear separation between setup and teardown operations

• GitHub Secrets integration for secure credential storage

Parameters:

• boto_ses – Boto3 session instance for AWS API interactions, should be configured with appropriate credentials and region for IAM operations

• aws_region – AWS region identifier (e.g., ‘us-east-1’) where the IAM user will be created and used for GitHub Actions

• iam_user_name – Name for the IAM user that will be created for GitHub Actions automation. Should follow AWS naming conventions and be descriptive of its purpose

• tags – Dictionary of key-value pairs for tagging the IAM user, useful for resource management, cost tracking, and identifying the automation source

• policy_document – IAM policy document as a dictionary defining the minimal permissions required for your GitHub Actions. Should follow principle of least privilege

• attached_policy_arn_list – List of AWS managed policy ARNs to attach to the IAM user in addition to the inline policy. Use empty list if only inline policy is needed

• path_access_key_json – Path object pointing to a local JSON file where AWS access key credentials will be stored for reuse across multiple runs

• github_user_name – GitHub username or organization name that owns the repository

• github_repo_name – Name of the GitHub repository where secrets will be configured

• github_token – GitHub personal access token with ‘repo’ scope permissions to manage repository secrets. Should have write access to the target repository

• github_secret_name_aws_default_region – Name for the GitHub secret that will store the AWS region value (default: “AWS_DEFAULT_REGION”)

• github_secret_name_aws_access_key_id – Name for the GitHub secret that will store the AWS access key ID (default: “AWS_ACCESS_KEY_ID”)

• github_secret_name_aws_secret_access_key – Name for the GitHub secret that will store the AWS secret access key (default: “AWS_SECRET_ACCESS_KEY”)

Note

This tool does not create IAM policies - it only attaches existing AWS managed policies specified in attached_policy_arn_list. Policy creation is out of scope for this simple automation tool designed for rapid IAM user setup. If your use case requires complex permissions beyond a single inline policy, consider using dedicated IAM management tools instead. This library is optimized for simple, come-and-go scenarios where one inline policy should be sufficient.

Setup Workflow:

• s11_create_iam_user()

• s12_put_iam_policy()

• s13_create_or_get_access_key()

• s14_setup_github_secrets()

Teardown Workflow:

• s21_delete_github_secrets()

• s22_delete_access_key()

• s23_delete_iam_policy()

• s24_delete_iam_user()

s11_create_iam_user()

Create IAM user with proper tagging for resource management.

This method creates an IAM user specifically for CI/CD automation, eliminating the need for human users to share or manage AWS credentials. The tagging strategy enables proper resource tracking and cost attribution, which is essential for open source projects that may have multiple automated workflows.

The idempotent design ensures this operation is safe to repeat, addressing the common scenario where setup scripts may be run multiple times during project configuration or troubleshooting.

s12_put_iam_policy()

Attach minimal-privilege inline policy and AWS managed policies to the IAM user.

This method implements the principle of least privilege by attaching only the specific permissions required for the intended use case. Inline policies are used instead of managed policies to ensure tight coupling between the user and their permissions, making cleanup more reliable and preventing permission drift.

Additionally, this method attaches any AWS managed policies specified in attached_policy_arn_list. It checks for existing attachments to avoid duplicate policy attachments.

The approach prevents the common security anti-pattern of using overly broad permissions for automation, reducing the blast radius if credentials are ever compromised.

s13_create_or_get_access_key(verbose: bool = True) → tuple[str, str]

Generate or retrieve access key credentials for the IAM user.

This method handles the critical security balance between automation and credential management. It reuses existing access keys when available to avoid key proliferation, but creates new ones when needed. The local storage of credentials enables consistent automation while keeping sensitive data out of version control.

The design addresses the common problem of credential lifecycle management in CI/CD scenarios, where regenerating keys frequently would break existing workflows, but never rotating them poses security risks.

Returns:

tuple[str, str]: Access key ID and secret access key for AWS authentication

s14_setup_github_secrets()

Configure GitHub repository secrets for seamless CI/CD integration.

This method automates the GitHub Secrets configuration, eliminating the manual step of copying credentials between AWS and GitHub. This automation is crucial for open source projects where multiple contributors need to be able to set up CI/CD without having direct access to AWS credentials.

The standardized secret naming convention ensures consistency across projects and follows GitHub Actions best practices. The automated approach reduces human error and ensures that all required environment variables are properly configured for AWS SDK authentication.

GitHub Secrets provide secure storage with encryption at rest and in transit, making them suitable for storing AWS credentials in open source repositories.

s21_delete_github_secrets()

Remove GitHub secrets to prevent credential accumulation.

This cleanup method addresses the important security practice of removing unused credentials from GitHub repositories. Leaving old credentials in GitHub Secrets creates unnecessary security exposure and can lead to confusion about which credentials are currently active.

The automated cleanup is particularly valuable for open source projects where manual credential management across multiple repositories becomes error-prone and inconsistent. This method ensures a clean slate for credential rotation or project decommissioning.

s22_delete_access_key()

Remove AWS access key to complete credential lifecycle management.

This method ensures that AWS access keys are properly deactivated and removed when no longer needed. Proper access key cleanup is essential for security hygiene and compliance, preventing the accumulation of unused long-lived credentials that could be compromised.

The method handles the common scenario where access keys may have already been deleted through other means, making the cleanup process robust and idempotent. This reliability is crucial for automated workflows that may be run multiple times or in different sequences.

s23_delete_iam_policy()

Remove IAM policies to clean up permissions and enable user deletion.

This method removes both the inline policy and any attached AWS managed policies from the IAM user, which is a prerequisite for user deletion in AWS IAM. The cleanup of all policies prevents permission artifacts from remaining in the AWS account and ensures that the IAM user can be completely removed.

The systematic approach to policy cleanup is important for maintaining a clean AWS environment and avoiding the common issue of orphaned policies that can accumulate over time in active development environments.

s24_delete_iam_user()

Remove IAM user to complete the full cleanup cycle.

This final cleanup method removes the IAM user itself, completing the full lifecycle management of the credential automation. This step is essential for preventing IAM user sprawl in AWS accounts and maintaining good security hygiene.

The complete cleanup capability allows projects to be easily decommissioned or to rotate credentials entirely by running the full teardown followed by a fresh setup. This approach is particularly valuable for open source projects with varying activity levels and contributor access patterns.