From f4d4ba193f6908e38d93339b77096d984a384bf5 Mon Sep 17 00:00:00 2001
From: Oliver Jarosch <oliver.jarosch@stackguardian.io>
Date: Fri, 14 Aug 2026 18:33:15 +0200
Subject: [PATCH 1/5] feat: add multi-role onboarding

---
 CHANGELOG.md                                  |   3 +
 main.tf                                       | 101 ++++++------
 outputs.tf                                    |   9 +
 stackguardian_role/README.md                  |   2 +-
 stackguardian_role/main.tf                    |   6 +
 .../team_onboarding_permissions.tf            |   2 +-
 .../tests/role_permissions.tofutest.hcl       |  45 +++++
 stackguardian_role/variables.tf               |  20 ++-
 stackguardian_role_assignment/README.md       |   6 +-
 stackguardian_role_assignment/main.tf         |   2 +-
 stackguardian_role_assignment/outputs.tf      |   9 +-
 .../tests/roles.tofutest.hcl                  |  35 ++++
 stackguardian_role_assignment/variables.tf    |  14 +-
 tests/multi_role_onboarding.tofutest.hcl      |  59 +++++++
 variables.tf                                  | 155 +++++++++++-------
 15 files changed, 334 insertions(+), 134 deletions(-)
 create mode 100644 outputs.tf
 create mode 100644 stackguardian_role_assignment/tests/roles.tofutest.hcl
 create mode 100644 tests/multi_role_onboarding.tofutest.hcl

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc5c287..784ee7a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Breaking
+- Replace the singleton root role and assignment inputs with keyed `roles` and `subjects` collections. Roles can independently scope workflow groups, cloud connectors, VCS connectors, and templates; each subject assignment now carries its complete roles list.
+
 ### Added
 - Add root-level AWS, Azure, and GCP identity wiring so Terraform creates the selected cloud identity and registers its generated identifiers with StackGuardian.
 - Add CLI-authenticated AWS and Azure onboarding and guarded destroy tasks with temporary targeted plans and StackGuardian token prompting.
diff --git a/main.tf b/main.tf
index 07cc5d4..04fd429 100644
--- a/main.tf
+++ b/main.tf
@@ -5,87 +5,87 @@ module "stackguardian_workflow_group" {
 }
 
 locals {
-  cloud_connectors = {
-    for connector in var.cloud_connectors : connector.name => connector
-  }
-
   aws_provider_region = try([
-    for connector in var.cloud_connectors : connector.aws_region
+    for connector in values(var.cloud_connectors) : coalesce(connector.aws_region, "eu-central-1")
     if contains(["AWS_STATIC", "AWS_RBAC", "AWS_OIDC"], connector.kind)
   ][0], "eu-central-1")
-  has_gcp_connector = anytrue([for connector in var.cloud_connectors : connector.kind == "GCP_OIDC"])
+  has_gcp_connector = anytrue([for connector in values(var.cloud_connectors) : connector.kind == "GCP_OIDC"])
 }
 
