Client Secrets ohne Downtime rotieren: Ablauf für Entra App Registrations

Ein Client Secret anzulegen dauert im Portal zwei Minuten. Die Ausfälle entstehen nicht beim Anlegen, sondern beim Umstellen: Irgendwo liegt noch der alte Wert, den niemand auf der Liste hatte. Dieser Beitrag beschreibt einen Ablauf, der ohne Unterbrechung funktioniert, im Portal, mit Microsoft Graph PowerShell und per Graph REST.

Warum die Rotation Integrationen bricht

Drei Eigenschaften von Client Secrets machen den Tausch heikel:

Der Wert wird genau einmal angezeigt. Nach dem Verlassen der Seite zeigt Entra nur noch die Secret ID und die ersten drei Zeichen. Wer den Wert nicht kopiert hat, legt ein neues Secret an.
Verbraucher cachen den Wert. Er steckt in App-Service-Einstellungen, in Key Vault, in Pipeline-Variablen, in einer Konfigurationsdatei auf einem On-Prem-Server, in einem Power-Automate-Connector. Jede dieser Stellen muss einzeln umgestellt werden.
Bereits ausgestellte Tokens bleiben gültig. Ein Access Token lebt standardmäßig 60 bis 90 Minuten. Ein gelöschtes Secret unterbricht laufende Sitzungen also nicht sofort. Der Fehler kommt erst beim nächsten Token-Request, oft eine Stunde später und scheinbar ohne Zusammenhang.

Der dritte Punkt ist der tückischste. Wer das alte Secret löscht, kurz beobachtet und „läuft noch“ notiert, hat nichts geprüft.

Das Überlappungsprinzip

Eine App Registration kann mehrere Client Secrets und mehrere Zertifikate gleichzeitig halten. Jedes davon ist für sich gültig. Daraus folgt die einzige Reihenfolge, die ohne Downtime funktioniert:

Neues Secret anlegen, altes behalten.
Alle Verbraucher auf das neue Secret umstellen.
Prüfen, dass sich niemand mehr mit dem alten authentifiziert.
Altes Secret entfernen.

Zwischen Schritt 2 und 4 liegt bewusst Zeit: mindestens ein Tag, bei wöchentlichen Batch-Jobs eine Woche.

Das Runbook

Ablaufdatum und Owner prüfen. Welches Secret läuft ab, wer ist an der App als Owner eingetragen, gibt es eine Doku zur Anwendung?
Verbraucher inventarisieren. Liste aller Stellen, die den Wert nutzen (Suchstellen weiter unten).
Neues Secret anlegen mit Beschreibung und passender Laufzeit. Den Wert sofort in den Passwort-Manager oder in Key Vault legen.
Verbraucher umstellen, einen nach dem anderen. Dienste neu starten, wo die Konfiguration nur beim Start gelesen wird.
Funktion prüfen: erfolgreiche Anmeldungen der App in den Sign-in-Logs oder ein Test-Token mit dem neuen Wert.
Wartefrist einhalten und die Sign-in-Logs auf Anmeldungen mit dem alten Secret beobachten.
Altes Secret entfernen, identifiziert über seine Key ID.
Dokumentieren: Datum, Key ID, nächstes Ablaufdatum, wer rotiert hat.

Im Portal

Im Microsoft Entra Admin Center: App registrations, App auswählen, Certificates & secrets, Tab Client secrets, New client secret. Der Dialog fragt zwei Dinge ab:

Description: siehe Namenskonvention unten.
Expires: 180 Tage (Vorschlag), 365 Tage, 730 Tage oder ein eigenes Datum. Mehr als 24 Monate sind nicht möglich, Microsoft empfiehlt unter 12 Monaten.

Nach Add zeigt die Tabelle Value und Secret ID. Kopiere Value. Die Secret ID ist die Key ID, sie bleibt sichtbar, der Wert nicht. Zum späteren Entfernen dient das Papierkorb-Symbol in der Zeile des alten Secrets.

Mit Microsoft Graph PowerShell

Benötigt wird Application.ReadWrite.All oder, für Apps mit eigener Ownership, Application.ReadWrite.OwnedBy. $appObjectId ist die Object ID der App Registration, nicht die Application (client) ID.

