☁️ Azure Managed HSM Role Assignment Terraform Module

Grants a Managed HSM local RBAC role to a principal. This is the authorization system Azure RBAC cannot reach. Targets hashicorp/azurerm ~> 4.0.

• ☁️ Creates one azurerm_key_vault_managed_hardware_security_module_role_assignment (the keystone this) — a data-plane grant on a Managed HSM.
• 🔴 Records why this module exists at all: Managed HSM local RBAC is a separate authorization system from Azure RBAC, so azurerm_role_assignment cannot do this job.
• 🔴 States the dependency trap plainly: nothing consumes this module's outputs, yet other resources cannot be created without it — so depends_on is required, and its absence produces a configuration that fails once and then succeeds.
• 🧮 Derives is_hsm_wide_scope, because /keys and /keys/prod-cmk differ by a few characters and by the whole blast radius of the grant.
• ⚠️ Names the mistake it cannot catch: an application ID and an object ID are both GUIDs, and passing the wrong one fails silently.

💡 Why it matters: this is the resource that decides who can use the keys. Getting the scope wrong is the difference between an application that can use its own key and one that can use every key the HSM will ever hold.

If this module saves you time:

• ⭐ Star the repository — it helps others find it.
• 🤝 Connect on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

flowchart TB
  rg["terraform-azurerm-resource-group"]
  mhsm["terraform-azurerm-key-vault-managed-hardware-security-module  ARM Microsoft.KeyVault/managedHSMs"]
  rdef["terraform-azurerm-key-vault-managed-hardware-security-module-role-definition  only when a built-in role is too broad"]
  builtin["Built-in local roles  Crypto User, Crypto Officer, Administrator, Crypto Auditor  already exist"]
  ra["terraform-azurerm-key-vault-managed-hardware-security-module-role-assignment"]
  key["terraform-azurerm-key-vault-managed-hardware-security-module-key  cannot be created without the grant"]
  rot["terraform-azurerm-key-vault-managed-hardware-security-module-key-rotation-policy"]

  rg -->|"name and location"| mhsm
  mhsm -->|"id as managed_hsm_id, an ARM path"| rdef
  mhsm -->|"id as managed_hsm_id"| ra
  rdef -->|"resource_manager_id as role_definition_id  NOT its id"| ra
  builtin -.->|"or a built-in role path, needing no definition resource"| ra
  ra -.->|"depends_on, because nothing references it"| key
  ra -.->|"depends_on"| rot

  classDef this fill:#0078D4,stroke:#004578,color:#ffffff;
  classDef keystone fill:#004578,stroke:#00243c,color:#ffffff;
  classDef neutral fill:#F3F2F1,stroke:#8A8886,color:#201F1E;
  class ra this;
  class mhsm keystone;
  class rg,rdef,builtin,key,rot neutral;

Two edges tell the story. The solid one from the role definition carries resource_manager_id, not id — the assignment wants the path without the HSM base URL. And every edge out of this module is dotted, because they are depends_on relationships rather than data references: nothing reads this resource's outputs.

flowchart TB
  n["name  a GUID YOU choose, force-new"]
  hsm["managed_hsm_id  ARM path, force-new  rejects hsm_uri and a vault ID"]
  sc["scope  slash, slash-keys, or slash-keys-slash-name  force-new  rejects an Azure RBAC scope"]
  rdid["role_definition_id  starts /Microsoft.KeyVault/  force-new  rejects both an ARM path and the https form"]
  pid["principal_id  an Entra OBJECT id, force-new"]
  to["timeouts  only THREE: create, read, delete"]

  res["azurerm_key_vault_managed_hardware_security_module_role_assignment.this"]

  wide["is_hsm_wide_scope  the most consequential line in the plan"]
  skey["scoped_key_name  null when HSM-wide"]
  role["recognised_builtin_role_name  null rather than a guess"]
  appid["an_application_id_passed_here_cannot_be_distinguished_from_an_object_id"]
  prereq["this_assignment_is_a_prerequisite_that_nothing_references"]

  n --> res
  hsm --> res
  sc --> res
  rdid --> res
  pid --> res
  to --> res
  sc --> wide
  sc --> skey
  rdid --> role
  pid --> appid
  res --> prereq

  classDef this fill:#0078D4,stroke:#004578,color:#ffffff;
  classDef neutral fill:#F3F2F1,stroke:#8A8886,color:#201F1E;
  class res this;
  class n,hsm,sc,rdid,pid,to,wide,skey,role,appid,prereq neutral;

