terraform-aws-github-action-federation-role

This repository contains a Terraform module for creating IAM Roles that can be assumed by GitHub Actions using web federation. Much of the work here is based off the excellent blog post by Aidan Steele.

PLEASE NOTE: This is as-of-yet (19th of September 2021) undocumented functionality, so this module should probably not be used in production environments as GitHub may change things before public release. See this GitHub Roadmap item for a current status of the feature.

This can be used in concert with this GitHub Action, which allows a workflow to assume a role. In fact, the tests that run as part of PR validation and release workflows for this very module use it!

For a full example of using the module, see my other repository here, where you can see a deployment for the OIDC provider and the IAM Role the workflows in this repository assume. (Please excuse the rather broad permissions assigned to the role; this is always run in a sandbox account that gets wiped frequently so the risk was minimal, though I do want to clean it up in the future.)

Pre-Requisites

The module requires that you set up an OIDC provider for GitHub in your AWS Account prior to use, the ARN of which is required by the oidc_provider_arn input variable. See below for an example Terraform resource that would provision this.

variable "github_repo_list" {
  type = list(string)
  description = "A list of GitHub orgs / users and repositories that the OIDC provider will trust. This must be in the format of 'org/repo'."
}

resource "aws_iam_openid_connect_provider" "github" {
  url = "https://vstoken.actions.githubusercontent.com"
  thumbprint_list = [ "a031c46782e6e6c662c2c87c76da9aa62ccabd8e" ]
  client_id_list = formatlist("https://github.com/%s", var.github_repo_list)
}

The module deliberately does not include this resource in order to be flexible around how you deploy it. For example, some organizations may wish to keep all definitions of GitHub Action assumed roles in one, tightly controlled repository. In this case, the OIDC provider may well be deployed in the same set of code as the role(s) themelves. In other cases, repository owners themselves may be responsible for writing the deployments to manage their roles; in this case, the provider would have to be kept elsewhere, since there can be only one deployed per AWS Account.

Module Usage

Requirements

Name	Version
aws	~> 3.54

Providers

Name	Version
aws	~> 3.54

Modules

No modules.

Resources

Name	Type
aws_iam_role.iam_role	resource
aws_iam_role_policy_attachment.policy_attachment	resource
aws_iam_policy_document.assume_role_policy	data source

Inputs

Name	Description	Type	Default	Required
github_branch_names	The names of the branches where actions running will be allowed to assume the role. This defaults to '*', which means that code running in any branch can assume the role.	list(string)	[ "*" ]	no
github_org_name	The name of the GitHub user or organization that owns the repository(ies) the role will use.	string	n/a	yes
github_repository_name	The name of the GitHub repository that will be allowed to assume the role. This defaults to '*', which will allow any repository within the org to assume the role. This is likely not a good use case for most deployments and may be changed in a future release.	string	"*"	no
iam_policy_arns	A list of IAM Policy ARNs that should be attached to the created IAM Role. Can be not specified if policy attachments will be handled elsewhere.	list(string)	[]	no
iam_role_boundary_policy_arn	If specified, the policy with the given ARN will be attached to the IAM Role as a boundary policy. If left as null (the default), no boundary policy will be attached.	string	null	no
iam_role_name	The name of the IAM Role to be created.	string	n/a	yes
oidc_provider_arn	The ARN for the existing OIDC IAM provider for GitHub.	string	n/a	yes

Outputs

Name	Description
assume_role_policy_json	The JSON result of the assume role policy document. This is mostly used for testing purposes.
iam_role_arn	The ARN of the generated IAM Role.