Configureer tokenontsleuteling in Microsoft.Identity.Web

In dit artikel wordt uitgelegd hoe u tokenontsleutelingscertificaten configureert in Microsoft. Identity.Web zodat uw toepassing versleutelde tokens uit de Microsoft identity platform kan ontsleutelen.

Standaard geeft de Microsoft identity platform tokens (ID-tokens, SAML-tokens) uit als ondertekende maar niet-versleutelde JWT's. Elke tussenpersoon die een token onderschept, kan de claims lezen. Voor toepassingen die gevoelige claims verwerken of in strikte nalevingsomgevingen werken, ondersteunt de Microsoft identity platform tokenversleuteling. Wanneer dit is ingeschakeld, versleutelt het identiteitsplatform de tokenpayload met behulp van een openbare sleutel die is geregistreerd bij uw toepassing. Alleen uw toepassing, die de bijbehorende persoonlijke sleutel bevat, kan het token ontsleutelen en lezen.

Hoe tokenversleuteling werkt

1. U genereert een certificaat met een openbaar/persoonlijk sleutelpaar.
2. U uploadt de public key (het bestand .cer) naar uw app-registratie in Microsoft Entra ID.
3. Wanneer het Microsoft identity platform een token voor uw toepassing uitgeeft, wordt het token versleuteld met behulp van uw openbare sleutel.
4. Uw toepassing gebruikt de persoonlijke sleutel om het token te ontsleutelen voordat claims worden verwerkt.

De versleuteling maakt gebruik van een schema met twee lagen: de nettolading van het token wordt versleuteld met een symmetrische versleutelingssleutel voor inhoud, die is verpakt (versleuteld) met behulp van uw openbare sleutel. Microsoft Entra ondersteunt RSA-OAEP- en RSA-OAEP-256-sleutelterugloopalgoritmen.

Bepalen wanneer tokenontsleuteling moet worden geconfigureerd

Configureer tokenontsleuteling wanneer uw toepassing aan een van de volgende voorwaarden voldoet:

• Ontvangt versleutelde SAML-tokens : bedrijfstoepassingen die gebruikmaken van eenmalige aanmelding op basis van SAML en versleutelde SAML-asserties vereisen om nalevings- of regelgevingsredenen.
• Hiermee ontvangt u versleutelde id-tokens : webtoepassingen die zich aanmelden voor id-tokenversleuteling om gevoelige claims (groepslidmaatschappen, aangepaste claims) te beveiligen, kunnen niet worden gelezen in transit.
• Werkt in omgevingen met hoge beveiliging : toepassingen in overheids-, financiële of gezondheidszorgscenario's waarbij tokengeheim wordt verplicht door beleid.

Voldoen aan de vereisten

Voordat u tokenontsleuteling configureert, moet u de volgende vereisten controleren:

• An X.509-certificaat met een persoonlijke sleutel — U hebt een certificaat in .pfx -indeling (PKCS#12) nodig of opgeslagen op een locatie die toegankelijk is voor uw toepassing (Azure Key Vault, certificaatarchief of bestandssysteem). De persoonlijke sleutel is vereist voor het ontsleutelen van tokens.
• App-registratie geconfigureerd voor tokenversleuteling: upload de openbare sleutel van het certificaat naar uw app-registratie in Microsoft Entra ID. Zie Het ontsleutelingscertificaat verderop in dit artikel registreren.
• Microsoft. Identity.Web 2.1.0 of hoger — De configuratie-eigenschap TokenDecryptionCredentials is beschikbaar in Microsoft. Identity.Web 2.1.0 en hoger.

Tokenontsleuteling configureren in appsettings.json

Microsoft. Identity.Web maakt gebruik van de matrix TokenDecryptionCredentials in de configuratiesectie AzureAd. Deze matrix volgt dezelfde referentiebeschrijvingsindeling als ClientCredentials, zodat u ontsleutelingscertificaten kunt laden uit Azure Key Vault, het certificaatarchief, een bestandspad of een met Base64 gecodeerde tekenreeks.

Een basisconfiguratie instellen

In het volgende voorbeeld ziet u de minimale configuratie voor het laden van een ontsleutelingscertificaat uit 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"
      }
    ]
  }
}

Er is geen extra code vereist. Wanneer Microsoft. Identity.Web detecteert de configuratie TokenDecryptionCredentials, het laadt het opgegeven certificaat automatisch en registreert het bij de OpenID Connect-verificatiehandler voor tokenontsleuteling.

Een referentiebron kiezen

