☁️ Azure Trusted Signing Account Terraform Module

TRADITIONAL code signing:   you hold a certificate and its PRIVATE KEY
                            -> you must protect it, rotate it, and survive its theft
                            -> a stolen signing key is a supply-chain incident

TRUSTED SIGNING:            Microsoft holds the key in an HSM
                            -> there is no private key for you to store or leak
                            -> access is an Azure role assignment, revocable instantly

✅ The security argument is straightforward and real: the most damaging thing about a code-signing certificate is that it exists as a file somebody can steal. Removing the file removes that risk, and replaces "protect this key forever" with "manage who can call this endpoint", which is a problem Azure is good at.

⚠️ And the trade-off is equally real: the key is not yours. It is not exportable, not portable to another provider, and not usable outside this service. If your signing story has to survive leaving Azure, that is a decision to make now rather than later.

ℹ️ This module emits both facts as constants, because they cut in opposite directions and both matter:

output "keys" { value = module.signing.signing_keys_are_microsoft_held } # always true

💡 Nothing in this module accepts, emits or stores a private key — not because of a design choice here, but because there is no such value in the service.

/subscriptions/.../resourceGroups/rg-release/providers/
    Microsoft.CodeSigning/codeSigningAccounts/sign-contoso-prod
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    not "TrustedSigning" anywhere

ℹ️ The service is called Trusted Signing; the ARM resource provider is Microsoft.CodeSigning. The Terraform resource name follows the product, and the Resource ID follows the API — so they disagree, and both are correct.

⚠️ Where that bites: writing an import command by hand (example 9), scoping a role assignment, searching Azure Resource Graph, or reading an activity log and looking for the wrong provider name.

✅ So take the ID from the module rather than constructing it:

module "signing_rbac" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-role-assignments.git?ref=v1.0.0"
  scope  = module.signing.id # ✅ not a hand-written path
  # ...
}

💡 This is a small thing that costs real time when you hit it, which is why the module's id output says so in its own description rather than leaving it to be discovered.

WHAT YOU NEED TO SIGN                      MANAGED BY
------------------------------------------------------------------
a Trusted Signing account                  ✅ this module
a CERTIFICATE PROFILE on that account      ❌ not modelled by the provider
an identity for the build agent            ✅ a sibling module
a signing role assignment on the account   ✅ a sibling module (example 4)
publisher identity validation              ❌ Microsoft's process (example 8)

🔴 The certificate profile is the gap that matters most, because it is the one people do not expect. The provider offers no resource for it, so it is created through the portal, the CLI or the API — and without it the account exists, the plan is clean, and signing fails.

⚠️ And it fails at signing time, which is to say in a release pipeline, probably out of hours, probably to somebody who did not build the infrastructure.

✅ So the module states its own incompleteness as an output, which is unusual and earns its place here:

output "incomplete" { value = module.signing.requires_certificate_profile } # always true

💡 A constant true is a weak signal in general. It is worth having in this case because nothing else in Terraform state hints that the resource you just created cannot do the job on its own, and the alternative is a comment in a file nobody reads.

ℹ️ Practical advice: create the profile once, by hand, and record the how in your release documentation — then treat this module as managing the account's lifecycle and access, which is what it can genuinely own.

# The endpoint a build agent signs through.
output "uri" { value = module.signing.account_uri }

🔴 Holding that URI confers no ability to sign. The build agent's identity needs a Trusted Signing role assignment on the account itself — a separate grant, on another module's terms, invisible to any plan here.

module "signing_rbac" {
  source = "git::https://github.com/microsoftexpert/terraform-azurerm-role-assignments.git?ref=v1.0.0"

  scope = module.signing.id

  role_assignments = {
    ci_signer = {
      role_definition_name = "Trusted Signing Certificate Profile Signer"
      principal_id         = var.ci_identity_object_id
    }
  }
}

⚠️ Check the current role name against Microsoft's documentation rather than trusting the string above indefinitely. Role names for newer services do change, and this library would rather point you at the source of truth than bake in a value that quietly goes stale.

✅ Prefer workload-identity federation for the CI identity — GitHub Actions or Azure DevOps authenticating to Azure with no standing secret. A code-signing pipeline is precisely where you do not want a long-lived client secret sitting in a variable group.

💡 And keep the signing grant narrow. Anyone who can sign through this account can produce artifacts your users will trust. That is a small group, and it is not the same group as "people who can deploy".