Five arguments plus timeouts. All five are force-new, which is why timeouts has only three keys.

Schema notes that bite:

• 🔴 This is not azurerm_role_assignment. Managed HSM local RBAC is a separate authorization system, with its own scopes, its own role definitions and its own CLI (az keyvault role assignment, not az role assignment).
• 🔴 timeouts has only three keys — create, read, delete. There is no update. Copy a four-key block from a sibling module and the update entry is discarded silently.
• 🔴 role_definition_id is a third ID convention, beginning /Microsoft.KeyVault/ with no subscription in it. Wire the role-definition module's resource_manager_id, not its id.
• 🔴 name is a GUID you supply, not one Azure allocates. There is no default.
• 🔴 scope is a local-RBAC path, not a Resource ID. Only /, /keys and /keys/<key-name> exist.
• 🔴 Nothing references this resource, and things depend on it. See Architecture Notes.
• ⚠️ principal_id is the Entra object ID. An application ID is the same shape and grants nothing.
• ⚠️ No tags — the provider exposes none.
• ⚠️ resource_id is a deprecated attribute and is deliberately not emitted.
• ⚠️ Force-new: every argument.
• ⚠️ lifecycle is not valid inside a module block, though depends_on is.

Two planes, and creating this resource needs the one Azure RBAC cannot grant.

🔴 Assigning a role is itself a data-plane operation, governed by the Microsoft.KeyVault/managedHsm/roleAssignments/write/action data action — which is held by Administrator, not by Crypto User or Crypto Officer. So an identity that can use keys generally cannot grant access to them, which is the correct separation and a common surprise.

⚠️ The bootstrap problem is real. A brand-new Managed HSM has exactly the administrators listed in its admin_object_ids, set at creation. Terraform must run as one of them — or as a member of a group that is one — to create any assignment at all.

🔒 Assign administrative roles to Entra security groups, not individuals. Microsoft recommends it because a deleted user account can leave an HSM with no administrator and no route back in. Consider PIM for just-in-time elevation.

• An existing, activated Managed HSM, and its ARM Resource ID.
• Terraform running as a Managed HSM Administrator on that HSM.
• A role definition to grant — either a built-in role's UUID, or a custom one from terraform-azurerm-key-vault-managed-hardware-security-module-role-definition.
• The principal's Entra object ID.
• A GUID for name, generated once and kept stable.
• The caller configures the provider "azurerm" { features {} } block, auth, and subscription; this module declares none of these.

terraform-azurerm-key-vault-managed-hardware-security-module-role-assignment/
├── providers.tf     # required_version + pinned azurerm; no provider block
├── variables.tf     # 6 inputs, 13 validations
├── main.tf          # the keystone `this` + scope- and role-parsing locals
├── outputs.tf       # id first, then what the module cannot catch
├── README.md        # this file
├── SCOPE.md         # the cross-module contract
├── LICENSE          # MIT
└── .gitignore

provider "azurerm" {
  features {}
}

data "azurerm_client_config" "current" {}

module "crypto_user" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-role-assignment.git?ref=v1.0.0"

  name           = "1e243909-064c-6ac3-84e9-1c8bf8d6ad22"
  managed_hsm_id = module.managed_hsm.id

  # Least privilege: one key, not the whole HSM.
  scope = "/keys/key-storage-cmk"

  role_definition_id = "/Microsoft.KeyVault/providers/Microsoft.Authorization/roleDefinitions/21dbd100-6940-42c2-9190-5d6cb909625b"
  principal_id       = data.azurerm_client_config.current.object_id
}

💡 That UUID is the built-in Managed HSM Crypto User role. No role-definition resource is needed to use it.