-module "aws_rbac" {
-  for_each = {
-    for name, connector in local.cloud_connectors : name => connector if connector.kind == "AWS_RBAC"
+# Terraform 1.5 cannot express cross-variable validation. This resource makes
+# collection-wide violations hard plan failures rather than advisory checks.
+resource "terraform_data" "validate_onboarding" {
+  input = {
+    cloud_connector_keys = keys(var.cloud_connectors)
+    vcs_connector_keys   = nonsensitive(keys(var.vcs_connectors))
+  }
+
+  lifecycle {
+    precondition {
+      condition     = length(setintersection(toset(keys(var.cloud_connectors)), toset(nonsensitive(keys(var.vcs_connectors))))) == 0
+      error_message = "cloud_connectors and vcs_connectors must not use the same key."
+    }
   }
+}
+
+module "aws_rbac" {
+  for_each = { for name, connector in var.cloud_connectors : name => connector if connector.kind == "AWS_RBAC" }
 
   source = "./aws_rbac"
 
   iam_role_name       = each.value.iam_role_name
   role_external_id    = each.value.aws_external_id
-  policy_arn          = each.value.policy_arn
-  trusted_account_ids = coalesce(try(each.value.trusted_account_ids, null), ["476299211833", "163602625436"])
+  policy_arn          = coalesce(each.value.policy_arn, "arn:aws:iam::aws:policy/ReadOnlyAccess")
+  trusted_account_ids = coalesce(each.value.trusted_account_ids, ["476299211833", "163602625436"])
 }
 
 module "aws_static" {
-  for_each = {
-    for name, connector in local.cloud_connectors : name => connector if connector.kind == "AWS_STATIC"
-  }
+  for_each = { for name, connector in var.cloud_connectors : name => connector if connector.kind == "AWS_STATIC" }
 
   source = "./aws_static"
 
-  aws_region               = each.value.aws_region
-  iam_user                 = coalesce(try(each.value.iam_user_name, null), each.value.name)
+  aws_region               = coalesce(each.value.aws_region, "eu-central-1")
+  iam_user                 = coalesce(each.value.iam_user_name, each.key)
   allow_static_credentials = each.value.allow_static_credentials
 }
 
 module "aws_oidc" {
-  for_each = {
-    for name, connector in local.cloud_connectors : name => connector if connector.kind == "AWS_OIDC"
-  }
+  for_each = { for name, connector in var.cloud_connectors : name => connector if connector.kind == "AWS_OIDC" }
 
   source = "./aws_oidc"
 
-  aws_region             = each.value.aws_region
+  aws_region             = coalesce(each.value.aws_region, "eu-central-1")
   iam_role_name          = each.value.iam_role_name
   stackguardian_org_name = var.stackguardian_org_name
-  policy_arn             = each.value.policy_arn
+  policy_arn             = coalesce(each.value.policy_arn, "arn:aws:iam::aws:policy/ReadOnlyAccess")
 }
 
 module "azure_oidc" {
-  for_each = {
-    for name, connector in local.cloud_connectors : name => connector if connector.kind == "AZURE_OIDC"
-  }
+  for_each = { for name, connector in var.cloud_connectors : name => connector if connector.kind == "AZURE_OIDC" }
 
   source = "./azure_oidc"
 
   subscription_id          = each.value.azure_subscription_id
   tenant_id                = each.value.azure_tenant_id
-  application_display_name = coalesce(try(each.value.application_display_name, null), each.value.name)
+  application_display_name = coalesce(each.value.application_display_name, each.key)
   stackguardian_org_name   = var.stackguardian_org_name
-  role_definition_name     = each.value.role_definition_name
+  role_definition_name     = coalesce(each.value.role_definition_name, "Contributor")
 }
 
 module "azure_static" {
-  for_each = {
-    for name, connector in local.cloud_connectors : name => connector if connector.kind == "AZURE_STATIC"
-  }
+  for_each = { for name, connector in var.cloud_connectors : name => connector if connector.kind == "AZURE_STATIC" }
 
   source = "./azure_static"
 
   subscription_id          = each.value.azure_subscription_id
   tenant_id                = each.value.azure_tenant_id
-  application_display_name = coalesce(try(each.value.application_display_name, null), each.value.name)
-  role_definition_name     = each.value.role_definition_name
+  application_display_name = coalesce(each.value.application_display_name, each.key)
+  role_definition_name     = coalesce(each.value.role_definition_name, "Contributor")
   allow_static_credentials = each.value.allow_static_credentials
 }
 
 module "gcp_oidc" {
-  for_each = {
-    for name, connector in local.cloud_connectors : name => connector if connector.kind == "GCP_OIDC"
-  }
+  for_each = { for name, connector in var.cloud_connectors : name => connector if connector.kind == "GCP_OIDC" }
 
   source = "./gcp_oidc"
 
@@ -94,20 +94,20 @@ module "gcp_oidc" {
   service_account_id                  = each.value.gcp_service_account_id
   workload_identity_pool_id           = each.value.gcp_workload_pool_id
   workload_identity_pool_provider_id  = each.value.gcp_provider_id
-  workload_identity_pool_display_name = each.value.name
-  project_role                        = each.value.gcp_project_role
+  workload_identity_pool_display_name = each.key
+  project_role                        = coalesce(each.value.gcp_project_role, "roles/owner")
 }
 
 module "stackguardian_connector_cloud" {
-  for_each = local.cloud_connectors
+  for_each = var.cloud_connectors
 
   source                   = "./stackguardian_connector_cloud"
-  connector_name           = each.value.name
+  connector_name           = each.key
   connector_kind           = each.value.kind
-  allow_static_credentials = try(each.value.allow_static_credentials, false)
+  allow_static_credentials = coalesce(each.value.allow_static_credentials, false)
   aws_access_key_id        = each.value.kind == "AWS_STATIC" ? module.aws_static[each.key].access_key_id : null
   aws_secret_access_key    = each.value.kind == "AWS_STATIC" ? module.aws_static[each.key].secret_access_key : null
-  aws_region               = each.value.kind == "AWS_STATIC" ? each.value.aws_region : null
+  aws_region               = each.value.kind == "AWS_STATIC" ? coalesce(each.value.aws_region, "eu-central-1") : null
   azure_tenant_id          = contains(["AZURE_STATIC", "AZURE_OIDC"], each.value.kind) ? each.value.azure_tenant_id : null
   azure_subscription_id    = contains(["AZURE_STATIC", "AZURE_OIDC"], each.value.kind) ? each.value.azure_subscription_id : null
   azure_client_id          = contains(["AZURE_STATIC", "AZURE_OIDC"], each.value.kind) ? (each.value.kind == "AZURE_STATIC" ? module.azure_static[each.key].client_id : module.azure_oidc[each.key].client_id) : null
@@ -123,19 +123,22 @@ module "stackguardian_connector_vcs" {
 }
 
 module "stackguardian_role" {
+  for_each = var.roles
+
   source           = "./stackguardian_role"
   org_name         = var.stackguardian_org_name
-  role_name        = var.role_name
-  cloud_connectors = [for connector in var.cloud_connectors : connector.name]
-  vcs_connectors   = [for key in keys(var.vcs_connectors) : var.vcs_connectors[key].name]
-  workflow_groups  = var.workflow_groups
-  template_list    = var.template_list
+  role_name        = each.key
+  workflow_groups  = [for name in each.value.workflow_groups : module.stackguardian_workflow_group[name].workflow_groups]
+  cloud_connectors = [for name in each.value.cloud_connectors : module.stackguardian_connector_cloud[name].connector_name]
+  vcs_connectors   = [for name in each.value.vcs_connectors : nonsensitive(module.stackguardian_connector_vcs.connector_vcs[index(nonsensitive(keys(var.vcs_connectors)), name)])]
+  template_list    = each.value.template_list
 }
 
 module "stackguardian_role_assignment" {
+  for_each = var.subjects
+
   source      = "./stackguardian_role_assignment"
-  role_name   = var.role_name
-  subject     = var.subject
-  entity_type = var.entity_type
-  depends_on  = [module.stackguardian_role]
+  roles       = [for name in each.value.roles : module.stackguardian_role[name].role]
+  subject     = each.key
+  entity_type = each.value.entity_type
 }
diff --git a/outputs.tf b/outputs.tf
new file mode 100644
index 0000000..afbc154
--- /dev/null
+++ b/outputs.tf
@@ -0,0 +1,9 @@
+output "role_permissions" {
+  description = "Generated permission documents keyed by role name."
+  value       = { for name, role in module.stackguardian_role : name => role.allowed_permissions }
+}
+
+output "subject_roles" {
+  description = "Assigned role names keyed by subject."
+  value       = { for subject, assignment in module.stackguardian_role_assignment : subject => assignment.roles }
+}
diff --git a/stackguardian_role/README.md b/stackguardian_role/README.md
index a1c0d31..7640fd1 100644
--- a/stackguardian_role/README.md
+++ b/stackguardian_role/README.md
@@ -1,6 +1,6 @@
 # StackGuardian Role v4
 
-Creates a StackGuardian `rolev4` resource using workflow, connector, and template collections. Configure the StackGuardian provider in the calling root. Existing `stackguardian_role` state must be removed and imported at the v4 address; see the root README.
+Creates a StackGuardian `rolev4` resource using workflow, connector, and template collections. At least one scope category must be non-empty; empty categories produce no permissions. Configure the StackGuardian provider in the calling root. Existing `stackguardian_role` state must be removed and imported at the v4 address; see the root README.
 
 ```hcl
 module "role" {
diff --git a/stackguardian_role/main.tf b/stackguardian_role/main.tf
index 95800c2..4abfb80 100644
--- a/stackguardian_role/main.tf
+++ b/stackguardian_role/main.tf
@@ -4,4 +4,10 @@ resource "stackguardian_rolev4" "role" {
   tags                = ["terraform", "scoped-access"]
   allowed_permissions = local.team_onboarding_permissions
 
+  lifecycle {
+    precondition {
+      condition     = length(concat(var.workflow_groups, var.cloud_connectors, var.vcs_connectors, var.template_list)) > 0
+      error_message = "A role must grant at least one workflow group, connector, or template."
+    }
+  }
 }
diff --git a/stackguardian_role/team_onboarding_permissions.tf b/stackguardian_role/team_onboarding_permissions.tf
index 543bfcf..55c8a40 100644
--- a/stackguardian_role/team_onboarding_permissions.tf
+++ b/stackguardian_role/team_onboarding_permissions.tf
@@ -6,7 +6,7 @@ locals {
   template_paths                 = var.template_list
   template_wildcard_paths        = [for template in local.template_paths : ".*"]
 
-  workflow_permissions = {
+  workflow_permissions = length(var.workflow_groups) == 0 ? {} : {
     "GET/api/v1/orgs/${var.org_name}/wfgrps/<wfGrp>/"                                                                = { name = "GetWorkflowGroup", paths = { "<wfGrp>" = local.workflow_group_paths } }
     "PATCH/api/v1/orgs/${var.org_name}/wfgrps/<wfGrp>/"                                                              = { name = "UpdateWorkflowGroup", paths = { "<wfGrp>" = local.workflow_group_paths } }
     "DELETE/api/v1/orgs/${var.org_name}/wfgrps/<wfGrp>/"                                                             = { name = "DeleteWorkflowGroup", paths = { "<wfGrp>" = local.workflow_group_paths } }
diff --git a/stackguardian_role/tests/role_permissions.tofutest.hcl b/stackguardian_role/tests/role_permissions.tofutest.hcl
index 5c4ffff..a6dda4f 100644
--- a/stackguardian_role/tests/role_permissions.tofutest.hcl
+++ b/stackguardian_role/tests/role_permissions.tofutest.hcl
@@ -42,3 +42,48 @@ run "builds_scoped_v4_permissions" {
     error_message = "Role permissions must not include broad administrative endpoints."
   }
 }
+
+run "omits_workflow_permissions_for_connector_only_role" {
+  command = plan
+
+  variables {
+    workflow_groups  = []
+    cloud_connectors = ["cloud-one"]
+    vcs_connectors   = []
+    template_list    = []
+  }
+
+  assert {
+    condition     = alltrue([for url in keys(output.allowed_permissions) : !strcontains(url, "/wfgrps/")])
+    error_message = "A role without workflow groups must not receive workflow permissions."
+  }
+}
+
+run "omits_workflow_permissions_for_template_only_role" {
+  command = plan
+
+  variables {
+    workflow_groups  = []
+    cloud_connectors = []
+    vcs_connectors   = []
+    template_list    = ["template-one"]
+  }
+
+  assert {
+    condition     = tolist(keys(output.allowed_permissions)) == tolist(["DELETE/api/v1/templatetypes/<templateType>/<org>/<template>/", "GET/api/v1/templatetypes/<templateType>/<org>/<template>/", "PATCH/api/v1/templatetypes/<templateType>/<org>/<template>/"])
+    error_message = "A template-only role must contain only template permissions."
+  }
+}
+
+run "rejects_role_without_scopes" {
+  command = plan
+
+  variables {
+    workflow_groups  = []
+    cloud_connectors = []
+    vcs_connectors   = []
+    template_list    = []
+  }
+
+  expect_failures = [stackguardian_rolev4.role]
+}
diff --git a/stackguardian_role/variables.tf b/stackguardian_role/variables.tf
index 9b73735..efbe22e 100644
--- a/stackguardian_role/variables.tf
+++ b/stackguardian_role/variables.tf
@@ -11,40 +11,44 @@ variable "org_name" {
 variable "workflow_groups" {
   type        = list(string)
   description = "Workflow groups granted to the role."
+  default     = []
 
   validation {
-    condition     = length(var.workflow_groups) > 0 && alltrue([for name in var.workflow_groups : length(trimspace(name)) > 0])
-    error_message = "workflow_groups must contain at least one non-empty name."
+    condition     = length(var.workflow_groups) == length(toset(var.workflow_groups)) && alltrue([for name in var.workflow_groups : length(trimspace(name)) > 0])
+    error_message = "workflow_groups must contain unique, non-empty names."
   }
 }
 
 variable "cloud_connectors" {
   type        = list(string)
   description = "Cloud connector names granted to the role."
+  default     = []
 
   validation {
-    condition     = alltrue([for name in var.cloud_connectors : length(trimspace(name)) > 0])
-    error_message = "cloud_connectors must contain only non-empty names."
+    condition     = length(var.cloud_connectors) == length(toset(var.cloud_connectors)) && alltrue([for name in var.cloud_connectors : length(trimspace(name)) > 0])
+    error_message = "cloud_connectors must contain unique, non-empty names."
   }
 }
 
 variable "vcs_connectors" {
   type        = list(string)
   description = "VCS connector names granted to the role."
+  default     = []
 
   validation {
-    condition     = alltrue([for name in var.vcs_connectors : length(trimspace(name)) > 0])
-    error_message = "vcs_connectors must contain only non-empty names."
+    condition     = length(var.vcs_connectors) == length(toset(var.vcs_connectors)) && alltrue([for name in var.vcs_connectors : length(trimspace(name)) > 0])
+    error_message = "vcs_connectors must contain unique, non-empty names."
   }
 }
 
 variable "template_list" {
   type        = list(string)
   description = "Template names granted to the role."
+  default     = []
 
   validation {
-    condition     = alltrue([for name in var.template_list : length(trimspace(name)) > 0])
-    error_message = "template_list must contain only non-empty names."
+    condition     = length(var.template_list) == length(toset(var.template_list)) && alltrue([for name in var.template_list : length(trimspace(name)) > 0])
+    error_message = "template_list must contain unique, non-empty names."
   }
 }
 
diff --git a/stackguardian_role_assignment/README.md b/stackguardian_role_assignment/README.md
index 4056e93..578f151 100644
--- a/stackguardian_role_assignment/README.md
+++ b/stackguardian_role_assignment/README.md
@@ -1,14 +1,14 @@
 # StackGuardian Role Assignment
 
-Assigns one role through the provider v1.12 `roles` list. Configure the StackGuardian provider in the calling root.
+Assigns one or more roles through the provider v1.12 `roles` list. Configure the StackGuardian provider in the calling root.
 
 ```hcl
 module "assignment" {
   source      = "./stackguardian_role_assignment"
-  role_name   = "developer"
+  roles       = ["developer", "auditor"]
   subject     = "developer@example.invalid"
   entity_type = "EMAIL"
 }
 ```
 
-Outputs: `user`, `role`.
+Outputs: `user`, `roles`.
diff --git a/stackguardian_role_assignment/main.tf b/stackguardian_role_assignment/main.tf
index c362765..d5102be 100644
--- a/stackguardian_role_assignment/main.tf
+++ b/stackguardian_role_assignment/main.tf
@@ -1,5 +1,5 @@
 resource "stackguardian_role_assignment" "sg_user" {
   user_id     = var.subject
   entity_type = var.entity_type
-  roles       = [var.role_name]
+  roles       = var.roles
 }
diff --git a/stackguardian_role_assignment/outputs.tf b/stackguardian_role_assignment/outputs.tf
index ee04cc4..8bc9305 100644
--- a/stackguardian_role_assignment/outputs.tf
+++ b/stackguardian_role_assignment/outputs.tf
@@ -1,8 +1,9 @@
 output "user" {
-  description = "User or group assigned to the role."
+  description = "User or group assigned to the roles."
   value       = var.subject
 }
-output "role" {
-  description = "Role assigned to the user or group."
-  value       = var.role_name
+
+output "roles" {
+  description = "Roles assigned to the user or group."
+  value       = var.roles
 }
diff --git a/stackguardian_role_assignment/tests/roles.tofutest.hcl b/stackguardian_role_assignment/tests/roles.tofutest.hcl
new file mode 100644
index 0000000..0183dfb
--- /dev/null
+++ b/stackguardian_role_assignment/tests/roles.tofutest.hcl
@@ -0,0 +1,35 @@
+mock_provider "stackguardian" {}
+
+variables {
+  subject = "developer@example.invalid"
+  roles   = ["developer", "auditor"]
+}
+
+run "assigns_all_roles_in_one_resource" {
+  command = plan
+
+  assert {
+    condition     = output.user == "developer@example.invalid" && output.roles == tolist(["developer", "auditor"])
+    error_message = "One subject assignment must preserve every requested role."
+  }
+}
+
+run "rejects_empty_role_list" {
+  command = plan
+
+  variables {
+    roles = []
+  }
+
+  expect_failures = [var.roles]
+}
+
+run "rejects_duplicate_role_list" {
+  command = plan
+
+  variables {
+    roles = ["developer", "developer"]
+  }
+
+  expect_failures = [var.roles]
+}
diff --git a/stackguardian_role_assignment/variables.tf b/stackguardian_role_assignment/variables.tf
index 86d8223..1b93f5e 100644
--- a/stackguardian_role_assignment/variables.tf
+++ b/stackguardian_role_assignment/variables.tf
@@ -1,6 +1,6 @@
 variable "subject" {
   type        = string
-  description = "Local email or qualified SSO email/group subject receiving the role."
+  description = "Local email or qualified SSO email/group subject receiving the roles."
 
   validation {
     condition     = can(regex("^([^/@\\s]+/[^/\\s]+|[^@\\s]+@[^@\\s]+\\.[^@\\s]+)$", var.subject))
@@ -11,6 +11,7 @@ variable "subject" {
 variable "entity_type" {
   type        = string
   description = "Subject type: EMAIL or GROUP."
+  default     = "EMAIL"
 
   validation {
     condition     = contains(["EMAIL", "GROUP"], var.entity_type)
@@ -18,7 +19,12 @@ variable "entity_type" {
   }
 }
 
-variable "role_name" {
-  type        = string
-  description = "Single StackGuardian role assigned to the subject."
+variable "roles" {
+  type        = list(string)
+  description = "StackGuardian roles assigned to the subject."
+
+  validation {
+    condition     = length(var.roles) > 0 && length(var.roles) == length(toset(var.roles)) && alltrue([for role in var.roles : length(trimspace(role)) > 0])
+    error_message = "roles must contain one or more unique, non-empty role names."
+  }
 }
diff --git a/tests/multi_role_onboarding.tofutest.hcl b/tests/multi_role_onboarding.tofutest.hcl
new file mode 100644
index 0000000..a99aa96
--- /dev/null
+++ b/tests/multi_role_onboarding.tofutest.hcl
@@ -0,0 +1,59 @@
+mock_provider "stackguardian" {}
+
+variables {
+  stackguardian_api_key  = "sgu_testkey"
+  stackguardian_org_name = "contract-org"
+  workflow_groups        = ["engineering", "platform"]
+  vcs_connectors = {
+    github = {
+      kind = "GITHUB_COM"
+      name = "github"
+      github = {
+        githubCreds = "test-credential"
+      }
+    }
+  }
+  roles = {
+    developer = {
+      workflow_groups = ["engineering"]
+      vcs_connectors  = ["github"]
+    }
+    auditor = {
+      workflow_groups = ["engineering", "platform"]
+      vcs_connectors  = ["github"]
+    }
+  }
+  subjects = {
+    "developer@example.invalid" = {
+      roles = ["developer", "auditor"]
+    }
+    "okta/platform-engineers" = {
+      entity_type = "GROUP"
+      roles       = ["auditor"]
+    }
+  }
+}
+
+run "provisions_keyed_roles_and_multi_role_subjects" {
+  command = plan
+
+  assert {
+    condition     = tolist(output.role_permissions["developer"]["GET/api/v1/orgs/contract-org/wfgrps/<wfGrp>/"].paths["<wfGrp>"]) == tolist(["engineering", "engineering/.*"])
+    error_message = "Roles must resolve workflow-group references through keyed module instances."
+  }
+
+  assert {
+    condition     = tolist(output.role_permissions["auditor"]["GET/api/v1/orgs/contract-org/integrations/<integration>/"].paths["<integration>"]) == tolist(["github"])
+    error_message = "Roles must resolve keyed VCS connector references."
+  }
+
+  assert {
+    condition     = tolist(output.subject_roles["developer@example.invalid"]) == tolist(["developer", "auditor"])
+    error_message = "A subject must receive all configured roles in one assignment."
+  }
+
+  assert {
+    condition     = tolist(output.subject_roles["okta/platform-engineers"]) == tolist(["auditor"])
+    error_message = "A group subject must receive its configured role."
+  }
+}
diff --git a/variables.tf b/variables.tf
index 6f7ac66..ea0460f 100644
--- a/variables.tf
+++ b/variables.tf
@@ -32,73 +32,94 @@ variable "stackguardian_api_uri" {
 
 variable "workflow_groups" {
   type        = list(string)
-  description = "Workflow groups created and granted to the role."
+  description = "Workflow groups created by this root."
+  default     = []
 
   validation {
-    condition     = length(var.workflow_groups) > 0 && alltrue([for name in var.workflow_groups : length(trimspace(name)) > 0])
-    error_message = "workflow_groups must contain at least one non-empty name."
+    condition     = length(var.workflow_groups) == length(toset(var.workflow_groups)) && alltrue([for name in var.workflow_groups : length(trimspace(name)) > 0])
+    error_message = "workflow_groups must contain unique, non-empty names."
   }
 }
 
 variable "cloud_connectors" {
-  description = "Cloud connectors managed by the root stack. Terraform creates and registers the selected cloud identity; static kinds are legacy-only."
-  type = list(object({
-    name                     = string
+  description = "Keyed cloud connectors. Terraform creates and registers the selected cloud identity; static kinds are legacy-only."
+  type = map(object({
     kind                     = string
+    allow_static_credentials = optional(bool)
+    aws_region               = optional(string)
     iam_role_name            = optional(string)
     iam_user_name            = optional(string)
-    policy_arn               = optional(string, "arn:aws:iam::aws:policy/ReadOnlyAccess")
+    policy_arn               = optional(string)
     aws_external_id          = optional(string)
     trusted_account_ids      = optional(list(string))
-    role_definition_name     = optional(string, "Contributor")
+    azure_subscription_id    = optional(string)
+    azure_tenant_id          = optional(string)
     application_display_name = optional(string)
+    role_definition_name     = optional(string)
+    gcp_project_id           = optional(string)
     gcp_service_account_id   = optional(string)
     gcp_workload_pool_id     = optional(string)
     gcp_provider_id          = optional(string)
-    gcp_project_role         = optional(string, "roles/owner")
-    gcp_project_id           = optional(string)
-    aws_region               = optional(string, "eu-central-1")
-    azure_subscription_id    = optional(string)
-    azure_tenant_id          = optional(string)
-    allow_static_credentials = optional(bool, false)
+    gcp_project_role         = optional(string)
   }))
+  default = {}
+
   validation {
-    condition     = alltrue([for connector in var.cloud_connectors : contains(["AWS_STATIC", "AWS_RBAC", "AWS_OIDC", "AZURE_STATIC", "AZURE_OIDC", "GCP_OIDC"], connector.kind)])
-    error_message = "cloud_connectors[*].kind must be AWS_STATIC, AWS_RBAC, AWS_OIDC, AZURE_STATIC, AZURE_OIDC, or GCP_OIDC."
+    condition     = alltrue([for name in keys(var.cloud_connectors) : can(regex("^[A-Za-z0-9][A-Za-z0-9 _.-]{0,99}$", name))])
+    error_message = "cloud_connectors keys must be 1-100 character StackGuardian resource names."
   }
 
   validation {
-    condition     = alltrue([for connector in var.cloud_connectors : !contains(["AWS_STATIC", "AZURE_STATIC"], connector.kind) || connector.allow_static_credentials])
-    error_message = "AWS_STATIC and AZURE_STATIC connectors require allow_static_credentials = true. Use AWS_RBAC, AWS_OIDC, AZURE_OIDC, or another non-static connector kind instead."
+    condition     = alltrue([for connector in values(var.cloud_connectors) : contains(["AWS_STATIC", "AWS_RBAC", "AWS_OIDC", "AZURE_STATIC", "AZURE_OIDC", "GCP_OIDC"], connector.kind)])
+    error_message = "cloud_connectors[*].kind must be AWS_STATIC, AWS_RBAC, AWS_OIDC, AZURE_STATIC, AZURE_OIDC, or GCP_OIDC."
   }
 
   validation {
-    condition = alltrue([for connector in var.cloud_connectors :
-      (connector.kind != "AWS_RBAC" || try(length(trimspace(connector.iam_role_name)) > 0, false) && try(length(trimspace(connector.aws_external_id)) > 0, false)) &&
-      (connector.kind != "AWS_OIDC" || try(length(trimspace(connector.iam_role_name)) > 0, false)) &&
-      (!contains(["AWS_STATIC", "AWS_RBAC", "AWS_OIDC"], connector.kind) || can(regex("^[a-z]{2}(-gov)?-[a-z]+-\\d$", connector.aws_region))) &&
-      (!contains(["AZURE_STATIC", "AZURE_OIDC"], connector.kind) || (try(can(regex("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", connector.azure_subscription_id)), false) && try(can(regex("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", connector.azure_tenant_id)), false))) &&
-      (connector.kind != "GCP_OIDC" || (try(can(regex("^[a-z][a-z0-9-]{4,28}[a-z0-9]$", connector.gcp_project_id)), false) && try(length(trimspace(connector.gcp_service_account_id)) > 0, false) && try(length(trimspace(connector.gcp_workload_pool_id)) > 0, false) && try(length(trimspace(connector.gcp_provider_id)) > 0, false)))
+    condition = alltrue([for connector in values(var.cloud_connectors) :
+      (connector.kind == "AWS_STATIC" && connector.allow_static_credentials == true &&
+        (connector.aws_region == null || can(regex("^[a-z]{2}(-gov)?-[a-z]+-\\d$", connector.aws_region))) &&
+        (connector.iam_user_name == null || can(regex("^[A-Za-z0-9][A-Za-z0-9 _.-]{0,99}$", connector.iam_user_name))) &&
+      connector.iam_role_name == null && connector.policy_arn == null && connector.aws_external_id == null && connector.trusted_account_ids == null && connector.azure_subscription_id == null && connector.azure_tenant_id == null && connector.application_display_name == null && connector.role_definition_name == null && connector.gcp_project_id == null && connector.gcp_service_account_id == null && connector.gcp_workload_pool_id == null && connector.gcp_provider_id == null && connector.gcp_project_role == null) ||
+      (connector.kind == "AWS_RBAC" && try(length(trimspace(connector.iam_role_name)) > 0, false) && try(length(trimspace(connector.aws_external_id)) > 0, false) &&
+        (connector.aws_region == null || can(regex("^[a-z]{2}(-gov)?-[a-z]+-\\d$", connector.aws_region))) &&
+        (connector.policy_arn == null || length(trimspace(connector.policy_arn)) > 0) &&
+        (connector.trusted_account_ids == null || (length(connector.trusted_account_ids) == length(toset(connector.trusted_account_ids)) && alltrue([for account_id in connector.trusted_account_ids : can(regex("^\\d{12}$", account_id))]))) &&
+      connector.allow_static_credentials == null && connector.iam_user_name == null && connector.azure_subscription_id == null && connector.azure_tenant_id == null && connector.application_display_name == null && connector.role_definition_name == null && connector.gcp_project_id == null && connector.gcp_service_account_id == null && connector.gcp_workload_pool_id == null && connector.gcp_provider_id == null && connector.gcp_project_role == null) ||
+      (connector.kind == "AWS_OIDC" && try(can(regex("^[A-Za-z0-9][A-Za-z0-9 _.-]{0,99}$", connector.iam_role_name)), false) &&
+        (connector.aws_region == null || can(regex("^[a-z]{2}(-gov)?-[a-z]+-\\d$", connector.aws_region))) &&
+        (connector.policy_arn == null || length(trimspace(connector.policy_arn)) > 0) &&
+      connector.allow_static_credentials == null && connector.iam_user_name == null && connector.aws_external_id == null && connector.trusted_account_ids == null && connector.azure_subscription_id == null && connector.azure_tenant_id == null && connector.application_display_name == null && connector.role_definition_name == null && connector.gcp_project_id == null && connector.gcp_service_account_id == null && connector.gcp_workload_pool_id == null && connector.gcp_provider_id == null && connector.gcp_project_role == null) ||
+      (connector.kind == "AZURE_STATIC" && connector.allow_static_credentials == true && try(can(regex("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", connector.azure_subscription_id)), false) && try(can(regex("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", connector.azure_tenant_id)), false) &&
+        (connector.application_display_name == null || can(regex("^[A-Za-z0-9][A-Za-z0-9 _.-]{0,99}$", connector.application_display_name))) &&
+        (connector.role_definition_name == null || length(trimspace(connector.role_definition_name)) > 0) &&
+      connector.aws_region == null && connector.iam_role_name == null && connector.iam_user_name == null && connector.policy_arn == null && connector.aws_external_id == null && connector.trusted_account_ids == null && connector.gcp_project_id == null && connector.gcp_service_account_id == null && connector.gcp_workload_pool_id == null && connector.gcp_provider_id == null && connector.gcp_project_role == null) ||
+      (connector.kind == "AZURE_OIDC" && try(can(regex("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", connector.azure_subscription_id)), false) && try(can(regex("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", connector.azure_tenant_id)), false) &&
+        (connector.application_display_name == null || can(regex("^[A-Za-z0-9][A-Za-z0-9 _.-]{0,99}$", connector.application_display_name))) &&
+        (connector.role_definition_name == null || length(trimspace(connector.role_definition_name)) > 0) &&
+      connector.allow_static_credentials == null && connector.aws_region == null && connector.iam_role_name == null && connector.iam_user_name == null && connector.policy_arn == null && connector.aws_external_id == null && connector.trusted_account_ids == null && connector.gcp_project_id == null && connector.gcp_service_account_id == null && connector.gcp_workload_pool_id == null && connector.gcp_provider_id == null && connector.gcp_project_role == null) ||
+      (connector.kind == "GCP_OIDC" && try(can(regex("^[a-z][a-z0-9-]{4,28}[a-z0-9]$", connector.gcp_project_id)), false) && try(length(trimspace(connector.gcp_service_account_id)) > 0, false) && try(length(trimspace(connector.gcp_workload_pool_id)) > 0, false) && try(length(trimspace(connector.gcp_provider_id)) > 0, false) &&
+        (connector.gcp_project_role == null || length(trimspace(connector.gcp_project_role)) > 0) &&
+      connector.allow_static_credentials == null && connector.aws_region == null && connector.iam_role_name == null && connector.iam_user_name == null && connector.policy_arn == null && connector.aws_external_id == null && connector.trusted_account_ids == null && connector.azure_subscription_id == null && connector.azure_tenant_id == null && connector.application_display_name == null && connector.role_definition_name == null)
     ])
-    error_message = "Each connector must provide the cloud-specific IDs and identity names required by its kind; OIDC connector IDs are created by Terraform."
+    error_message = "Each cloud connector must provide only the properties valid for its kind, including required IDs and static credential acknowledgement."
   }
 }
 
 variable "vcs_connectors" {
-  description = "VCS connector configuration. Credentials are sensitive and persist in Terraform state."
+  description = "Keyed VCS connector configuration. Credentials are sensitive and persist in Terraform state."
   sensitive   = true
   type = map(object({
     kind = string
     name = string
     github = optional(object({
       githubCreds     = string
-      github_com_url  = optional(string, "https://api.github.com")
-      github_http_url = optional(string, "https://github.com")
+      github_com_url  = optional(string)
+      github_http_url = optional(string)
     }))
     gitlab = optional(object({
       gitlabCreds   = string
-      gitlabHttpUrl = optional(string, "https://gitlab.com")
-      gitlabApiUrl  = optional(string, "https://gitlab.com/api/v4")
+      gitlabHttpUrl = optional(string)
+      gitlabApiUrl  = optional(string)
     }))
     bitbucket = optional(object({
       bitbucket_creds = string
@@ -107,51 +128,59 @@ variable "vcs_connectors" {
   default = {}
 
   validation {
-    condition = alltrue([for connector in values(var.vcs_connectors) :
-      (connector.kind == "GITHUB_COM" && connector.github != null && connector.gitlab == null && connector.bitbucket == null) ||
-      (connector.kind == "GITLAB_COM" && connector.gitlab != null && connector.github == null && connector.bitbucket == null) ||
-      (connector.kind == "BITBUCKET_ORG" && connector.bitbucket != null && connector.github == null && connector.gitlab == null)
-    ])
-    error_message = "Each VCS connector must have exactly one matching GitHub, GitLab, or Bitbucket credential object."
-  }
-}
-
-variable "role_name" {
-  type        = string
-  description = "StackGuardian role name."
-
-  validation {
-    condition     = length(trimspace(var.role_name)) > 0
-    error_message = "role_name must not be empty."
+    condition     = alltrue([for name, connector in var.vcs_connectors : can(regex("^[A-Za-z0-9][A-Za-z0-9 _.-]{0,99}$", name)) && connector.name == name])
+    error_message = "vcs_connectors keys must be resource names and match the name required by the unchanged VCS connector module."
   }
-}
-
-variable "template_list" {
-  type        = list(string)
-  description = "Templates granted to the StackGuardian role."
 
   validation {
-    condition     = length(var.template_list) > 0 && alltrue([for name in var.template_list : length(trimspace(name)) > 0])
-    error_message = "template_list must contain at least one non-empty template name."
+    condition = alltrue([for connector in values(var.vcs_connectors) :
+      (connector.kind == "GITHUB_COM" && connector.github != null && connector.gitlab == null && connector.bitbucket == null && length(trimspace(connector.github.githubCreds)) > 0) ||
+      (connector.kind == "GITLAB_COM" && connector.gitlab != null && connector.github == null && connector.bitbucket == null && length(trimspace(connector.gitlab.gitlabCreds)) > 0) ||
+      (connector.kind == "BITBUCKET_ORG" && connector.bitbucket != null && connector.github == null && connector.gitlab == null && length(trimspace(connector.bitbucket.bitbucket_creds)) > 0)
+    ])
+    error_message = "Each VCS connector must have exactly one matching GitHub, GitLab, or Bitbucket credential object with non-empty credentials."
   }
 }
 
-variable "subject" {
-  type        = string
-  description = "Local email or qualified SSO email/group subject receiving the role."
+variable "roles" {
+  description = "Keyed StackGuardian roles and their resource scopes."
+  type = map(object({
+    workflow_groups  = optional(list(string), [])
+    cloud_connectors = optional(list(string), [])
+    vcs_connectors   = optional(list(string), [])
+    template_list    = optional(list(string), [])
+  }))
+  default = {}
 
   validation {
-    condition     = can(regex("^([^/@\\s]+/[^/\\s]+|[^@\\s]+@[^@\\s]+\\.[^@\\s]+)$", var.subject))
-    error_message = "subject must be a local email or a qualified SSO subject in provider/value format."
+    condition = alltrue([for name, role in var.roles :
+      can(regex("^[A-Za-z0-9][A-Za-z0-9 _.-]{0,99}$", name)) &&
+      length(role.workflow_groups) == length(toset(role.workflow_groups)) &&
+      length(role.cloud_connectors) == length(toset(role.cloud_connectors)) &&
+      length(role.vcs_connectors) == length(toset(role.vcs_connectors)) &&
+      length(role.template_list) == length(toset(role.template_list)) &&
+      alltrue([for reference in concat(role.workflow_groups, role.cloud_connectors, role.vcs_connectors, role.template_list) : length(trimspace(reference)) > 0]) &&
+      length(concat(role.workflow_groups, role.cloud_connectors, role.vcs_connectors, role.template_list)) > 0
+    ])
+    error_message = "Each role key must be a resource name and each role must have at least one unique, non-empty workflow group, connector, or template reference."
   }
 }
 
-variable "entity_type" {
-  type        = string
-  description = "Type of StackGuardian assignment subject: EMAIL or GROUP."
+variable "subjects" {
+  description = "Keyed local-email, qualified SSO-email, or SSO-group subjects and their assigned roles."
+  type = map(object({
+    entity_type = optional(string, "EMAIL")
+    roles       = list(string)
+  }))
+  default = {}
 
   validation {
-    condition     = contains(["EMAIL", "GROUP"], var.entity_type)
-    error_message = "entity_type must be EMAIL or GROUP."
+    condition = alltrue([for subject, assignment in var.subjects :
+      can(regex("^([^/@\\s]+/[^/\\s]+|[^@\\s]+@[^@\\s]+\\.[^@\\s]+)$", subject)) &&
+      contains(["EMAIL", "GROUP"], assignment.entity_type) &&
+      length(assignment.roles) > 0 && length(assignment.roles) == length(toset(assignment.roles)) &&
+      alltrue([for role in assignment.roles : can(regex("^[A-Za-z0-9][A-Za-z0-9 _.-]{0,99}$", role))])
+    ])
+    error_message = "Each subject must be a local email or qualified SSO subject with a valid entity_type and a non-empty, duplicate-free role list."
   }
 }

From f0e32884dca6283a309d27af2af5b898302c81b9 Mon Sep 17 00:00:00 2001
From: Oliver Jarosch <oliver.jarosch@stackguardian.io>
Date: Fri, 14 Aug 2026 19:04:24 +0200
Subject: [PATCH 2/5] docs: add multi-role onboarding examples

---
 README.md                          | 46 ++++++++++++++----
 examples/aws-oidc.tfvars.example   | 44 ++++++++++++-----
 examples/azure-oidc.tfvars.example | 46 +++++++++++++-----
 terraform.tfvars.example           | 78 +++++++++++++++---------------
 4 files changed, 141 insertions(+), 73 deletions(-)

diff --git a/README.md b/README.md
index d931998..c29c2b4 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # StackGuardian Terraform Modules v2
 
-Terraform modules for StackGuardian onboarding and cloud identity configuration. The root module creates workflow groups, cloud/VCS connectors, a role, and one assignment. `stackguardian_private_runner/` is explicitly outside the v2 upgrade scope.
+Terraform modules for StackGuardian onboarding and cloud identity configuration. The root module creates workflow groups, cloud/VCS connectors, keyed roles, and one multi-role assignment per subject. `stackguardian_private_runner/` is explicitly outside the v2 upgrade scope.
 
 ## Prerequisites
 
@@ -9,7 +9,7 @@ Terraform modules for StackGuardian onboarding and cloud identity configuration.
 - AWS provider `>= 6.58.0, < 7.0.0`, AzureRM `>= 5.0.1, < 6.0.0`, AzureAD `>= 3.9.0, < 4.0.0`, and Google `>= 7.44.0, < 8.0.0` in their applicable modules.
 - Credentials authorized to create the selected cloud identities. Azure management needs Microsoft Graph application-management and subscription role-assignment privileges.
 
-Use `terraform.tfvars.example` as a schema reference. Put secret values in `TF_VAR_*` variables or a secret manager, not version control.
+Use `terraform.tfvars.example` as a configuration reference. Put secret values in `TF_VAR_*` variables or a secret manager, not version control.
 
 ## Static Credential Deprecation
 
@@ -18,14 +18,13 @@ Use `terraform.tfvars.example` as a schema reference. Put secret values in `TF_V
 Static authentication requires an explicit acknowledgement. The root acknowledgement is per connector and cannot enable another connector:
 
 ```hcl
-cloud_connectors = [{
-  name                     = "legacy-aws"
-  kind                     = "AWS_STATIC"
-  allow_static_credentials = true
-  aws_access_key_id        = var.legacy_aws_access_key_id
-  aws_secret_access_key    = var.legacy_aws_secret_access_key
-  aws_region               = "eu-central-1"
-}]
+cloud_connectors = {
+  legacy-aws = {
+    kind                     = "AWS_STATIC"
+    allow_static_credentials = true
+    aws_region               = "eu-central-1"
+  }
+}
 ```
 
 Standalone `aws_static` and `azure_static` modules also require `allow_static_credentials = true`. Terraform emits a deprecation warning during apply after acknowledgement.
@@ -62,6 +61,16 @@ Use `task destroy:aws` or `task destroy:azure` to remove a connector trial. Each
 
 Legacy aliases are intentionally unavailable. The root configures StackGuardian once; standalone StackGuardian leaf modules inherit provider configuration from their caller and do not accept API credentials.
 
+## Onboarding Configuration
+
+`terraform.tfvars.example` is a complete multi-role example. It includes a local user, a qualified SSO user, and an SSO group. `workflow_groups` is a list. Cloud connectors are keyed by connector name. The unchanged VCS connector leaf module retains its required `name` field; in root configuration it must equal its map key.
+
+Each `roles` map key is the StackGuardian role name. A role may scope workflow groups, cloud connectors, VCS connectors, and templates, but must include at least one non-empty scope. Role connector and workflow references are the relevant root map keys. Empty scope categories produce no permissions.
+
+Each `subjects` map key is a local email, qualified SSO email, or qualified SSO group such as `okta/platform-engineers`. A subject has one assignment resource containing its complete, non-empty, duplicate-free `roles` list. `entity_type` defaults to `EMAIL`; use `GROUP` for group subjects.
+
+VCS credentials remain sensitive and are stored in Terraform state. Keep real values in an ignored secret vars file, a generated `terraform.tfvars.json`, or JSON-encoded `TF_VAR_vcs_connectors`; examples use literal placeholders.
+
 ## Permissions And Defaults
 
 - `aws_static` is deprecated, needs IAM user/key permissions, and stores a generated static key in state. Use `aws_rbac` or `aws_oidc` when possible.
@@ -85,6 +94,23 @@ For standalone role usage, omit `module.stackguardian_role.`. Review the v4 `all
 
 Before replacing the former authoritative GCP IAM policy, add and import `google_service_account_iam_member.self_workload_identity`, then remove only the old policy state binding. Likewise, import the existing AWS role-policy attachment when converting from the legacy global attachment. Export existing IAM bindings first and verify the plan cannot remove unrelated principals.
 
+## Multi-Role Migration
+
+This root interface is a breaking change. Back up state, acquire an exclusive backend lock, convert the old values into one `roles` entry and one `subjects` entry, and review the resulting plan. Preserve workflow names and connector names as the new list values and map keys to retain their existing `for_each` addresses. A key or name change intentionally renames a resource and needs separate migration handling.
+
+Move the former singleton role and assignment addresses for each installation after converting configuration:
+
+```bash
+terraform state mv \
+  'module.stackguardian_role.stackguardian_rolev4.role' \
+  'module.stackguardian_role["engineering-developer"].stackguardian_rolev4.role'
+terraform state mv \
+  'module.stackguardian_role_assignment.stackguardian_role_assignment.sg_user' \
+  'module.stackguardian_role_assignment["developer@example.invalid"].stackguardian_role_assignment.sg_user'
+```
+
+Run a reviewed plan after the moves before applying. The v4 resource-type migration instructions above still apply when migrating from a pre-v4 state address.
+
 ## Module Usage
 
 Each module has a short usage and outputs reference in its directory README. Run `terraform init -upgrade`, `terraform validate`, and a reviewed plan from the specific module directory. Lock files are deliberately not committed because callers initialize independently.
diff --git a/examples/aws-oidc.tfvars.example b/examples/aws-oidc.tfvars.example
index ef055ab..f41254c 100644
--- a/examples/aws-oidc.tfvars.example
+++ b/examples/aws-oidc.tfvars.example
@@ -3,16 +3,36 @@
 stackguardian_org_name = "wicked-hop"
 
 workflow_groups = ["engineering"]
-cloud_connectors = [{
-  name          = "aws-oidc"
-  kind          = "AWS_OIDC"
-  aws_region    = "eu-central-1"
-  iam_role_name = "StackGuardianOidcRole"
-  policy_arn    = "arn:aws:iam::aws:policy/ReadOnlyAccess"
-}]
+cloud_connectors = {
+  aws-oidc = {
+    kind          = "AWS_OIDC"
+    aws_region    = "eu-central-1"
+    iam_role_name = "StackGuardianOidcRole"
+    policy_arn    = "arn:aws:iam::aws:policy/ReadOnlyAccess"
+  }
+}
 
-vcs_connectors = {}
-role_name      = "engineering-developer"
-template_list  = ["terraform-aws-vpc"]
-subject        = "developer@example.invalid"
-entity_type    = "EMAIL"
+roles = {
+  engineering-developer = {
+    workflow_groups  = ["engineering"]
+    cloud_connectors = ["aws-oidc"]
+    template_list    = ["terraform-aws-vpc"]
+  }
+}
+
+subjects = {
+  # Local user
+  "developer@example.invalid" = {
+    roles = ["engineering-developer"]
+  }
+  # Qualified SSO user
+  "okta/engineering.user@example.invalid" = {
+    entity_type = "EMAIL"
+    roles       = ["engineering-developer"]
+  }
+  # SSO group
+  "okta/platform-engineers" = {
+    entity_type = "GROUP"
+    roles       = ["engineering-developer"]
+  }
+}
diff --git a/examples/azure-oidc.tfvars.example b/examples/azure-oidc.tfvars.example
index 84cba19..05a052d 100644
--- a/examples/azure-oidc.tfvars.example
+++ b/examples/azure-oidc.tfvars.example
@@ -3,17 +3,37 @@
 stackguardian_org_name = "example-org"
 
 workflow_groups = ["engineering"]
-cloud_connectors = [{
-  name                     = "azure-oidc"
-  kind                     = "AZURE_OIDC"
-  azure_subscription_id    = "00000000-0000-0000-0000-000000000000"
-  azure_tenant_id          = "00000000-0000-0000-0000-000000000000"
-  application_display_name = "stackguardian-oidc"
-  role_definition_name     = "Reader"
-}]
+cloud_connectors = {
+  azure-oidc = {
+    kind                     = "AZURE_OIDC"
+    azure_subscription_id    = "00000000-0000-0000-0000-000000000000"
+    azure_tenant_id          = "00000000-0000-0000-0000-000000000000"
+    application_display_name = "stackguardian-oidc"
+    role_definition_name     = "Reader"
+  }
+}
 
-vcs_connectors = {}
-role_name      = "engineering-developer"
-template_list  = ["terraform-azurerm-resource-group"]
-subject        = "developer@example.invalid"
-entity_type    = "EMAIL"
+roles = {
+  engineering-developer = {
+    workflow_groups  = ["engineering"]
+    cloud_connectors = ["azure-oidc"]
+    template_list    = ["terraform-azurerm-resource-group"]
+  }
+}
+
+subjects = {
+  # Local user
+  "developer@example.invalid" = {
+    roles = ["engineering-developer"]
+  }
+  # Qualified SSO user
+  "okta/engineering.user@example.invalid" = {
+    entity_type = "EMAIL"
+    roles       = ["engineering-developer"]
+  }
+  # SSO group
+  "okta/platform-engineers" = {
+    entity_type = "GROUP"
+    roles       = ["engineering-developer"]
+  }
+}
diff --git a/terraform.tfvars.example b/terraform.tfvars.example
index 4ba30a5..d920802 100644
--- a/terraform.tfvars.example
+++ b/terraform.tfvars.example
@@ -2,62 +2,64 @@
 # Do not place it in this file.
 stackguardian_org_name = "example-org"
 
-workflow_groups = ["engineering"]
+workflow_groups = ["engineering", "platform"]
 
 # Terraform creates each selected cloud identity using the AWS CLI, Azure CLI, or
 # gcloud application-default credentials and registers its generated identifiers.
-# Prefer OIDC. Static connector kinds are retained only for legacy migrations.
-cloud_connectors = [
-  {
-    name          = "aws-oidc"
+cloud_connectors = {
+  aws-production = {
     kind          = "AWS_OIDC"
     aws_region    = "eu-central-1"
-    iam_role_name = "StackGuardianOidcRole"
-  },
-  {
-    name                     = "azure-oidc"
+    iam_role_name = "StackGuardianProductionRole"
+    policy_arn    = "arn:aws:iam::aws:policy/ReadOnlyAccess"
+  }
+  azure-production = {
     kind                     = "AZURE_OIDC"
     azure_subscription_id    = "00000000-0000-0000-0000-000000000000"
     azure_tenant_id          = "00000000-0000-0000-0000-000000000000"
-    application_display_name = "stackguardian-oidc"
+    application_display_name = "stackguardian-production"
     role_definition_name     = "Reader"
-  },
-  {
-    name                   = "gcp-oidc"
-    kind                   = "GCP_OIDC"
-    gcp_project_id         = "example-project"
-    gcp_service_account_id = "stackguardian"
-    gcp_workload_pool_id   = "stackguardian"
-    gcp_provider_id        = "stackguardian-oidc"
-    gcp_project_role       = "roles/viewer"
-  },
-]
+  }
+}
 
+# Credentials are sensitive and persist in Terraform state. Supply real values
+# through an ignored secret vars file or JSON-encoded TF_VAR_vcs_connectors.
 vcs_connectors = {
   github = {
-    name = "github"
     kind = "GITHUB_COM"
+    name = "github"
     github = {
       githubCreds = "<github-credential>"
     }
   }
-  gitlab = {
-    name = "gitlab"
-    kind = "GITLAB_COM"
-    gitlab = {
-      gitlabCreds = "<gitlab-credential>"
-    }
+}
+
+# Role references are workflow-group and connector map keys.
+roles = {
+  developer = {
+    workflow_groups  = ["engineering"]
+    cloud_connectors = ["aws-production"]
+    vcs_connectors   = ["github"]
+    template_list    = ["terraform-aws-vpc"]
   }
-  bitbucket = {
-    name = "bitbucket"
-    kind = "BITBUCKET_ORG"
-    bitbucket = {
-      bitbucket_creds = "<bitbucket-credential>"
-    }
+  auditor = {
+    workflow_groups  = ["platform"]
+    cloud_connectors = ["aws-production"]
   }
 }
 
-role_name     = "engineering-developer"
-template_list = ["terraform-aws-vpc"]
-subject       = "developer@example.invalid"
-entity_type   = "EMAIL"
+# Local user: an email not qualified by an SSO provider.
+# SSO users and groups use provider/value subject keys.
+subjects = {
+  "developer@example.invalid" = {
+    roles = ["developer", "auditor"]
+  }
+  "okta/engineering.user@example.invalid" = {
+    entity_type = "EMAIL"
+    roles       = ["developer"]
+  }
+  "okta/platform-engineers" = {
+    entity_type = "GROUP"
+    roles       = ["developer"]
+  }
+}

From 2a1bce94f5594dca27497453464810a7437abcdc Mon Sep 17 00:00:00 2001
From: Oliver Jarosch <oliver.jarosch@stackguardian.io>
Date: Fri, 14 Aug 2026 19:04:40 +0200
Subject: [PATCH 3/5] test: discover OpenTofu test configurations

---
 Taskfile.yml | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/Taskfile.yml b/Taskfile.yml
index 3601768..b3d4a26 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -91,7 +91,7 @@ tasks:
           terraform -chdir="$dir" fmt -check
         done
   test:
-    desc: Runs isolated OpenTofu native tests with mocked providers
+    desc: Runs isolated OpenTofu tests discovered under tests directories
     deps: [preflight:tofu]
     cmds:
       - |
@@ -100,14 +100,21 @@ tasks:
         root="$(pwd)"
         temp="$(mktemp -d)"
         trap 'rm -rf "$temp"' EXIT
-        for dir in stackguardian_role stackguardian_connector_cloud; do
-          tar --exclude='.terraform' --exclude='.terraform.lock.hcl' -cf - -C "$root" "$dir" | tar -xf - -C "$temp"
-          target="$temp/$dir"
-          perl -0pi -e 's/required_version = "= 1\.5\.7"/required_version = ">= 1.6.0"/' "$target/provider.tf"
-          perl -0pi -e 's/source\s*=\s*"StackGuardian\/stackguardian"/source  = "registry.terraform.io\/StackGuardian\/stackguardian"/' "$target/provider.tf"
+        while IFS= read -r config_dir; do
+          if [ "$config_dir" = "$root" ]; then
+            target="$temp/root"
+          else
+            target="$temp/${config_dir#"$root"/}"
+          fi
+          mkdir -p "$target"
+          tar --exclude='.git' --exclude='.terraform' --exclude='.terraform.lock.hcl' -cf - -C "$config_dir" . | tar -xf - -C "$target"
+          while IFS= read -r provider_file; do
+            perl -0pi -e 's/required_version = "= 1\.5\.7"/required_version = ">= 1.6.0"/' "$provider_file"
+            perl -0pi -e 's/source\s*=\s*"StackGuardian\/stackguardian"/source  = "registry.terraform.io\/StackGuardian\/stackguardian"/' "$provider_file"
+          done < <(find "$target" -name provider.tf -type f)
           tofu -chdir="$target" init -backend=false
           tofu -chdir="$target" test
-        done
+        done < <(find "$root" \( -name .git -o -name .terraform \) -type d -prune -o -path '*/tests/*.tofutest.hcl' -type f -print | while IFS= read -r test_file; do dirname "$(dirname "$test_file")"; done | sort -u)
   onboard:aws:
     desc: Creates AWS OIDC resources and registers the connector with StackGuardian
     deps: [preflight:terraform]
@@ -291,7 +298,7 @@ tasks:
           target="$temp/${dir#./}"
           mkdir -p "$target"
           if [ "$dir" = "." ]; then
-            tar --exclude='.git' --exclude='.kilo' --exclude='.terraform' --exclude='.terraform.lock.hcl' --exclude='terraform.tfvars' --exclude='*.auto.tfvars' --exclude='role_response.json' --exclude='stackguardian_private_runner' -cf - -C "$root" . | tar -xf - -C "$target"
+            tar --exclude='.git' --exclude='.terraform' --exclude='.terraform.lock.hcl' --exclude='terraform.tfvars' --exclude='*.auto.tfvars' --exclude='role_response.json' --exclude='stackguardian_private_runner' -cf - -C "$root" . | tar -xf - -C "$target"
           else
             tar --exclude='.terraform' --exclude='.terraform.lock.hcl' -cf - -C "$root" "$dir" | tar -xf - -C "$temp"
           fi

From db4095432d6b1aaea5b69696dbfcbbaf4c9c09ec Mon Sep 17 00:00:00 2001
From: Oliver Jarosch <oliver.jarosch@stackguardian.io>
Date: Sat, 15 Aug 2026 08:01:47 +0200
Subject: [PATCH 4/5] docs: simplify onboarding usage guide

---
 README.md | 80 +++++++++++++++----------------------------------------
 1 file changed, 22 insertions(+), 58 deletions(-)

diff --git a/README.md b/README.md
index c29c2b4..2987278 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
-# StackGuardian Terraform Modules v2
+# StackGuardian Terraform Modules
 
-Terraform modules for StackGuardian onboarding and cloud identity configuration. The root module creates workflow groups, cloud/VCS connectors, keyed roles, and one multi-role assignment per subject. `stackguardian_private_runner/` is explicitly outside the v2 upgrade scope.
+Terraform modules for StackGuardian onboarding and cloud identity configuration. The root module creates workflow groups, cloud/VCS connectors, keyed roles, and one multi-role assignment per subject.
 
 ## Prerequisites
 
@@ -11,9 +11,18 @@ Terraform modules for StackGuardian onboarding and cloud identity configuration.
 
 Use `terraform.tfvars.example` as a configuration reference. Put secret values in `TF_VAR_*` variables or a secret manager, not version control.
 
-## Static Credential Deprecation
+## How To Use
 
-`aws_static`, `azure_static`, and `AWS_STATIC` or `AZURE_STATIC` cloud connectors are deprecated. Static secrets are retained in Terraform state and may appear in plan artifacts, so protect both as sensitive data. Prefer `aws_rbac`, `aws_oidc`, `azure_oidc`, or the corresponding non-static connector kind.
+1. Copy `terraform.tfvars.example` to an ignored `terraform.tfvars` file and replace its placeholders.
+2. Set `TF_VAR_stackguardian_api_key` through a secret manager or environment variable.
+3. Authenticate to each cloud used by `cloud_connectors`.
+4. Run `terraform init`, review `terraform plan`, then run `terraform apply`.
+
+For AWS and Azure OIDC onboarding, customize the matching file in `examples/` and use `task onboard:aws` or `task onboard:azure`. Those tasks authenticate through the local cloud CLI, create the selected cloud identity, and apply a reviewed plan.
+
+## Static Credentials
+
+`AWS_STATIC` and `AZURE_STATIC` are supported only when `allow_static_credentials = true` is set on that connector. Static secrets are retained in Terraform state and may appear in plan artifacts. Prefer `AWS_RBAC`, `AWS_OIDC`, `AZURE_OIDC`, or `GCP_OIDC` whenever possible.
 
 Static authentication requires an explicit acknowledgement. The root acknowledgement is per connector and cannot enable another connector:
 
@@ -41,33 +50,19 @@ Both onboarding tasks use `TF_VAR_stackguardian_api_key` when it is set. Otherwi
 
 Use `task destroy:aws` or `task destroy:azure` to remove a connector trial. Each asks you to type the connector name before it destroys resources. AWS teardown retains any account-level `api.app.stackguardian.io` OIDC provider because it may be shared by multiple StackGuardian roles.
 
-## V2 Inputs
-
-| v1 input | v2 input |
-| --- | --- |
-| `api_key` | `stackguardian_api_key` |
-| `org_name` | `stackguardian_org_name` |
-| `user_or_group` | `subject` |
-| `connector_type` | `kind` in `cloud_connectors` |
-| `cloud_connector_name` | `name` in `cloud_connectors` |
-| `aws_default_region` | `aws_region` in the AWS connector |
-| `armTenantId`, `armSubscriptionId`, `armClientId`, `armClientSecret` | `azure_tenant_id`, `azure_subscription_id`, `azure_client_id`, `azure_client_secret` in the Azure connector |
-| `role_arn`, `role_external_id` | `aws_role_arn`, `aws_external_id` |
-| `aws_oidc.region`, `role_name`, `account_number`, `aws_policy` | `aws_region`, `iam_role_name`, `aws_account_id`, `policy_arn` |
-| `aws_rbac.aws_role_name`, `aws_policy` | `iam_role_name`, `policy_arn` |
-| `azure_static.AD_name` | `application_display_name` |
-| `azure_oidc.sg_org_name` | `stackguardian_org_name` |
-| `gcp_oidc.project`, `sg-org-id` | `gcp_project_id` in the GCP connector, `stackguardian_org_name` |
-
-Legacy aliases are intentionally unavailable. The root configures StackGuardian once; standalone StackGuardian leaf modules inherit provider configuration from their caller and do not accept API credentials.
-
 ## Onboarding Configuration
 
-`terraform.tfvars.example` is a complete multi-role example. It includes a local user, a qualified SSO user, and an SSO group. `workflow_groups` is a list. Cloud connectors are keyed by connector name. The unchanged VCS connector leaf module retains its required `name` field; in root configuration it must equal its map key.
+`terraform.tfvars.example` is a complete multi-role configuration. The root accepts these top-level collections:
+
+- `workflow_groups`: unique names of workflow groups to create.
+- `cloud_connectors`: a map keyed by connector name. Each value selects one cloud `kind` and supplies the corresponding identity settings. The root creates the selected identity and registers it with StackGuardian.
+- `vcs_connectors`: a map keyed by connector name. Each value supplies one GitHub, GitLab, or Bitbucket credential configuration. Its `name` must match the map key.
+- `roles`: a map keyed by StackGuardian role name. Each role references one or more workflow groups, cloud connectors, VCS connectors, or templates.
+- `subjects`: a map keyed by a local email or qualified SSO subject. Each subject receives one or more role names in one assignment resource.
 
-Each `roles` map key is the StackGuardian role name. A role may scope workflow groups, cloud connectors, VCS connectors, and templates, but must include at least one non-empty scope. Role connector and workflow references are the relevant root map keys. Empty scope categories produce no permissions.
+Role references use the corresponding collection keys. A role must include at least one non-empty scope. Empty scope categories produce no permissions.
 
-Each `subjects` map key is a local email, qualified SSO email, or qualified SSO group such as `okta/platform-engineers`. A subject has one assignment resource containing its complete, non-empty, duplicate-free `roles` list. `entity_type` defaults to `EMAIL`; use `GROUP` for group subjects.
+Subjects can be local emails such as `developer@example.invalid`, qualified SSO emails such as `okta/developer@example.invalid`, or SSO groups such as `okta/platform-engineers`. `entity_type` defaults to `EMAIL`; set it to `GROUP` for a group. Role lists must be non-empty and duplicate-free.
 
 VCS credentials remain sensitive and are stored in Terraform state. Keep real values in an ignored secret vars file, a generated `terraform.tfvars.json`, or JSON-encoded `TF_VAR_vcs_connectors`; examples use literal placeholders.
 
@@ -80,37 +75,6 @@ VCS credentials remain sensitive and are stored in Terraform state. Keep real va
 - Cloud and VCS connector modules require access to create StackGuardian connectors. They reject missing, mismatched, or conflicting credentials.
 - Role, assignment, and workflow-group modules require StackGuardian role-management permission.
 
-## Role v4 State Migration
-
-The role resource changes from `stackguardian_role` to `stackguardian_rolev4`; this cannot use a `moved` block or `terraform state mv`. During a maintenance window with exclusive backend locking, back up state and record the existing permissions, then run:
-
-```bash
-terraform state rm 'module.stackguardian_role.stackguardian_role.role'
-terraform import 'module.stackguardian_role.stackguardian_rolev4.role' '<role-name>'
-terraform plan
-```
-
-For standalone role usage, omit `module.stackguardian_role.`. Review the v4 `allowed_permissions`, apply the reviewed update, then run a second plan and test an allowed and denied path. Do not use `state mv`; roll back only by restoring the backed-up state/configuration.
-
-Before replacing the former authoritative GCP IAM policy, add and import `google_service_account_iam_member.self_workload_identity`, then remove only the old policy state binding. Likewise, import the existing AWS role-policy attachment when converting from the legacy global attachment. Export existing IAM bindings first and verify the plan cannot remove unrelated principals.
-
-## Multi-Role Migration
-
-This root interface is a breaking change. Back up state, acquire an exclusive backend lock, convert the old values into one `roles` entry and one `subjects` entry, and review the resulting plan. Preserve workflow names and connector names as the new list values and map keys to retain their existing `for_each` addresses. A key or name change intentionally renames a resource and needs separate migration handling.
-
-Move the former singleton role and assignment addresses for each installation after converting configuration:
-
-```bash
-terraform state mv \
-  'module.stackguardian_role.stackguardian_rolev4.role' \
-  'module.stackguardian_role["engineering-developer"].stackguardian_rolev4.role'
-terraform state mv \
-  'module.stackguardian_role_assignment.stackguardian_role_assignment.sg_user' \
-  'module.stackguardian_role_assignment["developer@example.invalid"].stackguardian_role_assignment.sg_user'
-```
-
-Run a reviewed plan after the moves before applying. The v4 resource-type migration instructions above still apply when migrating from a pre-v4 state address.
-
 ## Module Usage
 
 Each module has a short usage and outputs reference in its directory README. Run `terraform init -upgrade`, `terraform validate`, and a reviewed plan from the specific module directory. Lock files are deliberately not committed because callers initialize independently.

From 84c75d53900768643eac617aa6d1aa27bbf4f677 Mon Sep 17 00:00:00 2001
From: Oliver Jarosch <oliver.jarosch@stackguardian.io>
Date: Sat, 15 Aug 2026 08:01:53 +0200
Subject: [PATCH 5/5] test: mock root onboarding providers

---
 Taskfile.yml                             | 31 ++++++++++++++++++++++++
 tests/multi_role_onboarding.tofutest.hcl |  4 +++
 2 files changed, 35 insertions(+)

diff --git a/Taskfile.yml b/Taskfile.yml
index b3d4a26..eed1fdc 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -100,6 +100,17 @@ tasks:
         root="$(pwd)"
         temp="$(mktemp -d)"
         trap 'rm -rf "$temp"' EXIT
+        export AWS_ACCESS_KEY_ID="test"
+        export AWS_SECRET_ACCESS_KEY="test"
+        export AWS_SESSION_TOKEN="test"
+        export AWS_EC2_METADATA_DISABLED="true"
+        export ARM_CLIENT_ID="00000000-0000-0000-0000-000000000000"
+        export ARM_CLIENT_SECRET="test"
+        export ARM_TENANT_ID="00000000-0000-0000-0000-000000000000"
+        export ARM_SUBSCRIPTION_ID="00000000-0000-0000-0000-000000000000"
+        export AZUREAD_CLIENT_ID="$ARM_CLIENT_ID"
+        export AZUREAD_CLIENT_SECRET="$ARM_CLIENT_SECRET"
+        export AZUREAD_TENANT_ID="$ARM_TENANT_ID"
         while IFS= read -r config_dir; do
           if [ "$config_dir" = "$root" ]; then
             target="$temp/root"
@@ -108,6 +119,26 @@ tasks:
           fi
           mkdir -p "$target"
           tar --exclude='.git' --exclude='.terraform' --exclude='.terraform.lock.hcl' -cf - -C "$config_dir" . | tar -xf - -C "$target"
+          if [ "$config_dir" = "$root" ]; then
+            : > "$target/provider.tf"
+            printf '%s\n' \
+              'terraform {' \
+              '  required_version = "= 1.5.7"' \
+              '' \
+              '  required_providers {' \
+              '    stackguardian = {' \
+              '      source  = "StackGuardian/stackguardian"' \
+              '      version = ">= 1.12.0, < 2.0.0"' \
+              '    }' \
+              '  }' \
+              '}' \
+              '' \
+              'provider "stackguardian" {' \
+              '  api_key  = var.stackguardian_api_key' \
+              '  org_name = var.stackguardian_org_name' \
+              '  api_uri  = var.stackguardian_api_uri' \
+              '}' >> "$target/provider.tf"
+          fi
           while IFS= read -r provider_file; do
             perl -0pi -e 's/required_version = "= 1\.5\.7"/required_version = ">= 1.6.0"/' "$provider_file"
             perl -0pi -e 's/source\s*=\s*"StackGuardian\/stackguardian"/source  = "registry.terraform.io\/StackGuardian\/stackguardian"/' "$provider_file"
diff --git a/tests/multi_role_onboarding.tofutest.hcl b/tests/multi_role_onboarding.tofutest.hcl
index a99aa96..9228ad3 100644
--- a/tests/multi_role_onboarding.tofutest.hcl
+++ b/tests/multi_role_onboarding.tofutest.hcl
@@ -1,4 +1,8 @@
 mock_provider "stackguardian" {}
+mock_provider "aws" {}
+mock_provider "azurerm" {}
+mock_provider "azuread" {}
+mock_provider "google" {}
 
 variables {
   stackguardian_api_key  = "sgu_testkey"