Zum Hauptinhalt springen

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​

DokumentBeschreibung
dieses READMEKey Vaults, Naming, Authentifizierung, Berechtigungen, neues Secret anlegen
migration-plan.mdMigration hartcodierter Secrets aus den Repositories nach Azure Key Vault
_migration-brainstorming.mdArbeitsmaterial 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​

  1. appsettings.json definiert Key Vault Name und Prefix
  2. Beim App-Start werden alle Secrets mit dem Prefix aus dem Vault geladen
  3. 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-PfadSecret-Name im Vault
ConnectionStrings:Defaultmeineapp--ConnectionStrings--Default
ExternalAuth:Oidc:ClientSecretmeineapp--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:

UmgebungMethode
DevelopmentEingeloggter User (Visual Studio / az login) — nur Lesezugriff auf den Development-Vault
Fachtest, StageEnterprise Application pro Umgebung (Umgebungsvariablen)
ProdEnterprise Application pro Server (Umgebungsvariablen)

Umgebungsvariablen auf den Servern:

  • AZURE_CLIENT_ID
  • AZURE_CLIENT_SECRET
  • AZURE_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 App vudev-apps und Gruppe Vudev-Applications sind gelöscht, die Server offline. AKV-Referenzen auf at-tgca-tis-v-default in appsettings.vudev.json sind toter Code und können entfernt werden. Details und offene Aufräumarbeiten: VUDEV Decommissioning

Key Vaults​

UmgebungKey VaultSubscriptionResource Group
Developmentat-tgca-tis-d-defaultTogether-FachtestTIS-Secrets
Fachtestat-tgca-tis-f-defaultTogether-FachtestTIS-Secrets
Stageat-tgca-tis-s-defaultTogether-FachtestTIS-Secrets
Prodat-tgca-tis-p-defaultTogether-ProdTIS-Secrets

Enterprise Applications & Berechtigungen​

Gruppen mit Key Vault Berechtigungen (Key Vault Certificates User, Key Vault Secrets User, Key Vault Reader):

UmgebungEnterprise AppGruppeClient ID
Fachtestfachtest-appsFachtest-Applications7b099cbc-8d97-456e-9297-c7c5723b3a24
Stagestage-appsStage-Applicationsc64135ff-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)

ServerStatus
TISWEB001âś…
TISWEB002❌
TISAPP01âś…
TISAPP02âś…
TISAPP03âś…
TISDB003âś…
TISDB004âś…

Stage (Client ID: c64135ff-...89e3)

ServerStatus
TISWEB001âś…
TISWEB002âś…
TISAPP01âś…
TISAPP002âś…
TISAPP003âś…
TISDB001âś…
TISDB002âś…

Prod (je eine Enterprise App pro Server)

ServerClient IDStatus
TISWEB01492a80a5-3833-4865-bd63-ab29ea5518dfâś…
TISWEB02TBD❌
TISAPP01ab476948-f483-4c29-9880-0361a6d1f338âś…
TISAPP02f534c19b-dc96-4c07-a92c-91368b820342âś…
TISAPP03b31f1912-ec54-4877-9b74-7cbfd23778dcâś…
TISDB0162de3629-d55f-41da-b5e4-c9f6d967cd2bâś…
TISDB02da762a94-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:

  1. Dry-run ausfĂĽhren um Secrets zu erkennen:

    tis-secrets migrate -v at-tgca-tis-f-default -p meineapp -e fachtest --dry-run
  2. Migration durchfĂĽhren (ersetzt Secrets mit AKV-Referenzen):

    tis-secrets migrate -v at-tgca-tis-f-default -p meineapp -e fachtest
  3. FĂĽr jede Umgebung wiederholen (development, fachtest, stage, prod)

Optionen:

FlagBeschreibung
--no-replaceNur zu AKV hochladen, Config-Files nicht ändern
--replace-baseAuch base appsettings.json ersetzen (nach allen Umgebungen)
--dry-runZeigt was passieren würde ohne Änderungen

FĂĽr komplexe Projekte mit mehreren Config-Files: .secret-migration.json im Projektroot anlegen.

Manuell über Azure Portal​

  1. Azure Portal > Key Vault > Secrets > Generate/Import
  2. Secret-Name MUSS der Naming-Konvention folgen: {prefix}--{section}--{key}
  3. 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.