Skip to content

Identity and secrets — overview

All credentials, identities, and access management across every HCS project follow a single model: Key Vault is the source of truth, and nothing sensitive is ever committed to any repo.

The model

┌─────────────────────────────────────────────────────────────┐
│                        kv-hcs-vault-01                      │
│                   (single source of truth)                   │
└───────────┬─────────────────────────┬───────────────────────┘
            │                         │
            ▼                         ▼
   ADO Variable Groups         Local session
   (KV-linked, pipeline        (pulled via CLI
   access only)                scripts/Load-HCSEnvironment.ps1)
            │                         │
            ▼                         ▼
   ADO Pipelines               Claude Code, az CLI,
   (never see raw values)      gh CLI, local tools

This means:

  • Pipelines never store secrets — they pull from Variable Groups that are linked to Key Vault
  • Local development never reads from .env files — secrets are pulled from Key Vault at session start
  • No secret value ever appears in any file committed to any repo, ever

What is documented here

This section of the platform repo documents the existence and purpose of identities and secrets, not their values. Every entry in these registries answers:

  • What is this thing called?
  • What does it do?
  • Who or what uses it?
  • When does it expire?
  • When was it last rotated?

Registry files

File What it covers
secret-inventory.md All secrets in kv-hcs-vault-01
service-principals.md All Azure service principals
managed-identities.md All managed identities (user-assigned and system-assigned)
github-pats.md All GitHub personal access tokens
ado-variable-groups.md All ADO Variable Groups and their KV mappings

Key Vault

  • Vault name: kv-hcs-vault-01
  • Subscription: be069ae1-fc96-4a07-9f8e-5994d83a817d
  • Authenticated as: kris@hybridsolutions.cloud

All secrets, keys, and certificates used by any HCS project are stored here. Access is controlled by Azure RBAC. Any identity that needs a secret must have at least Key Vault Secrets User on this vault or on the specific secret.

Adding a new secret

  1. Create the secret in kv-hcs-vault-01 via the Azure portal or:
az keyvault secret set `
    --vault-name kv-hcs-vault-01 `
    --name my-new-secret `
    --value 'the-value'
  1. Add an entry to secret-inventory.md — name, purpose, who uses it, rotation schedule.
  2. If a pipeline needs it, add it to the appropriate Variable Group and document it in ado-variable-groups.md.
  3. If a local script needs it, add it to scripts/Load-HCSEnvironment.ps1 and document the env var name.

Never document the actual value anywhere.

Rotating a secret

  1. Generate the new value (new PAT, new client secret, etc.)
  2. Update the secret in kv-hcs-vault-01
  3. Update the Last Rotated date in the relevant registry file here
  4. If the secret is used in gh auth or similar tool auth, re-run the auth setup
  5. Pipelines that reference via Variable Groups pick up the new value automatically — no pipeline changes needed

Local session setup

Before starting a Claude Code session or any local development that needs credentials:

. scripts/Load-HCSEnvironment.ps1

This script: - Verifies you are logged in to Azure (az account show) - Pulls each registered secret from kv-hcs-vault-01 by name - Sets the corresponding environment variable in the current PowerShell session only - Prints which variables were loaded (names only — values are never logged) - Is safe to run multiple times in the same session