Setup github action open id in AWS made easy.
Project description
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",
)
GitHub Actions for Multi-AWS Accounts CI/CD IAM Permission Best Practice
If you have multiple GitHub Repositories using GitHub Actions to deploy applications to multiple environments in multiple AWS accounts, here is the best practice:
Supposes that you have three workload AWS Accounts dev_aws, test_aws, prod_aws, and a devops_aws AWS account to store versioned code artifacts. These accounts could be different AWS accounts, either could be the same AWS account isolated by naming convention.
Supposes that you have one admin_repo GitHub repo to setup and test the cross AWS account IAM permission, and have multiple project GitHub repo project1_repo, project2_repo, etc …
Run the following code to setup the GitHub Action OIDC provider in devops_aws account.
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(
# this AWS principal should have permission to deploy CloudFormation and IAM
aws_profile="aws_profile_for_devops_aws",
stack_name="admin-repo-with-hyphen",
github_org="your-github-org",
github_repo="admin_repo",
role_name="admin_repo_role_name",
)
For each project GitHub repo, run the following code to setup the IAM role in devops_aws AWS account, only for the given GitHub repo. Of course you can use ${GitHubOrg}/* to give all GitHub repos in the same GitHub org the same permission, but this is not recommended.
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(
# this AWS principal should have permission to deploy CloudFormation and IAM
aws_profile="aws_profile_for_devops_aws",
stack_name="project1-repo-with-hyphen",
github_org="your-github-org",
github_repo="project1_repo",
role_name="project1_repo_role_name",
)
Then refer to the cross_aws_account_iam_role Python library to setup the cross AWS account IAM roles for the project1_repo_role_name in devops_aws AWS Account.
Note:
In general, there are two ways to setup cross AWS account IAM permission in GitHub actions:
ONLY setup OIDC provider and IAM role in devops_aws account, and let the IAM role in devops_aws account to assume IAM role in dev_aws, test_aws, prod_aws account. This is the recommended way.
Setup OIDC provider and IAM role in devops_aws, dev_aws, test_aws, prod_aws account. And use aws-actions/configure-aws-credentials GitHub Action to switch between them. This is NOT recommended, because it introduce more complexity and more IAM permission to manage in workload AWS accounts, which increases the risk.
name: ...
on: ...
jobs:
job_id:
runs-on: ubuntu-latest
steps:
..
- name: Configure AWS credentials for DEVOPS
uses: aws-actions/configure-aws-credentials@v3
with:
role-to-assume: arn:aws:iam::${{ secrets.DEVOPS_AWS_ACCOUNT_ID }}:role/devops_aws_iam_role
role-session-name: sample_role_session
aws-region: ${{ env.AWS_REGION }}
- name: Configure AWS credentials for DEV
uses: aws-actions/configure-aws-credentials@v3
with:
role-to-assume: arn:aws:iam::${{ secrets.DEV_AWS_ACCOUNT_ID }}:role/dev_aws_iam_role
role-session-name: sample_role_session
aws-region: ${{ env.AWS_REGION }}
- name: Configure AWS credentials for TEST
uses: aws-actions/configure-aws-credentials@v3
with:
role-to-assume: arn:aws:iam::${{ secrets.TEST_AWS_ACCOUNT_ID }}:role/test_aws_iam_role
role-session-name: sample_role_session
aws-region: ${{ env.AWS_REGION }}
- name: Configure AWS credentials for PROD
uses: aws-actions/configure-aws-credentials@v3
with:
role-to-assume: arn:aws:iam::${{ secrets.PROD_AWS_ACCOUNT_ID }}:role/prod_aws_iam_role
role-session-name: sample_role_session
aws-region: ${{ env.AWS_REGION }}
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for gh_action_open_id_in_aws-0.1.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | a8947666750b1447187298bc6b9ff85eabd782c4ec0b5db4ea9ab9281c8a5734 |
|
MD5 | 0e88f31f272b71b538c805c58d51494b |
|
BLAKE2b-256 | f9fa6ab8db03ed1d958adbf8264aa407c2d8a2096da3835b53840304901264ce |
Hashes for gh_action_open_id_in_aws-0.1.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a5349a6c1a92c31f4eb25607c692c5b11bc8ea2e58a0b609dc7471856018c9ad |
|
MD5 | 3597344a932cf943aa7eaf557563d375 |
|
BLAKE2b-256 | 9e96e5cec9bbb02bca6d119a7168f62ce35f3ccdce03d1ad59a2658ca63dad86 |