Konfigurieren Sie die Tokenentschlüsselung in Microsoft. Identity.Web

In diesem Artikel wird erläutert, wie Token-Entschlüsselungszertifikate in Microsoft.Identity.Web konfiguriert werden, damit Ihre Anwendung verschlüsselte Token von der Microsoft Identity-Plattform entschlüsseln kann.

Standardmäßig gibt der Microsoft Identity Platform Token (ID-Token, SAML-Token) als signierte, aber unverschlüsselte JWTs aus. Jeder Zwischenhändler, der ein Token abfängt, kann dessen Claims lesen. Für Anwendungen, die vertrauliche Ansprüche verarbeiten oder in strengen Complianceumgebungen arbeiten, unterstützt die Microsoft Identity Platform die verschlüsselung token. Wenn diese Option aktiviert ist, verschlüsselt die Identitätsplattform die Tokennutzlast mithilfe eines öffentlichen Schlüssels, der bei Ihrer Anwendung registriert ist. Nur Ihre Anwendung , die den entsprechenden privaten Schlüssel enthält, kann das Token entschlüsseln und lesen.

Funktionsweise der Tokenverschlüsselung

1. Sie generieren ein Zertifikat mit einem öffentlichen/privaten Schlüsselpaar.
2. Sie laden den public-Schlüssel (die Datei .cer) in Ihre App-Registrierung in Microsoft Entra ID hoch.
3. Wenn der Microsoft Identity Platform ein Token für Ihre Anwendung ausgibt, verschlüsselt es das Token mit Ihrem öffentlichen Schlüssel.
4. Ihre Anwendung verwendet den privaten Schlüssel , um das Token vor der Verarbeitung von Ansprüchen zu entschlüsseln.

Die Verschlüsselung verwendet ein zweistufiges Schema: Die Tokennutzlast wird mit einem symmetrischen Inhaltsverschlüsselungsschlüssel verschlüsselt, der mit Ihrem öffentlichen Schlüssel umschlossen (verschlüsselt) wird. Microsoft Entra unterstützt RSA-OAEP- und RSA-OAEP-256-Schlüsselumschlagalgorithmen.

Bestimmen, wann die Tokenentschlüsselung konfiguriert werden soll

Konfigurieren Sie die Tokenentschlüsselung, wenn Ihre Anwendung eine der folgenden Bedingungen erfüllt:

• Empfängt verschlüsselte SAML-Token – Unternehmensanwendungen, die SAML-basiertes Single Sign-On verwenden und aus Compliance- oder behördlichen Gründen verschlüsselte SAML-Assertionen erfordern.
• Empfängt verschlüsselte ID-Token – Webanwendungen, die sich für die ID-Tokenverschlüsselung entscheiden, um vertrauliche Ansprüche (Gruppenmitgliedschaften, benutzerdefinierte Ansprüche) vor der Übertragung zu schützen.
• Arbeitet in Hochsicherheitsumgebungen – Anwendungen in Regierungs-, Finanz- oder Gesundheitsszenarien, in denen die Token-Vertraulichkeit durch eine Richtlinie vorgeschrieben wird.

Erfüllen der Voraussetzungen

Bevor Sie die Tokenentschlüsselung konfigurieren, überprüfen Sie die folgenden Anforderungen:

• An X.509-Zertifikat mit einem privaten Schlüssel – Sie benötigen ein Zertifikat im Format .pfx (PKCS#12) oder an einem Speicherort, auf den Ihre Anwendung zugreifen kann (Azure Key Vault, Zertifikatspeicher oder Dateisystem). Der private Schlüssel ist zum Entschlüsseln von Token erforderlich.
• App-Registrierung für die Tokenverschlüsselung konfiguriert – Laden Sie den öffentlichen Schlüssel des Zertifikats in ihre App-Registrierung in Microsoft Entra ID hoch. Weitere Informationen finden Sie unter Registrieren des Entschlüsselungszertifikats weiter unten in diesem Artikel.
• Microsoft.Identity.Web 2.1.0 oder höher – Die Konfigurationseigenschaft TokenDecryptionCredentials ist in Microsoft.Identity.Web ab Version 2.1.0 verfügbar und höher.

Konfigurieren der Tokenentschlüsselung in appsettings.json

Microsoft.Identity.Web verwendet das TokenDecryptionCredentials array im Konfigurationsabschnitt AzureAd. Dieses Array folgt demselben Beschreibungsformat für Anmeldeinformationen wie ClientCredentials, sodass Sie Entschlüsselungszertifikate aus Azure Key Vault, dem Zertifikatspeicher, einem Dateipfad oder einer base64-codierten Zeichenfolge laden können.

Einrichten einer grundlegenden Konfiguration

Das folgende Beispiel zeigt die Mindestkonfiguration zum Laden eines Entschlüsselungszertifikats aus Azure Key Vault:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "CallbackPath": "/signin-oidc",

    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "MyCertificate"
      }
    ]
  }
}

