gh-action-open-id-in-aws 0.1.1

Setup github action open id in AWS made easy.

---

Welcome to gh_action_open_id_in_aws Documentation

Overview

To use GitHub Actions to deploy applications to AWS, we have to setup the permission properly.

The old school method is to use Secret Environment Variable to store the AWS IAM User credentials. You can store access key abd secret key to the AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY environment variables. This is also the solution used by CircleCI.

Around Nov 2021, AWS and GitHub made the official Open ID Connection (OIDC) available. It simplifies the process of granting AWS permissions to GitHub Actions. This is the AWS recommended way, and AWS explicitly mentioned that it is NOT recommended to use long term IAM user credential for CI/CD.

This Python tool automates the process of setting up the GitHub action open id connection in AWS.

Reference:

• Configuring OpenID Connect in Amazon Web Services: GitHub official doc.

• Sample IAM OIDC CloudFormation Template: AWS maintained github action.

How to Use

To setup GitHub action open id connection in AWS the first time, you can do the following. This code snippet creates the necessary resources using AWS CloudFormation:

from gh_action_open_id_in_aws.impl import setup_github_action_open_id_connection_in_aws

setup_github_action_open_id_connection_in_aws(
    aws_profile="your_aws_profile_here",
    stack_name="cloudformation-stack-name-here",
    github_org="your-github-organization-name",
    github_repo="your_github_repo_name",
    role_name="the_iam_role_name_to_be_assumed_by_github_actions",
)

If you have more Github repo need to access the same AWS accounts, and you want to give them different permission, you can do this. This code snippet reuse the OIDC Provider you created before and create a different IAM role, and configure IAM policy permission for the new GitHub repo:

from boto_session_manager import BotoSesManager
from gh_action_open_id_in_aws.impl import setup_github_action_open_id_connection_in_aws

aws_profile = "your_aws_profile_here"
bsm = BotoSesManager(profile_name=aws_profile)
role_name = "the_new_iam_role_name_to_be_assumed_by_github_actions"

setup_github_action_open_id_connection_in_aws(
    aws_profile=aws_profile,
    stack_name="cloudformation-stack-name-here",
    github_org="your-github-organization-name",
    github_repo="another_github_repo_name",
    role_name=role_name,
    oidc_provider_arn=f"arn:aws:iam::{bsm.aws_account_id}:oidc-provider/token.actions.githubusercontent.com",
)

# let's say you want to give the new GitHub repo admin permission
bsm.iam_client.attach_role_policy(
    RoleName=role_name,
    PolicyArn="arn:aws:iam::aws:policy/AdministratorAccess",
)

Developer Guide

This section is for developers who want to contribute to this project.

What under the hood is a CloudFormation template. The gh_action_open_id_in_aws/cf.py file contains the AWS CDK source code. The cdk/cdk_synth.py script can generate the JSON CloudFormation template using AWS CDK. The developer then can copy the output template to the gh_action_open_id_in_aws/cft-{year}-{month}-{day}.json file and do local testing.

Install

gh_action_open_id_in_aws is released on PyPI, so all you need is to:

$ pip install gh-action-open-id-in-aws

To upgrade to latest version:

$ pip install --upgrade gh-action-open-id-in-aws