Secret Management
🤖 Generated with Claude Code
⚠️ Not yet reviewed
Co-Authored-By: Claude (noreply@anthropic.com)
Wo Secrets liegen, wie sie benannt sind und wer sie anlegen darf. Werte gehören nicht in dieses Repository — nur Namen und Struktur.
Inhalt​
| Dokument | Beschreibung |
|---|---|
| dieses README | Key Vaults, Naming, Authentifizierung, Berechtigungen, neues Secret anlegen |
| migration-plan.md | Migration hartcodierter Secrets aus den Repositories nach Azure Key Vault |
_migration-brainstorming.md | Arbeitsmaterial zur Migration — durch das _-Präfix nicht veröffentlicht |
diagrams/ | D2-Quellen und Renderings: keeper-migration, secret-migration-phase1, secret-migration-phase2 |
Überblick​
Secrets (Connection Strings, API Keys, Zertifikate) werden zentral in Azure Key Vaults verwaltet. Jede Umgebung hat eigene Key Vaults.
Applikationen laden Secrets beim Start ĂĽber das NuGet-Paket Tis.Hosting.Extensions.Configuration.Secrets, das auf Azure.Extensions.AspNetCore.Configuration.Secrets aufbaut.
So funktioniert es​
appsettings.jsondefiniert Key Vault Name und Prefix- Beim App-Start werden alle Secrets mit dem Prefix aus dem Vault geladen
- Secrets stehen danach als normale Configuration-Werte zur VerfĂĽgung (
IConfiguration)
{
"KeyVault": {
"VaultName": "at-tgca-tis-f-default",
"Prefix": "meineapp"
}
}
builder.Configuration.AddAzureKeyVaultFromConfig();
Secret-Naming im Vault (MUSS)​
Ein Secret MUSS dem Pattern {prefix}--{section}--{key} folgen:
| appsettings-Pfad | Secret-Name im Vault |
|---|---|
ConnectionStrings:Default | meineapp--ConnectionStrings--Default |
ExternalAuth:Oidc:ClientSecret | meineapp--ExternalAuth--Oidc--ClientSecret |
Regeln:
:MUSS zu--werden_MUSS zu-werden- Max. 127 Zeichen; der Name DARF NICHT andere Zeichen als alphanumerische und Bindestriche enthalten
Ein Secret, das anders benannt ist, wird schlicht nie geladen und fällt beim Start nicht auf — deshalb ist das Pattern verbindlich.
Authentifizierung gegenüber Key Vault​
Die Authentifizierung läuft über DefaultAzureCredential:
| Umgebung | Methode |
|---|---|
| Development | Eingeloggter User (Visual Studio / az login) — nur Lesezugriff auf den Development-Vault |
| Fachtest, Stage | Enterprise Application pro Umgebung (Umgebungsvariablen) |
| Prod | Enterprise Application pro Server (Umgebungsvariablen) |
Umgebungsvariablen auf den Servern:
AZURE_CLIENT_IDAZURE_CLIENT_SECRETAZURE_TENANT_ID
Tenant-ID: 13d188a3-27b5-44c8-a858-a4c34d245819
Die Variablen sind maschinenweit gesetzt und gelten fĂĽr alle Applikationen am Server. Wer sie liest, welche Werte gĂĽltig sind und was passiert, wenn eine fehlt: TOGETHER On-Premises Environments.
Naming Standards (MUSS)​
Ein neuer Key Vault MUSS dem folgenden Schema folgen. Die vollständigen
Naming-Konventionen stehen in Tis.Hosting.Extensions/docs/KEYVAULT_NAMING.md.
Kurzfassung:
at-tgca-{produktgruppe}-{environment}-{zweck}
Beispiel: at-tgca-tis-f-default = TIS Fachtest Standard-Secrets
Azure Resourcen & Umgebungen​
VuDev stillgelegt (August 2026): Die Umgebung existiert nicht mehr. Key Vault
at-tgca-tis-v-default, Enterprise Appvudev-appsund GruppeVudev-Applicationssind gelöscht, die Server offline. AKV-Referenzen aufat-tgca-tis-v-defaultinappsettings.vudev.jsonsind toter Code und können entfernt werden. Details und offene Aufräumarbeiten: VUDEV Decommissioning
Key Vaults​
| Umgebung | Key Vault | Subscription | Resource Group |
|---|---|---|---|
| Development | at-tgca-tis-d-default | Together-Fachtest | TIS-Secrets |
| Fachtest | at-tgca-tis-f-default | Together-Fachtest | TIS-Secrets |
| Stage | at-tgca-tis-s-default | Together-Fachtest | TIS-Secrets |
| Prod | at-tgca-tis-p-default | Together-Prod | TIS-Secrets |
Enterprise Applications & Berechtigungen​
Gruppen mit Key Vault Berechtigungen (Key Vault Certificates User, Key Vault Secrets User, Key Vault Reader):
| Umgebung | Enterprise App | Gruppe | Client ID |
|---|---|---|---|
| Fachtest | fachtest-apps | Fachtest-Applications | 7b099cbc-8d97-456e-9297-c7c5723b3a24 |
| Stage | stage-apps | Stage-Applications | c64135ff-c944-47b8-a9b6-ff9a6deb89e3 |
| Prod | (pro Server) | Prod-Applications | (siehe Server-Status) |
Server-Status​
Status = die AZURE_*-Umgebungsvariablen sind auf dem Server gesetzt, sodass sich die
Applikationen über DefaultAzureCredential am Key Vault der Umgebung anmelden können. Ein ❌
sagt nichts darüber aus, ob die Umgebung selbst einen Key Vault hat — den hat jede, siehe
oben.
Fachtest (Client ID: 7b099cbc-...3a24)
| Server | Status |
|---|---|
| TISWEB001 | âś… |
| TISWEB002 | ❌ |
| TISAPP01 | âś… |
| TISAPP02 | âś… |
| TISAPP03 | âś… |
| TISDB003 | âś… |
| TISDB004 | âś… |
Stage (Client ID: c64135ff-...89e3)
| Server | Status |
|---|---|
| TISWEB001 | âś… |
| TISWEB002 | âś… |
| TISAPP01 | âś… |
| TISAPP002 | âś… |
| TISAPP003 | âś… |
| TISDB001 | âś… |
| TISDB002 | âś… |
Prod (je eine Enterprise App pro Server)
| Server | Client ID | Status |
|---|---|---|
| TISWEB01 | 492a80a5-3833-4865-bd63-ab29ea5518df | âś… |
| TISWEB02 | TBD | ❌ |
| TISAPP01 | ab476948-f483-4c29-9880-0361a6d1f338 | âś… |
| TISAPP02 | f534c19b-dc96-4c07-a92c-91368b820342 | âś… |
| TISAPP03 | b31f1912-ec54-4877-9b74-7cbfd23778dc | âś… |
| TISDB01 | 62de3629-d55f-41da-b5e4-c9f6d967cd2b | âś… |
| TISDB02 | da762a94-2fcf-4e67-8d47-c7bce2d46393 | âś… |
Neues Secret hinzufügen​
Wer macht das: DevOps-Team — Entwickler haben keinen Schreibzugriff auf die Key Vaults. Entwickler fordern ein Secret beim DevOps-Team an, siehe Development → Secrets in a Service.
Mit tis-secrets Tool (empfohlen)​
Das CLI-Tool tis-secrets automatisiert die Migration von Secrets aus appsettings.json nach Azure Key Vault.
Installation:
dotnet tool install --global Tis.Tools.Secrets --add-source https://pkgs.dev.azure.com/togethercca/_packaging/tis-cca/nuget/v3/index.json
Workflow:
-
Dry-run ausfĂĽhren um Secrets zu erkennen:
tis-secrets migrate -v at-tgca-tis-f-default -p meineapp -e fachtest --dry-run -
Migration durchfĂĽhren (ersetzt Secrets mit AKV-Referenzen):
tis-secrets migrate -v at-tgca-tis-f-default -p meineapp -e fachtest -
FĂĽr jede Umgebung wiederholen (development, fachtest, stage, prod)
Optionen:
| Flag | Beschreibung |
|---|---|
--no-replace | Nur zu AKV hochladen, Config-Files nicht ändern |
--replace-base | Auch base appsettings.json ersetzen (nach allen Umgebungen) |
--dry-run | Zeigt was passieren würde ohne Änderungen |
FĂĽr komplexe Projekte mit mehreren Config-Files: .secret-migration.json im Projektroot anlegen.
Manuell über Azure Portal​
- Azure Portal > Key Vault > Secrets > Generate/Import
- Secret-Name MUSS der Naming-Konvention folgen:
{prefix}--{section}--{key} - In appsettings.json AKV-Referenz eintragen:
"ConnectionStrings": {
"Default": "@Microsoft.KeyVault(VaultName=at-tgca-tis-f-default;SecretName=meineapp--ConnectionStrings--Default)"
}
Für Entwickler​
Wie eine Applikation ein Secret liest, wie die Namen zustande kommen, was für lokale Entwicklung gilt und wie ein neues Secret angefordert wird, steht auf der Entwicklerseite: Development → Secrets in a Service.
Kurzfassung: Entwickler haben Lesezugriff auf den Development-Vault und sonst keine Berechtigungen. Neue Secrets legt das DevOps-Team an.