Consumes

Emits

module "crypto_user" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-role-assignment.git?ref=v1.0.0"

  name               = "1e243909-064c-6ac3-84e9-1c8bf8d6ad22"
  managed_hsm_id     = module.managed_hsm.id
  scope              = "/keys/key-storage-cmk"
  role_definition_id = "/Microsoft.KeyVault/providers/Microsoft.Authorization/roleDefinitions/21dbd100-6940-42c2-9190-5d6cb909625b"
  principal_id       = data.azurerm_client_config.current.object_id
}

module "crypto_user" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-role-assignment.git?ref=v1.0.0"

  name               = "1e243909-064c-6ac3-84e9-1c8bf8d6ad22"
  managed_hsm_id     = module.managed_hsm.id
  scope              = "/keys"
  role_definition_id = "/Microsoft.KeyVault/providers/Microsoft.Authorization/roleDefinitions/21dbd100-6940-42c2-9190-5d6cb909625b"
  principal_id       = data.azurerm_client_config.current.object_id
}

module "hsm_key" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-key.git?ref=v1.0.0"

  name           = "key-storage-cmk"
  managed_hsm_id = module.managed_hsm.id
  key_type       = "RSA-HSM"
  key_size       = 4096
  key_opts       = ["wrapKey", "unwrapKey"]

  # REQUIRED. The key does not reference this assignment, so Terraform sees no
  # dependency and is free to attempt the key first.
  depends_on = [module.crypto_user]
}

module "wrap_only_role" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-role-definition.git?ref=v1.0.0"

  name           = "7b6d2b5a-1c4e-4f6a-9a1e-2c3d4e5f6a7b"
  managed_hsm_id = module.managed_hsm.id
  role_name      = "Wrap and Unwrap Only"

  permissions = [{
    data_actions = [
      "Microsoft.KeyVault/managedHsm/keys/wrap/action",
      "Microsoft.KeyVault/managedHsm/keys/unwrap/action",
    ]
  }]
}

module "wrap_only_assignment" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-role-assignment.git?ref=v1.0.0"

  name           = "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c"
  managed_hsm_id = module.managed_hsm.id
  scope          = "/keys/key-storage-cmk"

  # `resource_manager_id`, NOT `id`. The id carries the HSM base URL and is rejected.
  role_definition_id = module.wrap_only_role.resource_manager_id
  principal_id       = var.application_object_id
}

# Rejected -- an Azure RBAC role definition ID. Those DO begin /subscriptions/.
role_definition_id = "/subscriptions/.../providers/Microsoft.Authorization/roleDefinitions/21dbd100-..."

# Rejected -- the role-definition module's `id`, with the HSM base URL.
role_definition_id = "https://hsm-prod.managedhsm.azure.net//Microsoft.KeyVault/providers/..."

# Accepted.
role_definition_id = "/Microsoft.KeyVault/providers/Microsoft.Authorization/roleDefinitions/21dbd100-6940-42c2-9190-5d6cb909625b"

output "check_the_blast_radius" {
  value = {
    hsm_wide = module.crypto_user.is_hsm_wide_scope
    key      = module.crypto_user.scoped_key_name
  }
}

# Rejected -- an Azure RBAC scope. Local RBAC does not use Resource IDs.
scope = "/subscriptions/.../resourceGroups/rg-hsm"

# Rejected -- no such shape. There is no per-version scope.
scope = "/keys/key-storage-cmk/9a8b7c6d"

# Rejected -- empty.
scope = ""

# Accepted.
scope = "/keys"
scope = "/keys/key-storage-cmk"
scope = "/"

output "read_this_when_a_grant_seems_to_do_nothing" {
  # Always true.
  value = module.crypto_user.an_application_id_passed_here_cannot_be_distinguished_from_an_object_id
}

# WRONG -- the application (client) id, shown first on an app registration blade.
# 11111111-2222-3333-4444-555555555555

# RIGHT -- the service principal's OBJECT id.
az ad sp show --id 11111111-2222-3333-4444-555555555555 --query id -o tsv