De TokenDecryptionCredentials matrix ondersteunt dezelfde brontypen als ClientCredentials. De volgende tabel bevat een overzicht van elke optie:

Key Vault (aanbevolen voor productie)

Met de volgende configuratie wordt een ontsleutelingscertificaat uit Azure Key Vault geladen:

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

De beheerde identiteit of service-principal van uw toepassing moet beschikken over Get en Lijst machtigingen voor de Key Vault-certificaten.

Certificaatopslag (Windows)

Met de volgende configuratie wordt een certificaat uit het Windows certificaatarchief met vingerafdruk geladen:

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

Bestandspad

Met de volgende configuratie wordt een certificaat uit een .pfx bestand op schijf geladen:

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

Base64-gecodeerd

Met de volgende configuratie wordt een certificaat uit een met Base64 gecodeerde tekenreeks geladen:

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

Deze optie is handig wanneer u het certificaat injecteert via een omgevingsvariabele of CI/CD-pijplijngeheim.

Meerdere ontsleutelingscertificaten configureren

U kunt meerdere certificaten opgeven in de TokenDecryptionCredentials matrix. Microsoft. Identity.Web probeert elk certificaat op volgorde totdat het token is ontsleuteld. Deze mogelijkheid is essentieel voor certificaatrotatie (zie Certificaatrotatie).

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

Het ontsleutelingscertificaat registreren in Microsoft Entra ID

Opdat het Microsoft identity platform tokens voor uw applicatie kan versleutelen, moet u de publieke sleutel van het certificaat uploaden naar uw app-registratie.

1. Meld u aan bij de Microsoft Entra-beheercentrum.
2. Navigeer naar Identity>Applications>App-registraties en selecteer uw toepassing.
3. Selecteer Certificaten en geheimen>Certificaten>Certificaat uploaden.
4. Upload het .cer bestand (alleen openbare sleutel) van uw ontsleutelingscertificaat.
5. Na het uploaden noteert u de vingerafdrukwaarde . Deze moet overeenkomen met het certificaat dat door uw toepassing wordt gebruikt.

Tokenversleuteling inschakelen voor de toepassing

Nadat u het certificaat hebt geüpload, moet u uw toepassing configureren om versleutelde tokens te ontvangen. Deze configuratie is momenteel beschikbaar via de Microsoft Graph API of PowerShell:

Het gebruik van 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
}

Ontsleutelingscertificaten vervangen

Certificaatrotatie voor tokenontsleuteling vereist een zorgvuldige, gefaseerde benadering om downtime te voorkomen:

Rotatiestappen

1. Een nieuw certificaat genereren : maak een nieuw X.509-certificaat met een persoonlijke sleutel.
2. Voeg het nieuwe certificaat toe aan uw toepassingsconfiguratie: voeg het nieuwe certificaat toe aan de TokenDecryptionCredentials matrix naast het bestaande certificaat. Plaats het nieuwe certificaat eerst in de matrix.
3. Upload the new public key — Upload het bestand .cer van het nieuwe certificaat naar uw app-registratie in Microsoft Entra.
4. Implementeer uw toepassing: implementeer de bijgewerkte configuratie zodat uw toepassing tokens kan ontsleutelen met een van beide certificaten.
5. Wijzig de actieve versleutelingssleutel: werk het tokenEncryptionKeyId toepassingsobject bij zodat het naar het keyId van het nieuwe certificaat verwijst.
6. Controleren : controleer of uw toepassing tokens ontsleutelt die zijn versleuteld met het nieuwe certificaat.
7. Verwijder het oude certificaat : na een respijtperiode (ten minste 24 uur om tokens in de cache te laten verlopen), verwijdert u het oude certificaat uit zowel uw app-registratie als de toepassingsconfiguratie.

Configuratie tijdens rotatie

Tijdens het draaivenster moet TokenDecryptionCredentials beide certificaten bevatten.

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

Problemen met tokenontsleuteling oplossen

Gebruik de volgende richtlijnen om veelvoorkomende problemen met tokenontsleuteling vast te stellen en op te lossen.

Fouten bij het ontsleutelen van tokens

Symptoom: Uw toepassing genereert een SecurityTokenDecryptionFailedException of retourneert een 401/500-fout bij het verwerken van tokens.

Veelvoorkomende oorzaken:

Ontbrekende persoonlijke sleutel

Symptoom:CryptographicException: The certificate key is not accessible of InvalidOperationException: Certificate does not have a private key.

Oorzaken en oplossingen:

• Certificaat dat is geëxporteerd zonder persoonlijke sleutel : exporteer het certificaat opnieuw in .pfx indeling en zorg ervoor dat u de persoonlijke sleutel tijdens het exporteren opneemt.
• Key Vault toegangsbeleid — Wanneer u Azure Key Vault gebruikt, zorg ervoor dat de identiteit van uw toepassing de machtiging Get heeft voor zowel Certificates als Secrets. De persoonlijke sleutel wordt opgeslagen als een geheim in Key Vault.
• Certificaatopslagmachtigingen — Controleer op Windows of de identiteit van de applicatiepool of het serviceaccount leestoegang heeft tot de privésleutel. Gebruik de optie Beheer persoonlijke sleutels in de certificaatstores MMC-module.

Algoritme komt niet overeen

Symptoom:SecurityTokenDecryptionFailedException met een bericht dat een niet-ondersteund algoritme aangeeft.

Oorzaken en oplossingen:

• Niet-ondersteund sleuteltype — Microsoft Entra ondersteunt RSA-certificaten voor tokenversleuteling. Zorg ervoor dat uw certificaat gebruikmaakt van een RSA-sleutelpaar (niet EC/ECDSA).
• Sleutelgrootte te klein : gebruik een sleutelgrootte van ten minste 2048 bits. RSA-sleutels die kleiner zijn dan 2048 bits, kunnen worden geweigerd.
• Algoritme wordt niet ondersteund — Microsoft Entra gebruikt RSA-OAEP voor sleutelomslag. Zorg ervoor dat uw certificaat- en toepassingsinfrastructuur dit algoritme ondersteunen.

Versleutelde tokens worden niet uitgegeven

Symptoom: Uw toepassing ontvangt niet-versleutelde tokens, ook al hebt u tokenontsleuteling geconfigureerd.

Oorzaken en oplossingen:

• tokenEncryptionKeyId niet geconfigureerd — U moet deze eigenschap expliciet instellen via Microsoft Graph. Het uploaden van het certificaat is niet voldoende.
• Certificaat is verlopen in app-registratie : controleer of het certificaat dat is geüpload naar uw app-registratie niet is verlopen. Upload indien nodig een nieuw certificaat.
• Toegangstokens zijn niet versleuteld . Tokenversleuteling is alleen van toepassing op id-tokens en SAML-tokens . Toegangstokens van Microsoft Entra worden niet versleuteld met uw certificaat.

Tokenontsleuteling en clientreferenties vergelijken

Tokenontsleutelingsreferenties dienen een ander doel dan clientreferenties. Uw toepassing kan hetzelfde certificaat voor beide gebruiken of afzonderlijke certificaten gebruiken.

In het volgende voorbeeld ziet u een configuratie die gebruikmaakt van hetzelfde Key Vault certificaat voor zowel verificatie als tokenontsleuteling:

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

Best practices volgen

Pas deze aanbevelingen toe wanneer u tokenontsleuteling implementeert.

Gebruik Azure Key Vault — Bewaar ontsleutelingscertificaten in Key Vault voor gecentraliseerd beheer, toegangsbeheer en auditlogboekregistratie.

Plannen voor rotatie : altijd een rotatiestrategie hebben voordat u tokenversleuteling implementeert. Neem zowel de nieuwe als de oude certificaten op tijdens het draaivenster.

Gebruik RSA 2048-bits of grotere sleutels : zorg ervoor dat uw certificaten RSA-sleutels van ten minste 2048 bits gebruiken voor voldoende beveiliging.

Controlecertificaatverloop — Stel waarschuwingen in Azure Key Vault of uw bewakingssysteem in om u te waarschuwen voordat certificaten verlopen.

Testen in een faseringsomgeving : verifieer tokenversleuteling en ontsleuteling in een niet-productieomgeving voordat u deze inschakelt in productie.

Geen persoonlijke sleutels opslaan in broncodebeheer — Gebruik Key Vault, omgevingsvariabelen of geheimenbeheerder voor certificaatopslag.

Verwijder het oude certificaat niet te vroeg tijdens het rouleren . Houd beide certificaten minstens 24 uur actief om toe te staan dat tokens in de cache verlopen.

Schakel tokenversleuteling niet in zonder dat er een ontsleutelingscertificaat is geconfigureerd . Uw toepassing kan tokens niet verwerken als deze niet kunnen ontsleutelen.

Verwante inhoud

• Overzicht van referenties
• Overzicht van tokencache
• Autorisatie in web-API's
• Certificaatreferenties