Skip to content

Latest commit

 

History

History
128 lines (90 loc) · 8.19 KB

README.md

File metadata and controls

128 lines (90 loc) · 8.19 KB
Raw

Terraform module AWS OIDC integration GitHub Actions

This Terraform module manages OpenID Connect (OIDC) integration between GitHub Actions and AWS.

Description

The module is strict on the claim checks to avoid that creating an OpenID connect integration opens your AWS account to any GitHub repo. However this strictness is not taking all the risk away. Ensure you familiarize yourself with OpenID Connect and the docs provided by GitHub and AWS. As always think about minimizing the privileges.

The module can manage the following:

  • The OpenID Connect identity provider for GitHub in your AWS account (via a submodule).
  • A role and assume role policy to check to check OIDC claims.

Manage the OIDC identity provider

The module provides an option for creating an OpenID connect provider. Using the internal provider module to create the OpenID Connect provider. This configuration will create the provider and output the ARN. This output can be passed to other instances of the module to setup roles for repositories on the same provider. Alternative you can create the OpenID connect provider via the resource aws_iam_openid_connect_provider or in case you have an existing one look-up via the data source aws_iam_openid_connect_provider.

Manage roles for a repo

The module creates a role with an assume role policy to check the OIDC claims for the given repo. Be default the policy is set to only allow actions running on the main branch and deny pull request actions. You can choose based on your need one (or more) of the default conditions to check. Additionally, a list of conditions can be provided. The role can only be assumed when all conditions evaluate to true. The following default conditions can be set.

  • allow_main : Allow GitHub Actions only running on the main branch.
  • allow_environment: Allow GitHub Actions only for environments, by setting github_environments you can limit to a dedicated environment.
  • deny_pull_request: Denies assuming the role for a pull request.
  • allow_all : Allow GitHub Actions for any claim for the repository. Be careful, this allows forks as well to assume the role!

Usages

In case there is not OpenID Connect provider already created in the AWS account, create one via the submodule.

module "oidc_provider" {
  source = "github.com/philips-labs/terraform-aws-github-oidc?ref=<version>//modules/provider"
}

Nest you ca pass the output the one or multiple instances of the module.

module "oidc_repo_s3" {
  source = "github.com/philips-labs/terraform-aws-github-oidc?ref=<version>"

  openid_connect_provider_arn = module.oidc_provider.openid_connect_provider.arn
  repo                        = var.repo_s3
  role_name                   = "repo-s3"

  # optional
  # override default conditions
  default_conditions          = ["allow_main"]

  # add extra conditions, will be merged with the default_conditions
  conditions                  = [{
    test = "StringLike"
    variable = "token.actions.githubusercontent.com:sub"
    values = ["repo:my-org/my-repo:pull_request"]
  }]
}

Examples

Check out the example for a full example of using the module.

Requirements

Name Version
terraform >= 1
aws >= 3

Providers

Name Version
aws >= 3
random n/a

Modules

No modules.

Resources

Name Type
aws_iam_role.main resource
aws_iam_role_policy_attachment.custom resource
random_string.random resource
aws_iam_policy_document.github_actions_assume_role_policy data source

Inputs

Name Description Type Default Required
account_ids Root users of these Accounts (id) would be given the permissions to assume the role created by this module. list(string) [] no
conditions (Optional) Additonal conditions for checking the OIDC claim. 
list(object({
    test     = string
    variable = string
    values   = list(string)
  }))
 [] no
custom_principal_arns List of IAM principals ARNs able to assume the role created by this module. list(string) [] no
default_conditions (Optional) Default condtions to apply, at least one of the following is madatory: 'allow_main', 'allow_environment', 'deny_pull_request' and 'allow_all'. list(string) 
[
  "allow_main",
  "deny_pull_request"
]
 no
github_environments (Optional) Allow GitHub action to deploy to all (default) or to one of the environments in the list. list(string) 
[
  "*"
]
 no
github_oidc_issuer OIDC issuer for GitHub Actions string "token.actions.githubusercontent.com" no
openid_connect_provider_arn Set the openid connect provider ARN when the provider is not managed by the module. string n/a yes
repo (Optional) GitHub repository to grant access to assume a role via OIDC. When the repo is set, a role will be created. string null no
role_max_session_duration Maximum session duration (in seconds) that you want to set for the specified role. number null no
role_name (Optional) role name of the created role, if not provided the namespace will be used. string null no
role_path (Optional) Path for the created role, requires repo is set. string "/github-actions/" no
role_permissions_boundary (Optional) Boundary for the created role, requires repo is set. string null no
role_policy_arns List of ARNs of IAM policies to attach to IAM role list(string) [] no

Outputs

Name Description
conditions The assume conditions added to the role.
role The crated role that can be assumed for the configured repository.

Contribution

We welcome contribution, please checkout the contribution guide. Be-aware we use pre commit hooks to update the docs.

Release

Releases are create automated from the main branch using conventional commit messages.

Contact

For question you can reach out to one of the maintainers.