output "what_am_i_granting" {
  value = {
    uuid = module.crypto_user.role_definition_uuid
    name = module.crypto_user.recognised_builtin_role_name
  }
}

# Crypto User
name = "Managed HSM Crypto User"

# A custom role, or a built-in one this module does not hard-code
name = null

variable "grants" {
  type = map(object({
    role_uuid    = string
    scope        = string
    principal_id = string
    name         = string
  }))
  default = {
    terraform_ci = {
      role_uuid    = "21dbd100-6940-42c2-9190-5d6cb909625b" # Crypto User
      scope        = "/keys"
      principal_id = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      name         = "1e243909-064c-6ac3-84e9-1c8bf8d6ad22"
    }
    rotation_officer = {
      role_uuid    = "515eb02d-2335-4d2d-92f2-b1cbdf9c3778" # Crypto Officer
      scope        = "/keys/key-storage-cmk"
      principal_id = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      name         = "1e243909-064c-6ac3-84e9-1c8bf8d6ad23"
    }
  }
}

module "grants" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-role-assignment.git?ref=v1.0.0"
  for_each = var.grants

  name               = each.value.name
  managed_hsm_id     = module.managed_hsm.id
  scope              = each.value.scope
  role_definition_id = "/Microsoft.KeyVault/providers/Microsoft.Authorization/roleDefinitions/${each.value.role_uuid}"
  principal_id       = each.value.principal_id
}

output "blast_radius_review" {
  value = { for k, m in module.grants : k => {
    hsm_wide = m.is_hsm_wide_scope
    key      = m.scoped_key_name
    role     = m.recognised_builtin_role_name
  } }
}

module "crypto_user" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-role-assignment.git?ref=v1.0.0"

  name               = "1e243909-064c-6ac3-84e9-1c8bf8d6ad22"
  managed_hsm_id     = module.managed_hsm.id
  scope              = "/keys"
  role_definition_id = "/Microsoft.KeyVault/providers/Microsoft.Authorization/roleDefinitions/21dbd100-6940-42c2-9190-5d6cb909625b"
  principal_id       = data.azurerm_client_config.current.object_id

  timeouts = {
    create = "10m"
    read   = "5m"
    delete = "10m"
    # An `update` key here would be DISCARDED SILENTLY -- there is no update
    # operation, because every argument is force-new.
  }
}

output "why_there_is_no_resource_id_output" {
  # Always true.
  value = module.crypto_user.the_deprecated_resource_id_attribute_is_deliberately_not_emitted
}

# Both are often needed, and they do different jobs.
module "hsm_contributor" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-role-assignments.git?ref=v1.0.0"

  scope = module.managed_hsm.id

  role_assignments = {
    manage_the_resource = {
      principal_id         = data.azurerm_client_config.current.object_id
      role_definition_name = "Managed HSM Contributor"
    }
  }
}

provider "azurerm" {
  features {}
}

data "azurerm_client_config" "current" {}

variable "location" {
  type    = string
  default = "eastus2"
}

module "rg" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-resource-group.git?ref=v1.0.0"

  name     = "rg-hsm-prod"
  location = var.location

  tags = { environment = "prod" }
}

module "managed_hsm" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module.git?ref=v1.0.0"

  name                = "hsm-prod-eastus2"
  resource_group_name = module.rg.name
  location            = var.location
  tenant_id           = data.azurerm_client_config.current.tenant_id

  # Terraform must be an administrator to create any assignment at all.
  admin_object_ids = [data.azurerm_client_config.current.object_id]

  tags = { environment = "prod" }
}

# A custom role, because no built-in role expresses wrap/unwrap without sign.
module "wrap_only_role" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-role-definition.git?ref=v1.0.0"

  name           = "7b6d2b5a-1c4e-4f6a-9a1e-2c3d4e5f6a7b"
  managed_hsm_id = module.managed_hsm.id
  role_name      = "Wrap and Unwrap Only"
  description    = "Envelope encryption for the storage CMK. No sign, no export, no delete."

  permissions = [{
    data_actions = [
      "Microsoft.KeyVault/managedHsm/keys/wrap/action",
      "Microsoft.KeyVault/managedHsm/keys/unwrap/action",
      "Microsoft.KeyVault/managedHsm/keys/read/action",
    ]
  }]
}