Neues Secret mit zwölf Monaten Laufzeit:

Connect-MgGraph -Scopes "Application.ReadWrite.All"

$new = Add-MgApplicationPassword -ApplicationId $appObjectId -BodyParameter @{
  passwordCredential = @{
    displayName = "backup-sync / it-ops / 2026-09-28"
    endDateTime = (Get-Date).AddMonths(12)
  }
}
$new.SecretText   # nur jetzt lesbar
$new.KeyId        # für die Doku

Vorhandene Secrets auflisten und das alte anhand seiner Key ID entfernen:

(Get-MgApplication -ApplicationId $appObjectId -Property PasswordCredentials).PasswordCredentials |
  Select-Object DisplayName, KeyId, StartDateTime, EndDateTime

Remove-MgApplicationPassword -ApplicationId $appObjectId -KeyId "f0b0b335-1d71-4883-8f98-567911bfdca6"

Mit Microsoft Graph REST

Dieselben zwei Aktionen als HTTP-Aufrufe auf der Ressource application. Ein PATCH auf passwordCredentials wird nicht unterstützt, es gibt nur die Aktionen addPassword und removePassword.

POST https://graph.microsoft.com/v1.0/applications/{object-id}/addPassword
Content-Type: application/json

{
  "passwordCredential": {
    "displayName": "backup-sync / it-ops / 2026-09-28",
    "endDateTime": "2027-09-28T00:00:00Z"
  }
}

Die Antwort enthält secretText (einmalig), keyId und hint. Ohne endDateTime setzt Graph zwei Jahre ab Start.

POST https://graph.microsoft.com/v1.0/applications/{object-id}/removePassword
Content-Type: application/json

{ "keyId": "f0b0b335-1d71-4883-8f98-567911bfdca6" }

Statt der Object ID akzeptiert Graph auch die Adressierung über applications(appId='{client-id}').

Alle Verbraucher eines Secrets finden

An diesem Schritt scheitern Rotationen. Suchstellen:

Key Vault: Secrets, deren Name oder Tag die App referenziert. Ist Key Vault die Verteilstelle, reicht dort eine neue Secret-Version.
App Service und Functions: Anwendungseinstellungen, Connection Strings, Key-Vault-Referenzen.
Pipelines: Variablengruppen in Azure DevOps, Secrets in GitHub Actions, Service Connections.
On-Prem: Konfigurationsdateien, Windows-Dienste, geplante Aufgaben, Drittanbieter-Tools mit eigener Credential-Ablage.
Dokumentation: Übergabeprotokolle, Wiki, das Ticket, in dem die App eingerichtet wurde.

Die verlässlichste Quelle ist Entra selbst. Unter Entra ID, Monitoring & health, Sign-in logs, Tab Service principal sign-ins stehen alle Anmeldungen der App mit IP-Adresse und Zielressource. Jede IP, die nach der Umstellung weiter anmeldet, obwohl dort niemand etwas geändert hat, ist ein vergessener Verbraucher. Der Bericht Application credential activity unter Usage & insights zeigt zusätzlich je Credential das Datum der letzten Verwendung. Er benötigt Entra ID P1 oder P2.

Namenskonvention für die Beschreibung

Die Beschreibung ist das einzige Freitextfeld am Secret. Sie sollte drei Fragen beantworten: wofür, wer, seit wann. Bewährt hat sich das Muster verbraucher / team / yyyy-mm-dd, also etwa backup-sync / it-ops / 2026-09-28. Mit dem Datum in der Beschreibung ist bei zwei parallelen Secrets sofort klar, welches das neue ist. Die Owner an der App Registration bleiben trotzdem gepflegt, denn eine Beschreibung ersetzt keinen Ansprechpartner.

Umstellung prüfen

Zwei Wege, je nach Zugriff:

Sign-in-Logs: Nach dem Neustart des Verbrauchers erscheint eine erfolgreiche Anmeldung der App. In den Details eines Eintrags steht der Client credential type. Fehlt der Eintrag, liest der Verbraucher noch den alten Wert oder gar keinen.
Test-Token: ein Client-Credentials-Request gegen den Token-Endpunkt mit dem neuen Wert. Antwortet Entra mit einem access_token, ist das Secret aktiv. Antwortet es mit AADSTS7000215 (invalid client secret), wurde meist die Secret ID statt des Werts kopiert.

POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={client-id}
&client_secret={neuer-wert}
&scope=https://graph.microsoft.com/.default
&grant_type=client_credentials

Rotation automatisieren

Wer mehr als eine Handvoll Apps betreibt, automatisiert die Schritte 3 bis 7:

Azure Automation Runbook oder Azure Function mit Zeitplan: liest per Graph alle Secrets, legt bei unter 30 Resttagen ein neues an und schreibt den Wert direkt in Key Vault.
Key Vault als Verteilstelle: Verbraucher lesen das Secret per Key-Vault-Referenz oder SDK statt aus eigener Konfiguration. Dann ist die Umstellung eine neue Secret-Version, kein Deployment.
Event Grid: Key Vault sendet Microsoft.KeyVault.SecretNearExpiry 30 Tage vor Ablauf und SecretExpired danach, siehe das Key-Vault-Event-Schema. Eine Function als Handler stößt die Rotation an. Voraussetzung: Das Key-Vault-Secret trägt dasselbe Ablaufdatum wie das Entra-Secret.

Die Automation braucht selbst ein Credential mit Application.ReadWrite.OwnedBy. Eine Managed Identity für die Function löst das Henne-Ei-Problem.

Zertifikate: gleiches Prinzip, anderer Selektor

Für Zertifikate gilt derselbe Ablauf. Hochgeladen wird unter Certificates & secrets, Tab Certificates, Upload certificate, als .cer, .pem oder .crt und nur der öffentliche Teil. Per Graph heißen die Aktionen addKey und removeKey; addKey verlangt einen Nachweis über ein bereits vorhandenes gültiges Zertifikat, sonst bleibt nur das Portal oder ein Update der keyCredentials. Der Unterschied liegt beim Verbraucher: Er wählt das Zertifikat meist über den Thumbprint oder den Subject-Namen aus dem Zertifikatsspeicher. Beim Wechsel muss also der Thumbprint in der Konfiguration mitwandern, oder der Client wählt nach Subject und nimmt automatisch das neueste. Der private Schlüssel gehört auf den Verbraucher oder in Key Vault, nie in Entra.

Typische Fehler

Fehler	Folge	Vermeidung
Altes Secret zuerst gelöscht	Ausfall etwa eine Stunde später, wenn die laufenden Tokens ablaufen	Immer überlappend: anlegen, umstellen, prüfen, löschen
Secret ID statt Value kopiert	`AADSTS7000215`, das neue Secret wirkt „falsch“	Value sofort nach Add kopieren, Secret ID nur für die Doku
Nur in einem von vielen Tenants rotiert	Dieselbe Integration fällt bei den anderen Kunden aus	Rotation je Tenant abhaken, Liste führen
Verbraucher ohne Neustart	Alte Konfiguration bleibt im Speicher	Dienst neu starten und Sign-in prüfen

Rotation beginnt mit Monitoring

Der Ablauf oben braucht Vorlauf: Inventar, Umstellung, Wartefrist. Wer das Ablaufdatum erst am Tag des Ausfalls erfährt, kann nicht überlappend rotieren. Entra selbst versendet keine Warnung, wie im Beitrag Entra App Registration Secrets laufen ab beschrieben. Eine Erinnerung 30 Tage vor Ablauf ist das Minimum, 90 Tage bei Apps mit vielen Verbrauchern.

Wie SecretExpiry hilft

SecretExpiry liest mit der Berechtigung Application.Read.All die Ablaufdaten aller Client Secrets und Zertifikate über alle verbundenen Tenants. Der Dienst rotiert selbst nichts, er meldet. Benachrichtigungen kommen per E-Mail je Ereignis oder als Wochenübersicht, per Webhook in einen Microsoft-Teams- oder Slack-Kanal oder als Kalender-Abo (ICS). Jeder Tenant kann eine eigene Empfängeradresse haben, und bereits eingeplante Rotationen lassen sich per Snooze stummschalten. Das Dashboard zeigt die dringenden Fälle zuerst. 14 Tage kostenlos testen, danach ab 10 € pro Tenant und Monat, Details in der Dokumentation.