Es ist kein zusätzlicher Code erforderlich. Wenn Microsoft. Identity.Web erkennt die konfiguration TokenDecryptionCredentials, lädt das angegebene Zertifikat automatisch und registriert es beim OpenID Connect-Authentifizierungshandler für die Tokenentschlüsselung.

Wählen Sie eine Anmeldedatenquelle aus

Das TokenDecryptionCredentials Array unterstützt dieselben Quelltypen wie ClientCredentials. In der folgenden Tabelle sind die einzelnen Optionen zusammengefasst:

Key Vault (empfohlen für den Produktionseinsatz)

Die folgende Konfiguration lädt ein Entschlüsselungszertifikat aus Azure Key Vault:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert"
    }
  ]
}

Die verwaltete Identität oder der Dienstprinzipal Ihrer Anwendung muss über Get und List Berechtigungen für die Key Vault Zertifikate verfügen.

Zertifikatspeicher (Windows)

Die folgende Konfiguration lädt ein Zertifikat aus dem Windows Zertifikatspeicher per Fingerabdruck:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "StoreWithThumbprint",
      "CertificateStorePath": "CurrentUser/My",
      "CertificateThumbprint": "A1B2C3D4E5F6..."
    }
  ]
}

Dateipfad

Die folgende Konfiguration lädt ein Zertifikat aus einer Datei auf dem .pfx Datenträger:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Path",
      "CertificateDiskPath": "/var/ssl/private/decrypt-cert.pfx",
      "CertificatePassword": "your-certificate-password"
    }
  ]
}

Base64-codiert

Die folgende Konfiguration lädt ein Zertifikat aus einer Base64-codierten Zeichenfolge:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Base64Encoded",
      "Base64EncodedValue": "MIIJ..."
    }
  ]
}

Diese Option ist nützlich, wenn Sie das Zertifikat über eine Umgebungsvariable oder einen geheimen CI/CD-Pipelineschlüssel einfügen.

Konfigurieren mehrerer Entschlüsselungszertifikate

Sie können mehrere Zertifikate im TokenDecryptionCredentials Array angeben. Microsoft. Identity.Web versucht jedes Zertifikat in der Reihenfolge, bis ein Zertifikat erfolgreich entschlüsselt wird. Diese Funktion ist für den Zertifikatwechsel unerlässlich (siehe Zertifikatwechsel).

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-New"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-Old"
    }
  ]
}

Registrieren des Entschlüsselungszertifikats in Microsoft Entra ID

Damit die Microsoft Identity Platform Token für Ihre Anwendung verschlüsseln kann, müssen Sie den öffentlichen Schlüssel in Ihre App-Registrierung hochladen.

1. Melden Sie sich beim Microsoft Entra Admin Center an.
2. Navigieren Sie zu Identity>Applications>App-Registrierungen, und wählen Sie Ihre Anwendung aus.
3. Wählen Sie Zertifikate und Geheimnisse>Zertifikate>Zertifikat hochladen aus.
4. Laden Sie die .cer Datei (nur öffentlicher Schlüssel) Ihres Entschlüsselungszertifikats hoch.
5. Notieren Sie sich nach dem Hochladen den Fingerabdruckwert – sie muss mit dem zertifikat übereinstimmen, das Ihre Anwendung verwendet.

Aktivieren der Tokenverschlüsselung für die Anwendung

Nach dem Hochladen des Zertifikats müssen Sie Ihre Anwendung so konfigurieren, dass verschlüsselte Token empfangen werden. Diese Konfiguration ist derzeit über microsoft Graph-API oder PowerShell verfügbar:

Using Microsoft Graph PowerShell:

# Get the key credential ID of the uploaded certificate
$app = Get-MgApplication -Filter "appId eq 'your-client-id'"
$keyId = ($app.KeyCredentials | Where-Object { $_.DisplayName -eq "CN=TokenDecryptionCert" }).KeyId

# Set the token encryption key ID
Update-MgApplication -ApplicationId $app.Id -BodyParameter @{
    "tokenEncryptionKeyId" = $keyId
}

Entschlüsselungszertifikate drehen

Die Zertifikatrotation für die Tokenentschlüsselung erfordert einen sorgfältigen, phasenweisen Ansatz, um Ausfallzeiten zu vermeiden:

Schritte zur Rotation

1. Generieren Sie ein neues Zertifikat – Erstellen Sie ein neues X.509-Zertifikat mit einem privaten Schlüssel.
2. Fügen Sie das neue Zertifikat zur Anwendungskonfiguration hinzu – Fügen Sie das neue Zertifikat neben dem vorhandenen Zertifikat dem Array hinzu TokenDecryptionCredentials . Platzieren Sie das neue Zertifikat zuerst im Array.
3. Laden Sie den neuen öffentlichen Schlüssel hoch – Laden Sie die Datei .cer des neuen Zertifikats in Ihre App-Registrierung in Microsoft Entra hoch.
4. Stellen Sie Ihre Anwendung bereit – Stellen Sie die aktualisierte Konfiguration bereit, damit Ihre Anwendung Token mit beiden Zertifikaten entschlüsseln kann.
5. Wechseln Sie den aktiven Verschlüsselungsschlüssel – Aktualisieren Sie das tokenEncryptionKeyId Anwendungsobjekt so, dass es auf das neue Zertifikat keyIdverweist.
6. Überprüfen – Vergewissern Sie sich, dass Ihre Anwendung Token, die mit dem neuen Zertifikat verschlüsselt wurden, erfolgreich entschlüsselt.
7. Entfernen Sie das alte Zertifikat – nach einer Nachfrist (mindestens 24 Stunden, um zwischengespeicherte Token ablaufen zu lassen), entfernen Sie das alte Zertifikat sowohl aus Der App-Registrierung als auch aus der Anwendungskonfiguration.

Konfiguration während der Drehung

Während des Rotationsfensters sollte Ihr TokenDecryptionCredentials beide Zertifikate enthalten:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2026"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2025"
    }
  ]
}

Problembehandlung der Tokenentschlüsselung

Verwenden Sie die folgenden Anleitungen, um häufige Probleme bei der Tokenentschlüsselung zu diagnostizieren und zu beheben.

Fehler bei der Tokenentschlüsselung

Symptom: Ihre Anwendung wirft einen Fehler oder gibt einen 401/500-Fehler zurück, wenn Token verarbeitet werden.

Häufige Ursachen:

Fehlender privater Schlüssel

Symptom:CryptographicException: The certificate key is not accessible oder InvalidOperationException: Certificate does not have a private key.

Ursachen und Lösungen:

• Zertifikat ohne privaten Schlüssel exportiert – Exportieren Sie das Zertifikat im .pfx Format erneut, und stellen Sie sicher, dass Sie den privaten Schlüssel während des Exports einschließen.
• Key Vault Zugriffsrichtlinie – Bei Verwendung von Azure Key Vault Stellen Sie sicher, dass die Identität Ihrer Anwendung über die Berechtigung Get für beide Certificates und Secrets verfügt. Der private Schlüssel wird in Key Vault als geheimer Schlüssel gespeichert.
• Certificate Store-Berechtigungen – Überprüfen Sie unter Windows, ob die Identität oder das Dienstkonto des Anwendungspools Lesezugriff auf den privaten Schlüssel hat. Verwenden Sie die Option "Private Schlüssel verwalten " im MMC-Snap-In für den Zertifikatspeicher.

Algorithmuskonflikt

Symptom:SecurityTokenDecryptionFailedException mit einer Meldung, die einen nicht unterstützten Algorithmus angibt.

Ursachen und Lösungen:

• Nicht unterstützter Schlüsselt-Typ — Microsoft Entra unterstützt RSA-Zertifikate für die Tokenverschlüsselung. Stellen Sie sicher, dass Ihr Zertifikat ein RSA-Schlüsselpaar verwendet (nicht EC/ECDSA).
• Schlüsselgröße zu klein – Verwenden Sie eine Schlüsselgröße von mindestens 2048 Bit. RSA-Schlüssel, die kleiner als 2048 Bit sind, werden möglicherweise abgelehnt.
• Algorithmus wird nicht unterstützt – Microsoft Entra verwendet RSA-OAEP für die Schlüsselverpackung. Stellen Sie sicher, dass Ihr Zertifikat und die Anwendungsinfrastruktur diesen Algorithmus unterstützen.

Verschlüsselte Token werden nicht ausgestellt

Symptom: Ihre Anwendung empfängt unverschlüsselte Token, obwohl Sie die Tokenentschlüsselung konfiguriert haben.

Ursachen und Lösungen:

• tokenEncryptionKeyId nicht konfiguriert – Sie müssen diese Eigenschaft explizit über Microsoft Graph festlegen. Das Hochladen des Zertifikats allein reicht nicht aus.
• Das Zertifikat ist in der App-Registrierung abgelaufen – Stellen Sie sicher, dass das in Ihre App-Registrierung hochgeladene Zertifikat nicht abgelaufen ist. Laden Sie bei Bedarf ein neues Zertifikat hoch.
• Zugriffstoken sind nicht verschlüsselt – Die Tokenverschlüsselung gilt nur für ID-Token und SAML-Token . Zugriffstoken von Microsoft Entra werden nicht mit Ihrem Zertifikat verschlüsselt.

Vergleich der Tokenentschlüsselung und der Client-Anmeldeinformationen

Tokenentschlüsselungsanmeldeinformationen dienen einem anderen Zweck als Clientanmeldeinformationen. Ihre Anwendung kann für beide Zertifikate dasselbe Zertifikat verwenden oder separate Zertifikate verwenden.

Das folgende Beispiel zeigt eine Konfiguration, die dasselbe Key Vault Zertifikat für die Authentifizierung und die Tokenentschlüsselung verwendet:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ],
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ]
  }
}

Bewährte Methoden befolgen

Wenden Sie diese Empfehlungen an, wenn Sie die Tokenentschlüsselung implementieren.

Use Azure Key Vault – Speichern Sie Entschlüsselungszertifikate in Key Vault für die zentrale Verwaltung, Zugriffssteuerung und Überwachungsprotokollierung.

Plan für Rotation – Haben Sie vor der Bereitstellung der Tokenverschlüsselung immer eine Rotationsstrategie. Fügen Sie während des Rotationszeitraums sowohl die neuen als auch die alten Zertifikate ein.

Verwenden Sie RSA 2048-Bit oder größere Schlüssel – Stellen Sie sicher, dass Ihre Zertifikate RSA-Schlüssel von mindestens 2048 Bits für eine angemessene Sicherheit verwenden.

Monitor-Zertifikatablauf – Richten Sie Warnungen in Azure Key Vault oder Ihrem Überwachungssystem ein, um Sie zu benachrichtigen, bevor Zertifikate ablaufen.

Testen Sie in einer Stagingumgebung – Überprüfen Sie die Tokenverschlüsselung und -entschlüsselung in einer Nicht-Produktionsumgebung, bevor Sie sie in der Produktion aktivieren.

Speichern Sie keine privaten Schlüssel in der Quellcodeverwaltung – Verwenden Sie Key Vault, Umgebungsvariablen oder einen geheimen Manager für die Zertifikatspeicherung.

Entfernen Sie das alte Zertifikat während der Drehung nicht zu früh . Halten Sie beide Zertifikate mindestens 24 Stunden aktiv, um zuzulassen, dass zwischengespeicherte Token ablaufen.

Aktivieren Sie nicht die Tokenverschlüsselung ohne ein konfiguriertes Entschlüsselungszertifikat. Ihre Anwendung verarbeitet keine Token, wenn sie nicht entschlüsselt werden können.

Verwandte Inhalte

• Übersicht über Anmeldeinformationen
• Übersicht über den Tokencache
• Autorisierung in Web-APIs
• Zertifikatanmeldeinformationen