sku_name = "Basic"   # start here
sku_name = "Premium" # move up when you need to

✅ It updates in place, which is genuinely unusual: most SKU arguments in this provider force replacement, so a tier change means rebuilding the resource. Here it is an ordinary apply.

💡 Which makes starting on Basic the sensible default. There is no penalty for being wrong, and no migration to plan.

ℹ️ The tiers differ in quota and in how many certificate profiles an account may hold. This module deliberately does not restate Microsoft's current limits — they change, and a stale number in a module description is worse than a pointer to the source of truth.

Error: Invalid value for variable

  sku_name must be Basic or Premium.

✅ Validated against the closed set, so a typo or an invented tier is caught at plan.

locals {
  signing_accounts = {
    prod = { sku = "Premium", location = "eastus" }
    test = { sku = "Basic", location = "eastus" }
  }
}

module "signing" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-trusted-signing-account.git?ref=v1.0.0"
  for_each = local.signing_accounts

  name                = "sign-contoso-${each.key}"
  resource_group_name = module.rg.name
  location            = each.value.location
  sku_name            = each.value.sku

  tags = { environment = each.key }
}

✅ Separating production signing from test signing is worth the second account. A test pipeline that can sign with the production account can produce artifacts your users trust, which is exactly the outcome code signing exists to prevent.

💡 And the separation is enforced by RBAC, not by the accounts themselves — so the real work is giving each pipeline a role assignment on only its own account (example 4).

⚠️ Do not multiply accounts beyond that. Each one needs its own certificate profile created by hand (example 3), so accounts are more expensive to operate than they look in Terraform.

ℹ️ for_each lives in the caller; the module manages one account.

output "signing_review" {
  value = {
    id         = module.signing.id           # ℹ️ says Microsoft.CodeSigning
    uri        = module.signing.account_uri  # grants nothing on its own
    sku        = module.signing.sku_name
    premium    = module.signing.is_premium_sku
    incomplete = module.signing.requires_certificate_profile # always true
    ms_keys    = module.signing.signing_keys_are_microsoft_held # always true
  }
}

🔴 incomplete is the line worth reading before a release. It is a constant, and it says the thing Terraform state otherwise cannot: this account needs a certificate profile that no plan created (example 3).

⚠️ uri invites the wrong conclusion, which is why its own description says so. An endpoint in an output looks like a capability; the capability is a role assignment (example 4).

💡 What no output can tell you is who can actually sign. That is a role-assignment question, on a different module's scope, and it is the most security-relevant fact about this account.

Trusted Signing also requires, outside Terraform entirely:
  - an eligible subscription and publisher
  - IDENTITY VALIDATION of the publishing organisation, by Microsoft
  - agreement to the service's terms
  - a certificate profile bound to that validated identity (example 3)

⚠️ Identity validation is a process with a lead time, not a setting. Microsoft verifies the publishing organisation before it will issue certificates on your behalf, and no amount of Terraform makes that faster.

💡 So plan the account creation and the validation in parallel, not in sequence. Creating the account is instant; being allowed to sign is not.

ℹ️ This module deliberately does not describe the current requirements or timelines. They are Microsoft's, they change, and a module README repeating them would go stale in a way that is worse than useless — it would look authoritative. The service's own documentation is the source of truth.

✅ What this module can honestly offer is the account, its tier, its tags, and a id to scope the signing grant to. Everything above is somebody's project-management problem, and it is better named than omitted.

terraform import 'module.signing.azurerm_trusted_signing_account.this' \
  "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-release/providers/Microsoft.CodeSigning/codeSigningAccounts/sign-contoso-prod"

ℹ️ Note Microsoft.CodeSigning/codeSigningAccounts in that path (example 2). Constructing it from the product name is the most likely way to get an import wrong here.

✅ Importing is comfortable otherwise — only name, resource_group_name and location are force-new, and all three appear in the Resource ID itself. A sku_name mismatch proposes an in-place change.

✅ Importing is also the likely path in practice, since the certificate profile has probably already been created by hand against an existing account (example 3).

What a destroy removes

terraform destroy on this module:
  removes the account  ->  and its certificate profiles with it
                       ->  the signing pipeline stops
                       ->  ALREADY-SIGNED artifacts remain valid and trusted

