Skip to content

Service principals

Registry of all Azure service principals (SPNs) used across HCS projects. App IDs are documented here. Client secrets are stored in kv-hcs-vault-01 only — never here.

How to register a new SPN

  1. Create the SPN in Azure: 
    az ad sp create-for-rbac `
    --name spn-hcs-<purpose>-<env> `
    --role <role> `
    --scopes /subscriptions/be069ae1-fc96-4a07-9f8e-5994d83a817d
  2. Store the generated client secret in kv-hcs-vault-01: 
    az keyvault secret set `
    --vault-name kv-hcs-vault-01 `
    --name spn-hcs-<purpose>-<env>-secret `
    --value '<client-secret>'
    Then immediately clear the secret from your terminal history.
  3. Add the client secret to secret-inventory.md.
  4. Add the SPN to the registry table below — App ID and all metadata, but not the secret.
  5. Assign the minimum required role(s) — principle of least privilege.
  6. Commit: docs(identity): register SPN spn-hcs-<purpose>-<env>

Naming convention: spn-hcs-<purpose>-<env> — e.g., spn-hcs-ado-pipelines-prd, spn-hcs-terraform-dev

Registry

Display name App ID Purpose Used by Role assignments Expiry Notes
(no SPNs registered yet — add the first one following the instructions above)

SPN client secret rotation

When a client secret is expiring or has been compromised:

  1. Create a new client secret in the Azure portal or via az ad sp credential reset
  2. Update the value in kv-hcs-vault-01 (same secret name — KV versions automatically)
  3. Update the Expiry date in the registry table above
  4. Pipelines that pull the secret from a Variable Group pick up the new value automatically
  5. Commit: docs(identity): rotate secret for <SPN display name>

Do not delete the old secret until you have confirmed the new one is working in all consuming pipelines.

Notes

  • All SPNs follow the principle of least privilege. If a pipeline only needs to read resources, the SPN gets Reader — not Contributor.
  • SPNs are never used for interactive login. Managed identities are preferred for Azure-hosted workloads.
  • Federation (workload identity) is preferred over client secrets for GitHub Actions pipelines.