# THIS MODULE, twice. Terraform needs Crypto User HSM-wide to create keys...
module "terraform_crypto_user" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-role-assignment.git?ref=v1.0.0"

  name               = "1e243909-064c-6ac3-84e9-1c8bf8d6ad22"
  managed_hsm_id     = module.managed_hsm.id
  scope              = "/keys"
  role_definition_id = "/Microsoft.KeyVault/providers/Microsoft.Authorization/roleDefinitions/21dbd100-6940-42c2-9190-5d6cb909625b"
  principal_id       = data.azurerm_client_config.current.object_id
}

# ...and Crypto Officer to write a rotation policy and perform the rotations.
module "terraform_crypto_officer" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-role-assignment.git?ref=v1.0.0"

  name               = "1e243909-064c-6ac3-84e9-1c8bf8d6ad23"
  managed_hsm_id     = module.managed_hsm.id
  scope              = "/keys"
  role_definition_id = "/Microsoft.KeyVault/providers/Microsoft.Authorization/roleDefinitions/515eb02d-2335-4d2d-92f2-b1cbdf9c3778"
  principal_id       = data.azurerm_client_config.current.object_id
}

# The application gets the custom role, at ONE key only.
module "app_wrap_only" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-role-assignment.git?ref=v1.0.0"

  name               = "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c"
  managed_hsm_id     = module.managed_hsm.id
  scope              = "/keys/key-storage-cmk"
  role_definition_id = module.wrap_only_role.resource_manager_id
  principal_id       = var.application_object_id
}

module "hsm_key" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-key.git?ref=v1.0.0"

  name           = "key-storage-cmk"
  managed_hsm_id = module.managed_hsm.id
  key_type       = "RSA-HSM"
  key_size       = 4096
  key_opts       = ["wrapKey", "unwrapKey"]

  tags = { environment = "prod" }

  # The grants do not appear in this module's arguments, so the edge must be explicit.
  depends_on = [module.terraform_crypto_user, module.terraform_crypto_officer]
}

module "hsm_key_rotation" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-key-vault-managed-hardware-security-module-key-rotation-policy.git?ref=v1.0.0"

  managed_hsm_key_id = module.hsm_key.id
  expire_after       = "P90D"
  time_before_expiry = "P30D"

  depends_on = [module.terraform_crypto_officer]
}

output "authorization_review" {
  value = {
    terraform_user     = module.terraform_crypto_user.is_hsm_wide_scope
    terraform_officer  = module.terraform_crypto_officer.is_hsm_wide_scope
    app_scope_is_wide  = module.app_wrap_only.is_hsm_wide_scope
    app_key            = module.app_wrap_only.scoped_key_name
    app_role           = module.wrap_only_role.role_name
    app_effective      = module.wrap_only_role.effective_data_actions
  }
}

variable "name" { type = string }               # GUID-validated
variable "managed_hsm_id" { type = string }      # anchored ARM path; rejects hsm_uri and a vault ID
variable "scope" { type = string }               # closed set: "/", "/keys", "/keys/<name>"
variable "role_definition_id" { type = string }  # rejects an ARM path and the https form
variable "principal_id" { type = string }        # GUID-validated; object vs application id is undetectable

variable "timeouts" {
  type = object({
    create = optional(string)
    read   = optional(string)
    delete = optional(string)
  })
  default = null
}

🔒 Nothing is sensitive. A role definition path is a permission reference and an object ID identifies a principal; neither grants anything on its own, and redacting them would obstruct exactly the review these outputs exist for.

Managed HSM local RBAC is a separate authorization system, and that is the whole reason this resource exists. Microsoft documents a dual-plane model: the control plane at management.azure.com is governed by Azure RBAC, and the data plane at <hsm>.managedhsm.azure.net by local RBAC. Using a key is a data-plane operation, so azurerm_role_assignment — which grants Azure RBAC roles at Resource ID scopes — cannot grant it. The two systems have different scopes, different role definition paths and different CLI commands, and Azure's security baseline records "Azure RBAC for Data Plane: Supported — False" for this service.

