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 for durable secrets, identity providers issue temporary credentials, and nothing sensitive is ever committed to a repo.

---

The model

Durable secrets                         Temporary cloud access
┌────────────────────────────┐          ┌────────────────────────────┐
│ Scope-owned Azure Key Vault│          │ Entra ID / AWS IAM Identity│
│ keys, certs, passwords     │          │ Center / workload federation│
└─────────────┬──────────────┘          └─────────────┬──────────────┘
              │                                       │
              ▼                                       ▼
   KV-linked variables and                   Short-lived CLI sessions,
   runtime secret resolution                 managed identities, IAM roles

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
• Federated AWS sessions remain in the AWS CLI cache and are never copied into Key Vault
• AWS workloads use IAM roles; Azure workloads use managed identities wherever available
• 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
aws-federated-access.md	AWS IAM Identity Center, workload roles, and CLI access

---

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'

2. Add an entry to secret-inventory.md — name, purpose, who uses it, rotation schedule.

3. If a pipeline needs it, add it to the appropriate Variable Group and document it in ado-variable-groups.md.

4. 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

AWS is authenticated separately because IAM Identity Center issues temporary credentials rather than a Key Vault secret:

aws sso login --sso-session <scope-session>

See AWS federated access for first-time setup, verification, logout, and the boundary between human and workload authentication.