SamuelBagattin / terraform-aws-github-oidc-provider

Fully configurable terraform module to access AWS APIs from Github Actions through OpenID Connect.

AWS Github OIDC Provider Terraform Module

Purpose

This module allows you to create a GitHub OIDC provider and the associated IAM roles, that will help Github Actions to securely authenticate against the AWS API using an IAM role

Features

• Create an AWS OIDC provider for GitHub Actions
• Create one or more IAM role that can be assumed by GitHub Actions
• IAM roles can be scoped to :
  • One or more GitHub organisations
  • One or more GitHub repository
  • One or more branches in a repository

Feature	Status
Create a role for all repositories in a specific Github organisation	✅
Create a role specific to a repository for a specific organisation	✅
Create a role specific to a branch in a repository	✅
Create a role for multiple organisations/repositories/branches	✅
Create a role for organisations/repositories/branches selected by wildcard (e.g. feature/* branches)	✅
Create multiple roles for a repository, each one with his own set of branches	❌
Create the OIDC provider and multiple roles configurations in separate terraform root modules	✅

Usage

TL;DR :

module "aws_github_actions_oidc" {
  source  = "registry.terraform.io/SamuelBagattin/github-oidc-provider/aws"
  permissions = {
    "my-org" : { # Specify the GitHub organisation name
      role_name = "default-org-role" # Default role name for subsequent repositories
      allowed_branches = ["main"] # Default branches for subsequent repositories
      repositories = {
        "my-repository" = { # GitHub repository name
          role_name : "my-role" # IAM role specific to a repository
          allowed_branches : ["my-branch","my-other-branch", "feature/*"] # List of branches allowed to assume the specific role
        }
        "another-repository" = {} # Will inherit role_name and allowed_branches from the organisation
      }
    }
    # The wildcard "*" can be used to allow any repository or branch
    # Can be used also for organisations, but use it at your own risk
    "my-org": { # Allow an organisation
      repositories = {
        "*": { # Allow any repository
          role_name : "my-role"
          allowed_branches : ["*"] # Allow any branch
        }
      }
    }
  }
}

For more simple or detailed use cases, please refer to the following examples :

• Simple example
• Complete example
• Separated OIDC provider and IAM roles

AWS Github OIDC Provider Terraform Module

Purpose

This module allows you to create a Github OIDC provider for your AWS account, that will help Github Actions to securely authenticate against the AWS API using an IAM role

Requirements

Name	Version
terraform	>= 0.13.0
aws	> 3.0, ~> 4.0

Modules

Name	Source	Version
github_actions_assumable_role	./modules/github_actions_assumable_role	n/a

Resources

Name	Type
aws_iam_openid_connect_provider.github_actions	resource

Inputs

Name	Description	Type	Default	Required
create_iam_roles	Whether or not to create IAM roles.	bool	true	no
create_oidc_provider	Whether or not to create the associated oidc provider. If true, variable 'oidc_provider_arn' is required	bool	true	no
oidc_provider_arn	Used if create_oidc_provider is true	string	""	no
permissions	Permissions configuration. See 'Permissions specifications' below	map(any)	n/a	yes

Outputs

Name	Description
oidc_provider_arn	OIDC provider ARN
roles_arns	Roles to be assumed by github actions

Permissions specifications

permissions = map(object({
  "role_name": string, # optional, default: "githubActions-iamRole"
  "allowed_branches": list(string), # optional, default: ["master"]
  "repositories": map(object({ # optional, default: ["*":{}]
    "role_name": string, # optional, defaults to the organisation role_name
    "allowed_branches": list(string), # optional, defaults to the organisation allowed_branches
  }))
}))