AWS Github OIDC Provider Terraform Module

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.

We recommend using GitHub's OIDC provider to get short-lived credentials needed for your actions. Specifying role-to-assume without providing an aws-access-key-id or a web-identity-token-file will signal to the action that you wish to use the OIDC provider. The default session duration is 1 hour when using the OIDC provider to directly assume an IAM Role. The default session duration is 6 hours when using an IAM User to assume an IAM Role (by providing an aws-access-key-id, aws-secret-access-key, and a role-to-assume) . If you would like to adjust this you can pass a duration to role-duration-seconds, but the duration cannot exceed the maximum that was defined when the IAM Role was created. The default session name is GitHubActions, and you can modify it by specifying the desired name in role-session-name.

• How to Hook EKS

Features

1. Create an AWS OIDC provider for GitHub Actions
2. Create one or more IAM role that can be assumed by GitHub Actions
3. IAM roles can be scoped to :
   • One or more GitHub organisations
   • One or more GitHub repository
   • One or more branches in a repository
4. Use existing OIDC provider and roles with Terraform
   • Reference an existing OIDC provider by ARN
   • Reference an existing IAM role by ARN
   • Optionally attach policies to existing roles
   • Update repository access list for existing roles

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)	✅
Use an existing OIDC provider	✅
Use an existing IAM role	✅
Update repository access list for existing roles	✅

---

---

Documentation

• TFLint Rules

Usage example

IMPORTANT: The master branch is used in source just as an example. In your code, do not pin to master because there may be breaking changes between releases. Instead pin to the release tag (e.g. ?ref=tags/x.y.z) of one of our latest releases.

module "github-oidc" {
  source  = "terraform-module/github-oidc-provider/aws"
  version = "~> 1"

  create_oidc_provider = true
  create_oidc_role     = true

  repositories              = ["terraform-module/module-blueprint"]
  oidc_role_attach_policies = ["arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"]
}

Using a custom role path and permissions boundary

module "github-oidc" {
  source  = "terraform-module/github-oidc-provider/aws"
  version = "~> 1"

  create_oidc_provider = true
  create_oidc_role     = true

  # Set a custom path for the role (useful for organizing roles)
  iam_role_path = "/github-actions/"
  
  # Set a permissions boundary to limit maximum permissions
  iam_role_permissions_boundary = "arn:aws:iam::123456789012:policy/MyPermissionsBoundary"
  
  repositories              = ["terraform-module/module-blueprint"]
  oidc_role_attach_policies = ["arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"]
}

Using existing OIDC provider and/or role

module "github-oidc" {
  source  = "terraform-module/github-oidc-provider/aws"
  version = "~> 1"

  # Use existing OIDC provider
  create_oidc_provider = false
  oidc_provider_arn    = "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
  
  # Use existing role
  create_oidc_role     = false
  oidc_role_arn        = "arn:aws:iam::123456789012:role/my-existing-github-role"
  
  # Optionally attach policies to the existing role
  attach_policies_to_existing_role = true
  oidc_role_attach_policies = ["arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"]
}

Updating repository list for existing role

module "github-oidc" {
  source  = "terraform-module/github-oidc-provider/aws"
  version = "~> 1"

  # Use existing OIDC provider
  create_oidc_provider = false
  oidc_provider_arn    = "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
  
  # Reference existing role but update its repository list
  create_oidc_role           = false
  oidc_role_arn              = "arn:aws:iam::123456789012:role/my-existing-github-role"
  update_existing_role_policy = true
  
  # New repository list to update the role with
  repositories = [
    "my-org/repo1",
    "my-org/repo2",
    "another-org/some-repo:main"  # Only allow main branch
  ]
}

Examples

See examples directory for working examples to reference

• Examples Dir

Assumptions

Available features

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	>= 1
aws	>= 4.0

Providers

Name	Version
aws	>= 4.0

Modules

No modules.

Resources

Name	Type
aws_iam_openid_connect_provider.this	resource
aws_iam_role.existing_role_policy	resource
aws_iam_role.this	resource
aws_iam_role_policy_attachment.attach	resource
aws_iam_policy_document.this	data source
aws_iam_role.existing	data source

Inputs

Name	Description	Type	Default	Required
attach_policies_to_existing_role	Whether to attach the specified policies to an existing role when 'create_oidc_role' is false	bool	false	no
create_oidc_provider	Whether or not to create the associated oidc provider. If false, variable 'oidc_provider_arn' is required	bool	true	no
create_oidc_role	Whether or not to create the OIDC attached role	bool	true	no
github_thumbprint	GitHub OpenID TLS certificate thumbprint.	string	"6938fd4d98bab03faadb97b34396831e3780aea1"	no
iam_role_path	Path for the IAM role	string	"/"	no
iam_role_permissions_boundary	ARN of the permissions boundary to use for the IAM role	string	null	no
max_session_duration	Maximum session duration in seconds.	number	3600	no
oidc_provider_arn	ARN of the OIDC provider to use. Required if 'create_oidc_provider' is false	string	null	no
oidc_role_arn	ARN of the OIDC role to use. Required if 'create_oidc_role' is false	string	null	no
oidc_role_attach_policies	Attach policies to OIDC role.	list(string)	[]	no
repositories	List of GitHub organization/repository names authorized to assume the role.	list(string)	[]	no
role_description	(Optional) Description of the role.	string	"Role assumed by the GitHub OIDC provider."	no
role_name	(Optional, Forces new resource) Friendly name of the role.	string	"github-oidc-provider-aws"	no
tags	A mapping of tags to assign to all resources	map(string)	{}	no
update_existing_role_policy	Whether to update the assume role policy of an existing role with the repository list from 'repositories' variable	bool	false	no

Outputs

Name	Description
oidc_provider_arn	OIDC provider ARN
oidc_role_arn	CICD GitHub role ARN
oidc_role_name	CICD GitHub role name

📝 Guidelines

• 📝 Use a succinct title and description.
• 🐛 Bugs & feature requests can be be opened
• 📶 Support questions are better asked on Stack Overflow
• 😊 Be nice, civil and polite (as always).

License

Copyright 2022 Ivan Katliarhcuk

MIT Licensed. See LICENSE for full details.

How to Contribute

Submit a pull request

Authors

Currently maintained by Ivan Katliarchuk and these awesome contributors.

Terraform Registry

• Module

Resources

• AWS: create oidc
• Github: configure OIDC aws
• Github: OIDC cloud
• AWS creds github action
• AWS Docs
• Github OIDC
• Terraform: oidc complex
• Terraform: oidc simple
• Terraform: oidc

Clone Me

Create a repository using this template →