Nothing references this resource, and other resources cannot be created without it. That combination is unusual and it is the module's sharpest trap. A Managed HSM key needs a Crypto User grant to exist before Terraform can create it — but the key does not reference the assignment, so Terraform sees no dependency and is free to attempt the key first. The result is a configuration that fails on a first apply and succeeds on a second, which reads like eventual consistency and is actually a missing edge in the graph. The fix is depends_on from each consumer to this module, in the composition. depends_on is valid on a module block; it is lifecycle that is not, and this suite repeats that caveat often enough to be worth disambiguating.

Three ID conventions live in this family and this module touches two of them. managed_hsm_id is an ARM Resource ID. role_definition_id is a provider-relative path beginning /Microsoft.KeyVault/ with no subscription in it at all — so the role-definition module's resource_manager_id is the output to wire, not its id, which carries the HSM's data-plane base URL. Elsewhere in the family a key's id is a data-plane URI. Each of the wrong forms is rejected by name, and the most valuable rejection is an Azure RBAC role definition ID: those genuinely begin /subscriptions/, are well-formed, and belong to a different resource entirely.

Every argument is force-new, which is why timeouts has three keys instead of four. There is no update operation to time out. This is coherent rather than an oversight, but it interacts badly with object-type conversion: a four-key timeouts block copied from the sibling key or role-definition module loses its update entry silently, with no error anywhere. That is the one place a wrong input to this module produces no signal at all.

scope is a genuinely closed set, and the module enforces it as one. Microsoft documents / or /keys for the whole HSM and /keys/<key-name> for a single key — nothing else, and in particular no per-version scope, so an assignment always covers every version of the key it names and rotation never changes its reach. Because the set is closed rather than an open list of examples, this is one of the few places in this library where an unrecognised value is rejected outright rather than allowed through. The derived is_hsm_wide_scope exists because /keys and /keys/prod-cmk differ by a handful of characters and by the entire blast radius of the grant, and a plan shows only the string.

The one mistake the module cannot catch is the one most likely to be made. A service principal has an application (client) ID and an object ID; principal_id wants the object ID; both are 36-character GUIDs with nothing in their shape to tell them apart. So the module validates GUID-ness and can do no more. The failure is silent — Azure accepts an assignment against a principal that is not a directory object, and the intended application is denied everything — which is why it is emitted as a constant output with the az ad sp show command that answers it.

Two decisions about attributes are worth stating. resource_id is marked (Deprecated) by the provider and is deliberately not emitted: an output is an interface, and re-exposing a field the provider intends to remove would make its removal a breaking change here. By contrast the role-definition sibling's similarly-named resource_manager_id is not deprecated and is emitted, because it is the value this module consumes. And there are no tags — the provider exposes none on either role resource, while the Managed HSM key does, so the answer varies resource by resource across this family and cannot be inferred from a neighbour.

Finally, assigning a role is itself an administrative act. The roleAssignments/write data action belongs to Managed HSM Administrator, not to Crypto User or Crypto Officer — so an identity that can use keys generally cannot grant access to them. On a brand-new HSM the only administrators are those listed in admin_object_ids at creation, so Terraform must run as one of them to create any assignment at all. Microsoft's advice to assign administrative roles to Entra security groups rather than individuals matters most here: a deleted user account can leave an HSM with no administrator and no route back in.

terraform init -backend=false
terraform validate
terraform fmt -check

Pin the module with ?ref=v1.0.0 — never a branch. Plan-only; a human applies from CI.

Before the first apply:

# Confirm Terraform's identity is an HSM administrator.
az keyvault role assignment list --hsm-name hsm-prod-eastus2 --assignee <object-id> --scope /

# Get the OBJECT id for a service principal -- not its application id.
az ad sp show --id <application-id> --query id -o tsv

After the apply:

# What was actually granted, and where.
az keyvault role assignment list --hsm-name hsm-prod-eastus2 -o table

