feat: Add support for creating IAM GitHub OIDC provider and role(s) (#…

…308)

README.md

@@ -156,6 +156,37 @@ module "iam_eks_role" {
 }
 ```
 
+`iam-github-oidc-provider`:
+
+```hcl
+module "iam_github_oidc_provider" {
+  source    = "terraform-aws-modules/iam/aws//modules/iam-github-oidc-provider"
+
+  tags = {
+    Environment = "test"
+  }
+}
+```
+
+`iam-github-oidc-role`:
+
+```hcl
+module "iam_github_oidc_role" {
+  source    = "terraform-aws-modules/iam/aws//modules/iam-github-oidc-role"
+
+  # This should be updated to suit your organization, repository, references/branches, etc.
+  subjects = ["terraform-aws-modules/terraform-aws-iam:*"]
+
+  policies = {
+    S3ReadOnly = "arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"
+  }
+
+  tags = {
+    Environment = "test"
+  }
+}
+```
+
 `iam-group-with-assumable-roles-policy`:
 
 ```hcl

examples/iam-github-oidc/README.md

@@ -0,0 +1,63 @@
+# IAM GitHub OIDC
+
+- Creates an IAM identity provider for GitHub OIDC
+- Creates an IAM role that trust the IAM GitHub OIDC provider
+  - GitHub reference: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services
+  - AWS IAM role reference: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html#idp_oidc_Create_GitHub
+
+Note: an IAM provider is 1 per account per given URL. This module would be provisioned once per AWS account, and multiple roles created with this provider as the trusted identity (typically 1 role per GitHub repository).
+
+To run this example you need to execute:
+
+```bash
+$ terraform init
+$ terraform plan
+$ terraform apply
+```
+
+Run `terraform destroy` when you don't need these resources.
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.0 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 4.0 |
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_iam_github_oidc_provider"></a> [iam\_github\_oidc\_provider](#module\_iam\_github\_oidc\_provider) | ../../modules/iam-github-oidc-provider | n/a |
+| <a name="module_iam_github_oidc_provider_disabled"></a> [iam\_github\_oidc\_provider\_disabled](#module\_iam\_github\_oidc\_provider\_disabled) | ../../modules/iam-github-oidc-provider | n/a |
+| <a name="module_iam_github_oidc_role"></a> [iam\_github\_oidc\_role](#module\_iam\_github\_oidc\_role) | ../../modules/iam-github-oidc-role | n/a |
+| <a name="module_iam_github_oidc_role_disabled"></a> [iam\_github\_oidc\_role\_disabled](#module\_iam\_github\_oidc\_role\_disabled) | ../../modules/iam-github-oidc-role | n/a |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [aws_iam_policy.additional](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_policy) | resource |
+
+## Inputs
+
+No inputs.
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_iam_role_arn"></a> [iam\_role\_arn](#output\_iam\_role\_arn) | ARN of IAM role |
+| <a name="output_iam_role_name"></a> [iam\_role\_name](#output\_iam\_role\_name) | Name of IAM role |
+| <a name="output_iam_role_path"></a> [iam\_role\_path](#output\_iam\_role\_path) | Path of IAM role |
+| <a name="output_iam_role_unique_id"></a> [iam\_role\_unique\_id](#output\_iam\_role\_unique\_id) | Unique ID of IAM role |
+| <a name="output_provider_arn"></a> [provider\_arn](#output\_provider\_arn) | The ARN assigned by AWS for this provider |
+| <a name="output_provider_url"></a> [provider\_url](#output\_provider\_url) | The URL of the identity provider. Corresponds to the iss claim |
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

examples/iam-github-oidc/main.tf

@@ -0,0 +1,79 @@
+provider "aws" {
+  region = local.region
+}
+
+locals {
+  name   = "ex-iam-github-oidc"
+  region = "eu-west-1"
+
+  tags = {
+    Example    = local.name
+    GithubRepo = "terraform-aws-iam"
+    GithubOrg  = "terraform-aws-modules"
+  }
+}
+
+################################################################################
+# GitHub OIDC Provider
+# Note: This is one per AWS account
+################################################################################
+
+module "iam_github_oidc_provider" {
+  source = "../../modules/iam-github-oidc-provider"
+
+  tags = local.tags
+}
+
+module "iam_github_oidc_provider_disabled" {
+  source = "../../modules/iam-github-oidc-provider"
+
+  create = false
+}
+
+################################################################################
+# GitHub OIDC Role
+################################################################################
+
+module "iam_github_oidc_role" {
+  source = "../../modules/iam-github-oidc-role"
+
+  # This should be updated to suit your organization, repository, references/branches, etc.
+  subjects = ["terraform-aws-modules/terraform-aws-iam:*"]
+
+  policies = {
+    additional = aws_iam_policy.additional.arn
+    S3ReadOnly = "arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"
+  }
+
+  tags = local.tags
+}
+
+module "iam_github_oidc_role_disabled" {
+  source = "../../modules/iam-github-oidc-role"
+
+  create = false
+}
+
+################################################################################
+# Supporting Resources
+################################################################################
+
+resource "aws_iam_policy" "additional" {
+  name        = "${local.name}-additional"
+  description = "Additional test policy"
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Action = [
+          "ec2:Describe*",
+        ]
+        Effect   = "Allow"
+        Resource = "*"
+      },
+    ]
+  })
+
+  tags = local.tags
+}

examples/iam-github-oidc/outputs.tf

@@ -0,0 +1,37 @@
+################################################################################
+# GitHub OIDC Provider
+################################################################################
+
+output "provider_arn" {
+  description = "The ARN assigned by AWS for this provider"
+  value       = module.iam_github_oidc_provider.arn
+}
+
+output "provider_url" {
+  description = "The URL of the identity provider. Corresponds to the iss claim"
+  value       = module.iam_github_oidc_provider.url
+}
+
+################################################################################
+# GitHub OIDC Role
+################################################################################
+
+output "iam_role_arn" {
+  description = "ARN of IAM role"
+  value       = module.iam_github_oidc_role.arn
+}
+
+output "iam_role_name" {
+  description = "Name of IAM role"
+  value       = module.iam_github_oidc_role.name
+}
+
+output "iam_role_path" {
+  description = "Path of IAM role"
+  value       = module.iam_github_oidc_role.path
+}
+
+output "iam_role_unique_id" {
+  description = "Unique ID of IAM role"
+  value       = module.iam_github_oidc_role.unique_id
+}

examples/iam-github-oidc/versions.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">= 1.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 4.0"
+    }
+  }
+}

modules/iam-github-oidc-provider/README.md

@@ -0,0 +1,62 @@
+# IAM GitHub OIDC Provider
+
+Creates an IAM identity provider for GitHub OIDC. See more details here https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services
+
+Note: an IAM provider is 1 per account per given URL. This module would be provisioned once per AWS account, and multiple roles created with this provider as the trusted identity (typically 1 role per GitHub repository).
+
+## Usage
+
+```hcl
+module "iam_github_oidc_provider" {
+  source    = "terraform-aws-modules/iam/aws//modules/iam-github-oidc-provider"
+
+  tags = {
+    Environment = "test"
+  }
+}
+```
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.0 |
+| <a name="requirement_tls"></a> [tls](#requirement\_tls) | >= 3.0 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 4.0 |
+| <a name="provider_tls"></a> [tls](#provider\_tls) | >= 3.0 |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [aws_iam_openid_connect_provider.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_openid_connect_provider) | resource |
+| [aws_partition.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/partition) | data source |
+| [tls_certificate.this](https://registry.terraform.io/providers/hashicorp/tls/latest/docs/data-sources/certificate) | data source |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_client_id_list"></a> [client\_id\_list](#input\_client\_id\_list) | List of client IDs (also known as audiences) for the IAM OIDC provider. Defaults to STS service if not values are provided | `list(string)` | `[]` | no |
+| <a name="input_create"></a> [create](#input\_create) | Controls if resources should be created (affects all resources) | `bool` | `true` | no |
+| <a name="input_tags"></a> [tags](#input\_tags) | A map of tags to add to the resources created | `map(any)` | `{}` | no |
+| <a name="input_url"></a> [url](#input\_url) | The URL of the identity provider. Corresponds to the iss claim | `string` | `"https://token.actions.githubusercontent.com"` | no |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_arn"></a> [arn](#output\_arn) | The ARN assigned by AWS for this provider |
+| <a name="output_url"></a> [url](#output\_url) | The URL of the identity provider. Corresponds to the iss claim |
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

modules/iam-github-oidc-provider/main.tf

@@ -0,0 +1,21 @@
+data "aws_partition" "current" {}
+
+################################################################################
+# GitHub OIDC Provider
+################################################################################
+
+data "tls_certificate" "this" {
+  count = var.create ? 1 : 0
+
+  url = var.url
+}
+
+resource "aws_iam_openid_connect_provider" "this" {
+  count = var.create ? 1 : 0
+
+  url             = var.url
+  client_id_list  = coalescelist(var.client_id_list, ["sts.${data.aws_partition.current.dns_suffix}"])
+  thumbprint_list = data.tls_certificate.this[0].certificates[*].sha1_fingerprint
+
+  tags = var.tags
+}

modules/iam-github-oidc-provider/outputs.tf

@@ -0,0 +1,13 @@
+################################################################################
+# GitHub OIDC Provider
+################################################################################
+
+output "arn" {
+  description = "The ARN assigned by AWS for this provider"
+  value       = try(aws_iam_openid_connect_provider.this[0].arn, null)
+}
+
+output "url" {
+  description = "The URL of the identity provider. Corresponds to the iss claim"
+  value       = try(aws_iam_openid_connect_provider.this[0].url, null)
+}

modules/iam-github-oidc-provider/variables.tf

@@ -0,0 +1,23 @@
+variable "create" {
+  description = "Controls if resources should be created (affects all resources)"
+  type        = bool
+  default     = true
+}
+
+variable "tags" {
+  description = "A map of tags to add to the resources created"
+  type        = map(any)
+  default     = {}
+}
+
+variable "client_id_list" {
+  description = "List of client IDs (also known as audiences) for the IAM OIDC provider. Defaults to STS service if not values are provided"
+  type        = list(string)
+  default     = []
+}
+
+variable "url" {
+  description = "The URL of the identity provider. Corresponds to the iss claim"
+  type        = string
+  default     = "https://token.actions.githubusercontent.com"
+}

modules/iam-github-oidc-provider/versions.tf

@@ -0,0 +1,14 @@
+terraform {
+  required_version = ">= 1.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 4.0"
+    }
+    tls = {
+      source  = "hashicorp/tls"
+      version = ">= 3.0"
+    }
+  }
+}