✅ Existing signatures survive, which is the important reassurance: signatures are verified against a certificate chain, not against the account that produced them. Deleting the account does not invalidate what you shipped.

⚠️ But the certificate profile goes with the account, and recreating it means going through profile creation again — and possibly re-validation. This is not a resource to destroy casually while a release is pending.

💡 To stop managing the account without deleting it, use terraform state rm. A CanNotDelete lock is the available protection, since a caller cannot use prevent_destroy.

tags = {
  owner       = "release-engineering"
  environment = "prod"
  profile     = "contoso-public-trust" # the profile created by hand (example 3)
}

✅ Real Azure resource tags — a map(string), updating in place.

💡 A profile tag is a genuinely useful convention here. The certificate profile is not in Terraform state (example 3), so nothing in your configuration records which profile this account carries — and a tag is the cheapest place to put that link where somebody debugging a release will find it.

ℹ️ An owner tag matters more than usual for a signing account. "Who can sign?" is a question with a security answer (example 4), and "who owns this account?" is the question that gets asked first.

⚠️ Tags are metadata. A profile tag does not create a profile, and none of this makes the account capable of signing on its own.

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

✅ What that proves: sku_name is Basic or Premium, and the three force-new identity fields are non-empty. This is a small resource and the gate is correspondingly small.

💡 Proved by evaluating the condition in terraform console inside the module, which does fire root-module variable validations — unlike terraform validate on a calling configuration. A sku_name of Standard — a plausible guess, and not a real tier — is rejected.

⚠️ What it cannot prove is everything that actually matters here: whether a certificate profile exists, whether the region offers the service, whether the publisher has been validated, and whether any identity is permitted to sign.

ℹ️ That gap is why this module emits requires_certificate_profile rather than relying on documentation alone (example 3). No cloud apply happens in this flow — plan-only until a human applies from CI.

provider "azurerm" {
  features {}
}

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

  name     = "rg-release-prod"
  location = "eastus" # ⚠️ Trusted Signing is not offered everywhere
}

# ── Production and test signing kept apart (example 6) ──────────────────
locals {
  accounts = {
    prod = "Premium"
    test = "Basic"
  }
}

module "signing" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-trusted-signing-account.git?ref=v1.0.0"
  for_each = local.accounts

  name                = "sign-contoso-${each.key}"
  resource_group_name = module.rg.name
  location            = module.rg.location
  sku_name            = each.value # updates in place, so this is cheap (example 5)

  tags = {
    environment = each.key
    owner       = "release-engineering"
    # The profile is NOT in Terraform state (example 3) — record the link here.
    profile = "contoso-${each.key}-profile"
  }
}

# ── The grant that actually lets a pipeline sign (example 4) ──────────────
# Each pipeline gets a role on ONLY its own account.
module "signing_rbac" {
  source   = "git::https://github.com/microsoftexpert/terraform-azurerm-role-assignments.git?ref=v1.0.0"
  for_each = local.accounts

  scope = module.signing[each.key].id # ✅ from the module, not hand-built (example 2)

  role_assignments = {
    ci_signer = {
      # ⚠️ Confirm the current role name against Microsoft's documentation.
      role_definition_name = "Trusted Signing Certificate Profile Signer"
      principal_id         = var.ci_identity_object_ids[each.key]
    }
  }
}

resource "azurerm_management_lock" "signing_prod" {
  name       = "signing-no-delete"
  scope      = module.signing["prod"].id
  lock_level = "CanNotDelete"
  notes      = "Deleting this account removes its certificate profile too"
}

output "signing_posture" {
  value = {
    uris = { for k, m in module.signing : k => m.account_uri }
    # Always true, for every account. Read it before trusting the pipeline (example 3).
    needs_profile = [for k, m in module.signing : k if m.requires_certificate_profile]
  }
}

🔒 What the composition gets right: production and test signing on separate accounts with separate role assignments, so a test pipeline cannot sign production artifacts; the scope taken from the module's id rather than a hand-written Microsoft.CodeSigning path; a profile tag recording the one dependency that lives outside Terraform; a CanNotDelete lock on production; and a note to re-check the role name rather than trusting a string indefinitely.

⚠️ What no plan will tell you: whether a certificate profile exists on either account, whether the publisher has passed identity validation, or whether the role name above is still current.

💡 needs_profile lists every account, always, by construction — which is the point. It is there for whoever assumes a clean apply means a working signing pipeline.