# NOTE: a scope of / or /keys does NOT list key-level assignments -- query those separately.
az keyvault role assignment list --hsm-name hsm-prod-eastus2 --scope /keys/key-storage-cmk -o table

What the offline gate proves: that the configuration parses against the pinned provider, that formatting is canonical, and — via terraform console with variables files — that all 13 validations fire on the input each targets. No validation on this module references another variable, so validation suppression is not a factor here and grouping was by intent rather than by dependency.

Proved with a failing value each: an empty name and a friendly name where a GUID belongs; the parent's hsm_uri and a Key Vault ID in managed_hsm_id; an empty scope, an Azure RBAC scope, and a per-version scope that does not exist; an empty role_definition_id, an Azure RBAC role definition ID, and the role-definition module's id with its https:// base URL; and an empty principal_id plus a display name where a GUID belongs.

Every derived value was printed rather than reasoned about, against all three scope shapes. is_hsm_wide_scope returned true for both / and /keys with scoped_key_name = null, and false for /keys/key-storage-cmk with the key name parsed correctly. recognised_builtin_role_name returned "Managed HSM Crypto User" and "Managed HSM Crypto Officer" for the two known UUIDs and null for an unrecognised one — confirming it declines rather than guesses. The parsed HSM name and resource group were checked against a real ARM ID.

One harness note worth recording: Git Bash rewrites any -var value beginning with a slash into a Windows path, so -var 'scope=/keys' arrived as C:/Program Files/Git/keys and produced a wrong answer that looked like a module defect. Every slash-leading value was moved into a variables file.

What only an apply exercises: whether the HSM exists, and whether Terraform's identity is an HSM administrator — the most likely failure.

What no Terraform run exercises at all: whether principal_id is the object ID rather than the application ID, and whether the granted role actually permits what the application needs.

Outputs:

an_application_id_passed_here_cannot_be_distinguished_from_an_object_id = true
id = "https://hsm-prod-eastus2.managedhsm.azure.net//providers/Microsoft.Authorization/roleAssignments/1e243909-064c-6ac3-84e9-1c8bf8d6ad22"
is_hsm_wide_scope = false
managed_hsm_id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-hsm-prod/providers/Microsoft.KeyVault/managedHSMs/hsm-prod-eastus2"
managed_hsm_name = "hsm-prod-eastus2"
managed_hsm_resource_group = "rg-hsm-prod"
name = "1e243909-064c-6ac3-84e9-1c8bf8d6ad22"
principal_id = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
recognised_builtin_role_name = "Managed HSM Crypto User"
role_definition_id = "/Microsoft.KeyVault/providers/Microsoft.Authorization/roleDefinitions/21dbd100-6940-42c2-9190-5d6cb909625b"
role_definition_uuid = "21dbd100-6940-42c2-9190-5d6cb909625b"
scope = "/keys/key-storage-cmk"
scoped_key_name = "key-storage-cmk"
the_deprecated_resource_id_attribute_is_deliberately_not_emitted = true
this_assignment_is_a_prerequisite_that_nothing_references = true
this_resource_carries_no_tags = true

• azurerm_key_vault_managed_hardware_security_module_role_assignment provider reference
• Microsoft Learn — Access control for Managed HSM
• Microsoft Learn — Managed HSM local RBAC built-in roles
• Microsoft Learn — Managed HSM role management
• Parent: terraform-azurerm-key-vault-managed-hardware-security-module — supplies managed_hsm_id from its id output, and sets the initial administrators.
• Sibling: terraform-azurerm-key-vault-managed-hardware-security-module-role-definition — supplies role_definition_id from its resource_manager_id output. Needed only where a built-in role is too broad.
• Depends on this module: terraform-azurerm-key-vault-managed-hardware-security-module-key and …-key-rotation-policy — both require a grant before they can be created, via depends_on.
• Contrast: terraform-azurerm-role-assignments — Azure RBAC, for managing the HSM resource. A different system for a different job.
• This module's SCOPE.md.

💙 "Infrastructure as Code should be standardized, consistent, and secure."