chore: custom role for administrative units

- also modify docs and add entries to changelog

Author: malhussan

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [v0.13.0]
+
+### Added
+
+- Harden permissions for administrative units
+- Support for dynamic membership rules in administrative units
+
 ## [v0.12.0]
 
 ### Added
@@ -98,7 +105,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial Release
 
-[unreleased]: https://github.com/meshcloud/terraform-azure-meshplatform/compare/v0.12.0...HEAD
+[unreleased]: https://github.com/meshcloud/terraform-azure-meshplatform/compare/v0.13.0...HEAD
+[v0.13.0]: https://github.com/meshcloud/terraform-azure-meshplatform/releases/tag/v0.13.0
 [v0.12.0]: https://github.com/meshcloud/terraform-azure-meshplatform/releases/tag/v0.12.0
 [v0.11.0]: https://github.com/meshcloud/terraform-azure-meshplatform/releases/tag/v0.11.0
 [v0.1.0]: https://github.com/meshcloud/terraform-azure-meshplatform/releases/tag/v0.1.0

README.md

@@ -107,6 +107,29 @@ module "meshplatform" {
 }
 ```
 
+### Using Pre-provisioned Subscriptions
+
+meshStack will need to be able to read subscriptions at the source location
+(typically the root of your management group hierarchy) and then have permission to rename them.
+Please include the following `additional_permission` when configuring this terraform module.
+
+```hcl
+  additional_permissions = ["Microsoft.Subscription/rename/action"]
+```
+
+### Using Azure Administrative Units
+
+To use Azure Administrative Units with this module, you can set the `administrative_unit_name` and `administrative_unit_membership_rule` variables.
+
+```hcl
+module "meshplatform" {
+  source = "meshcloud/meshplatform/azure"
+  # required inputs
+  administrative_unit_name              = "my-administrative-unit"
+  administrative_unit_membership_rule   = "(user.accountEnabled -eq true)" # Include all active users
+}
+```
+
 ## Workload Identity Federation for Multiple Environments
 
 When using multiple MCA service principals with Workload Identity Federation (WIF), you can configure per-service-principal subjects to support different Kubernetes namespaces or environments.
@@ -142,15 +165,6 @@ workload_identity_federation = {
 
 This approach allows each service principal to have its own custom subject when configuring WIF.
 
-### Using Pre-provisioned Subscriptions
-
-meshStack will need to be able to read subscriptions at the source location
-(typically the root of your management group hierarchy) and then have permission to rename them.
-Please include the following `additional_permission` when configuring this terraform module.
-
-```hcl
-  additional_permissions = ["Microsoft.Subscription/rename/action"]
-```
 
 ### Enabling Azure Functions for Landing Zones
 
@@ -234,6 +248,7 @@ Before opening a Pull Request, please do the following:
 |------|-------------|------|---------|:--------:|
 | <a name="input_additional_permissions"></a> [additional\_permissions](#input\_additional\_permissions) | Additional Subscription-Level Permissions the Service Principal needs. | `list(string)` | `[]` | no |
 | <a name="input_additional_required_resource_accesses"></a> [additional\_required\_resource\_accesses](#input\_additional\_required\_resource\_accesses) | Additional AAD-Level Resource Accesses the replicator Service Principal needs. | `list(object({ resource_app_id = string, resource_accesses = list(object({ id = string, type = string })) }))` | `[]` | no |
+| <a name="input_administrative_unit_membership_rule"></a> [administrative\_unit\_membership\_rule](#input\_administrative\_unit\_membership\_rule) | Dynamic membership rule for the Administrative Unit. Required when administrative\_unit\_name is set.<br><br>Suggested default: "(user.accountEnabled -eq true)"<br>NOTE: This rule will include ALL active users in your tenant. Consider more restrictive rules for production use.<br><br>Examples for more restrictive rules:<br>- "(user.companyName -eq \"MyCompany\") and (user.accountEnabled -eq true)" - Active users from specific company<br>- "(user.userType -eq \"Member\") and (user.accountEnabled -eq true)" - Active member users only<br><br>For more information on membership rules, see:<br>https://learn.microsoft.com/en-us/entra/identity/users/groups-dynamic-membership | `string` | `null` | no |
 | <a name="input_administrative_unit_name"></a> [administrative\_unit\_name](#input\_administrative\_unit\_name) | Display name of the adminstration-unit name where the user groups are managed. | `string` | `null` | no |
 | <a name="input_application_owners"></a> [application\_owners](#input\_application\_owners) | List of user principals that should be added as owners to the created service principals. | `list(string)` | `[]` | no |
 | <a name="input_can_cancel_subscriptions_in_scopes"></a> [can\_cancel\_subscriptions\_in\_scopes](#input\_can\_cancel\_subscriptions\_in\_scopes) | The scopes to which Service Principal cancel subscription permission is assigned to. List of management group id of form `/providers/Microsoft.Management/managementGroups/<mgmtGroupId>/`. | `list(string)` | `[]` | no |

main.tf

@@ -62,7 +62,9 @@ module "replicator_service_principal" {
   can_cancel_subscriptions_in_scopes = var.can_cancel_subscriptions_in_scopes
   can_delete_rgs_in_scopes           = var.can_delete_rgs_in_scopes
 
-  administrative_unit_name              = var.administrative_unit_name
+  administrative_unit_name            = var.administrative_unit_name
+  administrative_unit_membership_rule = var.administrative_unit_membership_rule
+
   additional_required_resource_accesses = var.additional_required_resource_accesses
   additional_permissions                = var.additional_permissions
 

modules/meshcloud-replicator-service-principal/README.md

@@ -4,7 +4,6 @@
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | > 1.0 |
-| <a name="requirement_azapi"></a> [azapi](#requirement\_azapi) | >=1.13.1 |
 | <a name="requirement_azuread"></a> [azuread](#requirement\_azuread) | >=3.0.2 |
 | <a name="requirement_azurerm"></a> [azurerm](#requirement\_azurerm) | >=4.11.0 |
 
@@ -17,17 +16,15 @@ No modules.
 | Name | Type |
 |------|------|
 | [azuread_administrative_unit.meshcloud_replicator_au](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/administrative_unit) | resource |
-| [azuread_administrative_unit_role_member.groups_admin_assignment](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/administrative_unit_role_member) | resource |
-| [azuread_administrative_unit_role_member.user_admin_assignment](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/administrative_unit_role_member) | resource |
 | [azuread_app_role_assignment.meshcloud_replicator-administrativeunit](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/app_role_assignment) | resource |
 | [azuread_app_role_assignment.meshcloud_replicator-directory](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/app_role_assignment) | resource |
 | [azuread_app_role_assignment.meshcloud_replicator-group](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/app_role_assignment) | resource |
 | [azuread_app_role_assignment.meshcloud_replicator-user](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/app_role_assignment) | resource |
 | [azuread_application.meshcloud_replicator](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application) | resource |
 | [azuread_application_federated_identity_credential.meshcloud_replicator](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application_federated_identity_credential) | resource |
 | [azuread_application_password.application_pw](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/application_password) | resource |
-| [azuread_directory_role.groups_administrator](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/directory_role) | resource |
-| [azuread_directory_role.user_administrator](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/directory_role) | resource |
+| [azuread_custom_directory_role.meshcloud_replicator_au_role](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/custom_directory_role) | resource |
+| [azuread_directory_role_assignment.meshcloud_replicator_au_assignment](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/directory_role_assignment) | resource |
 | [azuread_service_principal.meshcloud_replicator](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/resources/service_principal) | resource |
 | [azurerm_management_group_policy_assignment.privilege-escalation-prevention](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/management_group_policy_assignment) | resource |
 | [azurerm_policy_definition.privilege_escalation_prevention](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/policy_definition) | resource |
@@ -38,6 +35,7 @@ No modules.
 | [azurerm_role_definition.meshcloud_replicator_rg_deleter](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/role_definition) | resource |
 | [azurerm_role_definition.meshcloud_replicator_subscription_canceler](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/role_definition) | resource |
 | [terraform_data.allowed_assignments](https://registry.terraform.io/providers/hashicorp/terraform/latest/docs/resources/data) | resource |
+| [terraform_data.patch_admin_unit](https://registry.terraform.io/providers/hashicorp/terraform/latest/docs/resources/data) | resource |
 | [time_rotating.replicator_secret_rotation](https://registry.terraform.io/providers/hashicorp/time/latest/docs/resources/rotating) | resource |
 | [azuread_application_published_app_ids.well_known](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/data-sources/application_published_app_ids) | data source |
 | [azuread_application_template.enterprise_app](https://registry.terraform.io/providers/hashicorp/azuread/latest/docs/data-sources/application_template) | data source |
@@ -49,6 +47,7 @@ No modules.
 |------|-------------|------|---------|:--------:|
 | <a name="input_additional_permissions"></a> [additional\_permissions](#input\_additional\_permissions) | Additional Subscription-Level Permissions the Service Principal needs. | `list(string)` | `[]` | no |
 | <a name="input_additional_required_resource_accesses"></a> [additional\_required\_resource\_accesses](#input\_additional\_required\_resource\_accesses) | Additional AAD-Level Resource Accesses the Service Principal needs. | `list(object({ resource_app_id = string, resource_accesses = list(object({ id = string, type = string })) }))` | `[]` | no |
+| <a name="input_administrative_unit_membership_rule"></a> [administrative\_unit\_membership\_rule](#input\_administrative\_unit\_membership\_rule) | Dynamic membership rule for the Administrative Unit. Required when administrative\_unit\_name is set.<br><br>Suggested default: "(user.accountEnabled -eq true)"<br>NOTE: This rule will include ALL active users in your tenant. Consider more restrictive rules for production use.<br><br>Examples for more restrictive rules:<br>- "(user.companyName -eq \"MyCompany\") and (user.accountEnabled -eq true)" - Active users from specific company<br>- "(user.userType -eq \"Member\") and (user.accountEnabled -eq true)" - Active member users only<br><br>For more information on membership rules, see:<br>https://learn.microsoft.com/en-us/entra/identity/users/groups-dynamic-membership | `string` | `null` | no |
 | <a name="input_administrative_unit_name"></a> [administrative\_unit\_name](#input\_administrative\_unit\_name) | Display name of the adminstration-unit name where the user groups are managed. | `string` | `null` | no |
 | <a name="input_application_owners"></a> [application\_owners](#input\_application\_owners) | List of user principals that should be added as owners to the replicator service principal. | `list(string)` | `[]` | no |
 | <a name="input_assignment_scopes"></a> [assignment\_scopes](#input\_assignment\_scopes) | The scopes to which Service Principal permissions is assigned to. List of management group id of form `/providers/Microsoft.Management/managementGroups/<mgmtGroupId>/`. | `list(string)` | n/a | yes |

modules/meshcloud-replicator-service-principal/module.tf

@@ -12,10 +12,6 @@ terraform {
       source  = "hashicorp/azuread"
       version = ">=3.0.2"
     }
-    azapi = {
-      source  = "Azure/azapi"
-      version = ">=1.13.1"
-    }
   }
 }
 
@@ -133,29 +129,6 @@ resource "azuread_application" "meshcloud_replicator" {
       access_token_issuance_enabled = false
     }
   }
-  dynamic "required_resource_access" {
-    for_each = var.administrative_unit_name == null ? [] : [1]
-
-    content {
-      resource_app_id = data.azuread_application_published_app_ids.well_known.result.MicrosoftGraph
-
-      resource_access {
-        id   = data.azuread_service_principal.msgraph.app_role_ids["AdministrativeUnit.Read.All"]
-        type = "Role"
-      }
-
-      # resource_access {
-      #   id   = data.azuread_service_principal.msgraph.app_role_ids["Group.create"]
-      #   type = "Role"
-      # }
-
-      # resource_access {
-      #   id   = data.azuread_service_principal.msgraph.app_role_ids["User.Invite.All"]
-      #   type = "Role"
-      # }
-    }
-  }
-
 
   dynamic "required_resource_access" {
     for_each = var.additional_required_resource_accesses == null ? [] : var.additional_required_resource_accesses
@@ -327,9 +300,9 @@ resource "azurerm_management_group_policy_assignment" "privilege-escalation-prev
   ]
 }
 
-//--------------------------------------------------------------------------
+//---------------------------------------------------------------------------
 // Administrative Unit
-//--------------------------------------------------------------------------
+//---------------------------------------------------------------------------
 
 resource "azuread_administrative_unit" "meshcloud_replicator_au" {
   count        = var.administrative_unit_name == null ? 0 : 1
@@ -338,33 +311,73 @@ resource "azuread_administrative_unit" "meshcloud_replicator_au" {
 }
 
 //--------------------------------------------------------------------------
-// Built-in AU-scoped Roles
+// Update AU properties via Microsoft Graph API using az rest
 //--------------------------------------------------------------------------
 
-resource "azuread_directory_role" "user_administrator" {
-  count        = var.administrative_unit_name == null ? 0 : 1
-  display_name = "User Administrator"
+resource "terraform_data" "patch_admin_unit" {
+  count = var.administrative_unit_name == null ? 0 : 1
+
+  lifecycle {
+    precondition {
+      condition     = var.administrative_unit_membership_rule != null
+      error_message = "When administrative_unit_name is set, administrative_unit_membership_rule must also be provided. Suggested value: \"(user.accountEnabled -eq true)\""
+    }
+  }
+
+  provisioner "local-exec" {
+    command = <<-EOT
+      az rest \
+        --method PATCH \
+        --url "https://graph.microsoft.com/v1.0/directory/administrativeUnits/${azuread_administrative_unit.meshcloud_replicator_au[0].object_id}" \
+        --body '{
+          "displayName": "${var.administrative_unit_name}",
+          "membershipType": "Dynamic",
+          "membershipRule": "${var.administrative_unit_membership_rule}",
+          "membershipRuleProcessingState": "On"
+        }'
+    EOT
+  }
+
+  triggers_replace = {
+    au_id           = azuread_administrative_unit.meshcloud_replicator_au[0].object_id
+    display_name    = var.administrative_unit_name
+    membership_rule = var.administrative_unit_membership_rule
+  }
+
+  depends_on = [azuread_administrative_unit.meshcloud_replicator_au]
 }
+//--------------------------------------------------------------------------
+// Custom AU-scoped Role
+//--------------------------------------------------------------------------
 
-resource "azuread_directory_role" "groups_administrator" {
+resource "azuread_custom_directory_role" "meshcloud_replicator_au_role" {
   count        = var.administrative_unit_name == null ? 0 : 1
-  display_name = "Groups Administrator"
+  display_name = "meshStack Replicator AU Role"
+  description  = "Custom role for meshStack replicator with limited User and Group permissions"
+  enabled      = true
+  version      = "1.0"
+
+  # users permissions
+  permissions {
+    allowed_resource_actions = [
+      "microsoft.directory/users/standard/read",
+      "microsoft.directory/groups/create",
+      "microsoft.directory/groups/standard/read",
+      "microsoft.directory/groups/members/update",
+      "microsoft.directory/groups/members/read",
+      "microsoft.directory/groups/memberOf/read",
+      "microsoft.directory/administrativeUnits/members/read",
+      "microsoft.directory/administrativeUnits/members/update",
+    ]
+  }
 }
 
 //--------------------------------------------------------------------------
-// AU Role Assignments for meshcloud_replicator
+// AU Role Assignment for meshcloud_replicator
 //--------------------------------------------------------------------------
 
-resource "azuread_administrative_unit_role_member" "user_admin_assignment" {
-  count                         = var.administrative_unit_name == null ? 0 : 1
-  role_object_id                = azuread_directory_role.user_administrator[0].object_id
-  administrative_unit_object_id = azuread_administrative_unit.meshcloud_replicator_au[0].object_id
-  member_object_id              = azuread_service_principal.meshcloud_replicator.object_id
-}
-
-resource "azuread_administrative_unit_role_member" "groups_admin_assignment" {
-  count                         = var.administrative_unit_name == null ? 0 : 1
-  role_object_id                = azuread_directory_role.groups_administrator[0].object_id
-  administrative_unit_object_id = azuread_administrative_unit.meshcloud_replicator_au[0].object_id
-  member_object_id              = azuread_service_principal.meshcloud_replicator.object_id
+resource "azuread_directory_role_assignment" "meshcloud_replicator_au_assignment" {
+  count               = var.administrative_unit_name == null ? 0 : 1
+  role_id             = azuread_custom_directory_role.meshcloud_replicator_au_role[0].object_id
+  principal_object_id = azuread_service_principal.meshcloud_replicator.object_id
 }

modules/meshcloud-replicator-service-principal/variables.tf

@@ -65,3 +65,21 @@ variable "application_owners" {
   description = "List of user principals that should be added as owners to the replicator service principal."
   default     = []
 }
+
+variable "administrative_unit_membership_rule" {
+  type        = string
+  default     = null
+  description = <<-EOT
+    Dynamic membership rule for the Administrative Unit. Required when administrative_unit_name is set.
+
+    Suggested default: "(user.accountEnabled -eq true)"
+    NOTE: This rule will include ALL active users in your tenant. Consider more restrictive rules for production use.
+
+    Examples for more restrictive rules:
+    - "(user.companyName -eq \"MyCompany\") and (user.accountEnabled -eq true)" - Active users from specific company
+    - "(user.userType -eq \"Member\") and (user.accountEnabled -eq true)" - Active member users only
+
+    For more information on membership rules, see:
+    https://learn.microsoft.com/en-us/entra/identity/users/groups-dynamic-membership
+  EOT
+}