feat: add tags, iam_role_arns_map, and variable validation (Stage 1 prep for v2) (#11)

Author: josmo

README.md

@@ -35,7 +35,7 @@ module "aws_oidc_github" {
 }
 
 output "role_arn" {
-  value = module.aws_oidc_github.iam_role_arns["deploy-main"]
+  value = module.aws_oidc_github.iam_role_arns_map["deploy-main"]
 }
 ```
 
@@ -103,7 +103,7 @@ jobs:
       - run: aws sts get-caller-identity
 ```
 
-The `role-to-assume` value is the full ARN of one of the roles this module created — `module.aws_oidc_github.iam_role_arns[<key>]`.
+The `role-to-assume` value is the full ARN of one of the roles this module created — `module.aws_oidc_github.iam_role_arns_map[<role-name>]` (the map key matches the entry name you used in `role_subject-repos_policies`). The older `iam_role_arns` flat-list output is deprecated and will be removed in v2.
 
 ## Debugging with `assume_role_names`
 
@@ -142,45 +142,44 @@ The [`wrappers/`](./wrappers) directory contains thin wrapper modules pre-config
 ## Requirements
 
 | Name | Version |
-|------|---------|
+| ---- | ------- |
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.5.7 |
 | <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.0 |
-| <a name="requirement_tls"></a> [tls](#requirement\_tls) | >= 4.0.3 |
 
 ## Providers
 
 | Name | Version |
-|------|---------|
+| ---- | ------- |
 | <a name="provider_aws"></a> [aws](#provider\_aws) | >= 4.0 |
-| <a name="provider_tls"></a> [tls](#provider\_tls) | >= 4.0.3 |
 
 ## Modules
 
 | Name | Source | Version |
-|------|--------|---------|
+| ---- | ------ | ------- |
 | <a name="module_aws_oidc_github"></a> [aws\_oidc\_github](#module\_aws\_oidc\_github) | ./modules/aws-roles-oidc-github | n/a |
 
 ## Resources
 
 | Name | Type |
-|------|------|
+| ---- | ---- |
 | [aws_iam_openid_connect_provider.github](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_openid_connect_provider) | resource |
-| [tls_certificate.github](https://registry.terraform.io/providers/hashicorp/tls/latest/docs/data-sources/certificate) | data source |
 
 ## Inputs
 
 | Name | Description | Type | Default | Required |
-|------|-------------|------|---------|:--------:|
+| ---- | ----------- | ---- | ------- | :------: |
 | <a name="input_aud_value"></a> [aud\_value](#input\_aud\_value) | Audience claim required in the OIDC token. Defaults to the value the official aws-actions/configure-aws-credentials action sends. | `string` | `"sts.amazonaws.com"` | no |
 | <a name="input_github_tls_url"></a> [github\_tls\_url](#input\_github\_tls\_url) | GitHub OIDC issuer URL. Override only for GitHub Enterprise Server. | `string` | `"https://token.actions.githubusercontent.com"` | no |
 | <a name="input_max_session_duration"></a> [max\_session\_duration](#input\_max\_session\_duration) | Maximum session duration in seconds for every role created. Defaults to 1 hour. Increase up to 43200 (12h) if your workflows need longer sessions. | `number` | `3600` | no |
-| <a name="input_role_subject-repos_policies"></a> [role\_subject-repos\_policies](#input\_role\_subject-repos\_policies) | Map of IAM roles to create. The map key is the role name. Each value defines:<br/>  - `subject_repos`     : OIDC subject claims allowed to assume this role (e.g. "repo:my-org/my-repo:ref:refs/heads/main").<br/>  - `policy_arns`       : IAM policy ARNs to attach to the role.<br/>  - `role_path`         : (optional) IAM path for the role. Defaults to "/".<br/>  - `assume_role_names` : (optional) IAM role names in the same account that may also assume this role (useful for local debugging). | <pre>map(object({<br/>    role_path         = optional(string)<br/>    subject_repos     = list(string)<br/>    policy_arns       = list(string)<br/>    assume_role_names = optional(list(string))<br/>  }))</pre> | n/a | yes |
+| <a name="input_role_subject-repos_policies"></a> [role\_subject-repos\_policies](#input\_role\_subject-repos\_policies) | Map of IAM roles to create. The map key is the role name. Each value defines:<br/>  - `subject_repos`     : OIDC subject claims allowed to assume this role (e.g. "repo:my-org/my-repo:ref:refs/heads/main").<br/>  - `policy_arns`       : IAM policy ARNs to attach to the role.<br/>  - `role_path`         : (optional) IAM path for the role. Defaults to "/".<br/>  - `assume_role_names` : (optional) IAM role names in the same account that may also assume this role (useful for local debugging). | <pre>map(object({<br/>    role_path         = optional(string, "/")<br/>    subject_repos     = list(string)<br/>    policy_arns       = list(string)<br/>    assume_role_names = optional(list(string))<br/>  }))</pre> | n/a | yes |
+| <a name="input_tags"></a> [tags](#input\_tags) | Tags applied to the OIDC provider and every IAM role created by this module. | `map(string)` | `{}` | no |
 
 ## Outputs
 
 | Name | Description |
-|------|-------------|
+| ---- | ----------- |
 | <a name="output_github_oidc_provider_arn"></a> [github\_oidc\_provider\_arn](#output\_github\_oidc\_provider\_arn) | oidc provider arn to use for roles/policies |
 | <a name="output_github_oidc_provider_url"></a> [github\_oidc\_provider\_url](#output\_github\_oidc\_provider\_url) | oidc provider url to use for roles/policies |
-| <a name="output_iam_role_arns"></a> [iam\_role\_arns](#output\_iam\_role\_arns) | Roles that will be assumed by GitHub Action |
+| <a name="output_iam_role_arns"></a> [iam\_role\_arns](#output\_iam\_role\_arns) | Roles that will be assumed by GitHub Action. (Deprecated: use `iam_role_arns_map` instead; this output will be removed in v2.) |
+| <a name="output_iam_role_arns_map"></a> [iam\_role\_arns\_map](#output\_iam\_role\_arns\_map) | Map of role name to role ARN. Prefer this output; the flat `iam_role_arns` list will be removed in v2. |
 <!-- END_TF_DOCS -->

main.tf

@@ -5,33 +5,30 @@ terraform {
       source  = "hashicorp/aws"
       version = ">= 4.0"
     }
-    tls = {
-      source  = "hashicorp/tls"
-      version = ">= 4.0.3"
-    }
   }
 }
 
-
-data "tls_certificate" "github" {
-  url = var.github_tls_url
-}
-
 resource "aws_iam_openid_connect_provider" "github" {
-  url             = var.github_tls_url
-  client_id_list  = [var.aud_value]
-  thumbprint_list = [data.tls_certificate.github.certificates[0].sha1_fingerprint]
+  url            = var.github_tls_url
+  client_id_list = [var.aud_value]
+  # AWS stopped enforcing thumbprint verification for the GitHub OIDC issuer in
+  # mid-2023, but the AWS provider still requires a 40-char hex value. Pass the
+  # historical GitHub thumbprint as a placeholder; the actual trust is enforced
+  # by IAM via the provider URL, not this value.
+  thumbprint_list = ["6938fd4d98bab03faadb97b34396831e3780aea1"]
+  tags            = var.tags
 }
 
 module "aws_oidc_github" {
   for_each                 = var.role_subject-repos_policies
   source                   = "./modules/aws-roles-oidc-github"
   role_name                = each.key
-  role_path                = each.value.role_path != null ? each.value.role_path : "/"
+  role_path                = each.value.role_path
   github_repos             = each.value.subject_repos
   policy_arns              = each.value.policy_arns
   assume_role_names        = each.value.assume_role_names
   github_oidc_provider_arn = aws_iam_openid_connect_provider.github.arn
   github_oidc_provider_url = aws_iam_openid_connect_provider.github.url
   max_session_duration     = var.max_session_duration
+  tags                     = var.tags
 }

modules/aws-roles-oidc-github/README.md

@@ -8,15 +8,14 @@ Use this submodule directly **only** if you already manage your `aws_iam_openid_
 ## Requirements
 
 | Name | Version |
-|------|---------|
+| ---- | ------- |
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.5.7 |
 | <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.0 |
-| <a name="requirement_tls"></a> [tls](#requirement\_tls) | >= 4.0.3 |
 
 ## Providers
 
 | Name | Version |
-|------|---------|
+| ---- | ------- |
 | <a name="provider_aws"></a> [aws](#provider\_aws) | >= 4.0 |
 
 ## Modules
@@ -26,7 +25,7 @@ No modules.
 ## Resources
 
 | Name | Type |
-|------|------|
+| ---- | ---- |
 | [aws_iam_role.github_ci](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role) | resource |
 | [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
 | [aws_iam_policy_document.assume_role_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
@@ -35,7 +34,7 @@ No modules.
 ## Inputs
 
 | Name | Description | Type | Default | Required |
-|------|-------------|------|---------|:--------:|
+| ---- | ----------- | ---- | ------- | :------: |
 | <a name="input_assume_role_names"></a> [assume\_role\_names](#input\_assume\_role\_names) | IAM role names in the same account that may assume this role via sts:AssumeRole. Useful for local debugging; remove before production. | `list(string)` | `[]` | no |
 | <a name="input_github_oidc_provider_arn"></a> [github\_oidc\_provider\_arn](#input\_github\_oidc\_provider\_arn) | ARN of the GitHub OIDC provider that the IAM role will trust. | `string` | n/a | yes |
 | <a name="input_github_oidc_provider_url"></a> [github\_oidc\_provider\_url](#input\_github\_oidc\_provider\_url) | URL of the GitHub OIDC provider (e.g. https://token.actions.githubusercontent.com). | `string` | n/a | yes |
@@ -44,10 +43,11 @@ No modules.
 | <a name="input_policy_arns"></a> [policy\_arns](#input\_policy\_arns) | IAM policy ARNs to attach to the role (managed or customer-managed policies). | `list(string)` | n/a | yes |
 | <a name="input_role_name"></a> [role\_name](#input\_role\_name) | Name of the IAM role to create. Used verbatim — no prefixing or sanitization is applied. | `string` | n/a | yes |
 | <a name="input_role_path"></a> [role\_path](#input\_role\_path) | IAM path to create the role under. Must start and end with '/' (e.g. '/' or '/github/'). | `string` | n/a | yes |
+| <a name="input_tags"></a> [tags](#input\_tags) | Tags applied to the IAM role created by this submodule. | `map(string)` | `{}` | no |
 
 ## Outputs
 
 | Name | Description |
-|------|-------------|
+| ---- | ----------- |
 | <a name="output_iam_role_arn"></a> [iam\_role\_arn](#output\_iam\_role\_arn) | Role that will be assumed by GitHub Action |
 <!-- END_TF_DOCS -->

modules/aws-roles-oidc-github/main.tf

@@ -5,10 +5,6 @@ terraform {
       source  = "hashicorp/aws"
       version = ">= 4.0"
     }
-    tls = {
-      source  = "hashicorp/tls"
-      version = ">= 4.0.3"
-    }
   }
 }
 
@@ -56,4 +52,5 @@ resource "aws_iam_role" "github_ci" {
   max_session_duration = var.max_session_duration
   assume_role_policy   = data.aws_iam_policy_document.assume_role_policy.json
   managed_policy_arns  = var.policy_arns
+  tags                 = var.tags
 }

modules/aws-roles-oidc-github/variables.tf

@@ -21,6 +21,11 @@ variable "role_name" {
 variable "role_path" {
   type        = string
   description = "IAM path to create the role under. Must start and end with '/' (e.g. '/' or '/github/')."
+
+  validation {
+    condition     = can(regex("^/([a-zA-Z0-9._+-]+/)*$", var.role_path))
+    error_message = "role_path must start and end with '/' and only contain [a-zA-Z0-9._+-] segments (e.g. \"/\", \"/github/\", \"/teams/platform/\")."
+  }
 }
 
 variable "policy_arns" {
@@ -38,4 +43,15 @@ variable "max_session_duration" {
   type        = number
   default     = 3600
   description = "Maximum session duration in seconds for the role. Defaults to 1 hour. Increase up to 43200 (12h) if your workflows need longer sessions."
+
+  validation {
+    condition     = var.max_session_duration >= 3600 && var.max_session_duration <= 43200
+    error_message = "max_session_duration must be between 3600 (1h) and 43200 (12h) — AWS-enforced bounds."
+  }
+}
+
+variable "tags" {
+  type        = map(string)
+  default     = {}
+  description = "Tags applied to the IAM role created by this submodule."
 }

outputs.tf

@@ -1,8 +1,13 @@
 output "iam_role_arns" {
-  description = "Roles that will be assumed by GitHub Action"
+  description = "Roles that will be assumed by GitHub Action. (Deprecated: use `iam_role_arns_map` instead; this output will be removed in v2.)"
   value       = values(module.aws_oidc_github)[*].iam_role_arn
 }
 
+output "iam_role_arns_map" {
+  description = "Map of role name to role ARN. Prefer this output; the flat `iam_role_arns` list will be removed in v2."
+  value       = { for k, m in module.aws_oidc_github : k => m.iam_role_arn }
+}
+
 output "github_oidc_provider_arn" {
   description = "oidc provider arn to use for roles/policies"
   value       = aws_iam_openid_connect_provider.github.arn

variables.tf

@@ -1,6 +1,6 @@
 variable "role_subject-repos_policies" {
   type = map(object({
-    role_path         = optional(string)
+    role_path         = optional(string, "/")
     subject_repos     = list(string)
     policy_arns       = list(string)
     assume_role_names = optional(list(string))
@@ -12,6 +12,26 @@ variable "role_subject-repos_policies" {
       - `role_path`         : (optional) IAM path for the role. Defaults to "/".
       - `assume_role_names` : (optional) IAM role names in the same account that may also assume this role (useful for local debugging).
   EOT
+
+  validation {
+    condition = alltrue([
+      for v in var.role_subject-repos_policies : alltrue([for r in v.subject_repos : startswith(r, "repo:")])
+    ])
+    error_message = "Every subject_repos entry must start with \"repo:\" (e.g. \"repo:my-org/my-repo:ref:refs/heads/main\")."
+  }
+
+  validation {
+    condition = alltrue([
+      for v in var.role_subject-repos_policies : can(regex("^/([a-zA-Z0-9._+-]+/)*$", v.role_path))
+    ])
+    error_message = "Each role_path must start and end with '/' and only contain [a-zA-Z0-9._+-] segments (e.g. \"/\", \"/github/\", \"/teams/platform/\")."
+  }
+}
+
+variable "tags" {
+  type        = map(string)
+  default     = {}
+  description = "Tags applied to the OIDC provider and every IAM role created by this module."
 }
 
 variable "github_tls_url" {
@@ -30,4 +50,9 @@ variable "max_session_duration" {
   type        = number
   default     = 3600
   description = "Maximum session duration in seconds for every role created. Defaults to 1 hour. Increase up to 43200 (12h) if your workflows need longer sessions."
+
+  validation {
+    condition     = var.max_session_duration >= 3600 && var.max_session_duration <= 43200
+    error_message = "max_session_duration must be between 3600 (1h) and 43200 (12h) — AWS-enforced bounds."
+  }
 }