oidc-aws-github

Terraform module to configure GitHub Actions with AWS Identity Provider Open ID Connect (ODIC.) This allows GitHub Actions to authenticate against AWS without using any long-lived keys. This module provisions the necessary role and permissions as defined in the official GitHub docs.

Multiple repo configuration

This module allows you to create roles for lists of repos(subjects) and policies in the AWS account. Curently it only supports policies in the same account as the role being created. This is helpful for non-mono repo style groups as well as for large organizations where teams have separate repo ownership for the same AWS account.

Debugging features

The assume_role_names input allows you to assume the OIDC role and act as if you were the GitHub Actions pipeline. This is very useful for debugging while you're getting things setup. Note: we recommend removing this once your production ready so that all further changes are only applied via the pipeline.

Example GitHub Action

jobs:
  apply-terraform-main:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v2
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          role-to-assume: arn:aws:iam::{account_id}:role/ci/GithubCI-OIDC-TF
          aws-region: us-west-2
          role-duration-seconds: 1200 #can be up to the max set in the terraform module, defaults to 15 min

Requirements

Name	Version
aws	~> 4.0
tls	~> 4.0.3

Providers

Name	Version
aws	~> 4.0
tls	~> 4.0.3

Modules

Name	Source	Version
aws_oidc_github	./modules/aws-roles-oidc-github	n/a

Resources

Name	Type
aws_iam_openid_connect_provider.github	resource
tls_certificate.github	data source

Inputs

Name	Description	Type	Default	Required
aud_value	GitHub Aud	string	"sts.amazonaws.com"	no
github_tls_url	GitHub URL to perform TLS verification against.	string	"https://token.actions.githubusercontent.com"	no
max_session_duration	Maximum session duration in seconds. - by default assume role will be 15 minutes - when calling from actions you'll need to increase up to the maximum allowed hwere	number	3600	no
role_subject-repos_policies	role name to repos and policies mapping. role name as the key and object value for repo subjects ie "repo:organization/infrastructure:ref:refs/heads/main" as well as a list of policy arns ie ["Administrator"] and list of roles that can assume the new role for debugging	map(object({ role_path = optional(string) subject_repos = list(string) policy_arns = list(string) assume_role_names = optional(list(string)) }))	n/a	yes

Outputs

Name	Description
github_oidc_provider_arn	oidc provider arn to use for roles/policies
github_oidc_provider_url	oidc provider url to use for roles/policies
iam_role_arns	Roles that will be assumed by GitHub Action