Konfigurera tokendekryptering i Microsoft. Identity.Web

I den här artikeln beskrivs hur du konfigurerar certifikat för tokenkryptering i Microsoft. Identity.Web så att programmet kan dekryptera krypterade token från Microsofts identitetsplattform.

Som standard utfärdar Microsofts identitetsplattform token (ID-token, SAML-token) som signerade men okrypterade JWT:er. Alla mellanhänder som intercepterar en token kan läsa dess innehåll. För program som hanterar känsliga anspråk eller fungerar i strikta efterlevnadsmiljöer stöder Microsofts identitetsplattform token kryptering. När den är aktiverad krypterar identitetsplattformen tokennyttolasten med hjälp av en offentlig nyckel som registrerats med ditt program. Endast ditt program – som innehåller motsvarande privata nyckel – kan dekryptera och läsa token.

Så här fungerar tokenkryptering

1. Du genererar ett certifikat med ett offentligt/privat nyckelpar.
2. Du laddar upp den offentliga nyckeln (filen .cer) till din appregistrering i Microsoft Entra ID.
3. När Microsofts identitetsplattform utfärdar en token för ditt program krypteras token med hjälp av din offentliga nyckel.
4. Ditt program använder den privata nyckeln för att dekryptera token innan anspråk bearbetas.

Krypteringen använder ett tvåskiktsschema: tokennyttolasten krypteras med en symmetrisk innehållskrypteringsnyckel som omsluts (krypteras) med din offentliga nyckel. Microsoft Entra stöder RSA-OAEP- och RSA-OAEP-256-nyckelomslutningsalgoritmer.

Avgöra när tokendekryptering ska konfigureras

Konfigurera tokendekryptering när programmet uppfyller något av följande villkor:

• Tar emot krypterade SAML-token – Företagsprogram som använder SAML-baserad enkel inloggning och kräver krypterade SAML-intyg av efterlevnads- eller regelskäl.
• Tar emot krypterade ID-token – webbprogram som väljer ID-tokenkryptering för att skydda känsliga anspråk (gruppmedlemskap, anpassade anspråk) från att läsas under överföring.
• Fungerar i miljöer med hög säkerhet – Program i myndighets-, ekonomi- eller sjukvårdsscenarier där tokensekretess krävs av principen.

Uppfylla kraven

Kontrollera följande krav innan du konfigurerar tokendekryptering:

• An X.509-certifikat med en privat nyckel – Du behöver ett certifikat i .pfx -format (PKCS#12) eller lagras på en plats som är tillgänglig för ditt program (Azure Key Vault, certifikatarkiv eller filsystem). Den privata nyckeln krävs för att dekryptera token.
• Appregistrering konfigurerad för tokenkryptering – Ladda upp certifikatets offentliga nyckel till din appregistrering i Microsoft Entra ID. Mer information finns i Registrera dekrypteringscertifikatet senare i den här artikeln.
• Microsoft. Identity.Web 2.1.0 eller senare – konfigurationsegenskapen TokenDecryptionCredentials är tillgänglig i Microsoft. Identity.Web 2.1.0 och senare.

Konfigurera tokendekryptering i appsettings.json

Microsoft. Identity.Web använder matrisen TokenDecryptionCredentials i konfigurationsavsnittet AzureAd. Den här matrisen följer samma beskrivningsformat för autentiseringsuppgifter som ClientCredentials, så att du kan läsa in dekrypteringscertifikat från Azure Key Vault, certifikatarkivet, en filsökväg eller en Base64-kodad sträng.

Konfigurera en grundläggande konfiguration

I följande exempel visas den minsta konfigurationen för att läsa in ett dekrypteringscertifikat från 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"
      }
    ]
  }
}

Ingen ytterligare kod krävs. När Microsoft. Identity.Web identifierar konfigurationen TokenDecryptionCredentials. Det läser automatiskt in det angivna certifikatet och registrerar det med OpenID Connect-autentiseringshanteraren för tokendekryptering.

Välj en källa för autentiseringsuppgifter

Matrisen TokenDecryptionCredentials stöder samma källtyper som ClientCredentials. I följande tabell sammanfattas varje alternativ:

Key Vault (rekommenderas för produktion)

Följande konfiguration läser in ett dekrypteringscertifikat från Azure Key Vault:

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

Programmets hanterade identitet eller tjänstprincipalen måste ha behörigheterna Get och List för certifikat i Key Vault.

Certifikatarkiv (Windows)

Följande konfiguration läser in ett certifikat från Windows certifikatarkivet med tumavtryck:

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

Filväg

Följande konfiguration läser in ett certifikat från en .pfx fil på disken:

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

Base64-kodad

Följande konfiguration läser in ett certifikat från en Base64-kodad sträng:

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

Det här alternativet är användbart när du matar in certifikatet via en miljövariabel eller EN CI/CD-pipelinehemlighet.

Konfigurera flera dekrypteringscertifikat

Du kan ange flera certifikat i matrisen TokenDecryptionCredentials . Microsoft.Identity.Web försöker dekryptera varje certifikat i ordning tills ett framgångsrikt avkrypterar token. Den här funktionen är viktig för certifikatrotation (se Certifikatrotation).

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

Registrera dekrypteringscertifikatet i Microsoft Entra ID

För att Microsofts identitetsplattform ska kunna kryptera tokens för ditt program, måste du ladda upp certifikatets publika nyckel till din appregistrering.

1. Logga in på Microsoft Entra administrationscenter.
2. Gå till Identity>Applications>App registrations och välj ditt program.
3. Välj Certifikat och hemligheter>Certifikat>Ladda upp certifikat.
4. .cer Ladda upp filen (endast offentlig nyckel) för dekrypteringscertifikatet.
5. När du har laddat upp noterar du tumavtrycksvärdet – det måste matcha certifikatet som programmet använder.

Aktivera tokenkryptering för programmet

När du har laddat upp certifikatet måste du konfigurera programmet så att det tar emot krypterade token. Den här konfigurationen är för närvarande tillgänglig via Microsoft Graph API eller PowerShell:

Använda 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
}

Byt ut dekrypteringscertifikat

Certifikatrotation för tokendekryptering kräver en noggrann, stegvis metod för att undvika stilleståndstid:

Rotationssteg

1. Generera ett nytt certifikat – Skapa ett nytt X.509-certifikat med en privat nyckel.
2. Lägg till det nya certifikatet i programkonfigurationen – Lägg till det nya certifikatet i matrisen TokenDecryptionCredentials tillsammans med det befintliga certifikatet. Placera det nya certifikatet först i matrisen.
3. Ladda upp den nya offentliga nyckeln – Ladda upp det nya certifikatets .cer-fil till din appregistrering i Microsoft Entra.
4. Distribuera ditt program – Distribuera den uppdaterade konfigurationen så att programmet kan dekryptera token med något av certifikaten.
5. Växla den aktiva krypteringsnyckeln – Uppdatera tokenEncryptionKeyId programobjektet så att det pekar på det nya certifikatets keyId.
6. Kontrollera – Bekräfta att programmet har dekrypterat token som krypterats med det nya certifikatet.
7. Ta bort det gamla certifikatet – Efter en respitperiod (minst 24 timmar för att tillåta att cachelagrade token upphör att gälla) tar du bort det gamla certifikatet från både appregistreringen och programkonfigurationen.

Konfiguration under pågående rotation

Under rotationsfönstret bör din TokenDecryptionCredentials innehålla båda certifikaten:

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

Felsöka tokendekryptering

Använd följande vägledning för att diagnostisera och lösa vanliga problem med tokendekryptering.

Fel vid tokendekryptering

Symptom: Ditt program genererar ett SecurityTokenDecryptionFailedException eller returnerar ett 401/500-fel vid bearbetning av token.

Vanliga orsaker:

Privat nyckel saknas

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

Orsaker och lösningar:

• Certifikat som exporteras utan privat nyckel – Exportera certifikatet på nytt i .pfx format och se till att du inkluderar den privata nyckeln under exporten.
• Key Vault åtkomstprincip – När du använder Azure Key Vault, kontrollera att programmets identitet har behörigheten Get på både Certificates och Secrets. Den privata nyckeln lagras som en hemlighet i Key Vault.
• Certifikatarkivbehörigheter – På Windows kontrollerar du att programpoolens identitet eller tjänstkonto har läsbehörighet till den privata nyckeln. Använd alternativet Hantera privata nycklar i mmc-snapin-modulen för certifikatarkivet.

Matchningsfel för algoritm

Symptom:SecurityTokenDecryptionFailedException med ett meddelande som anger en algoritm som inte stöds.

Orsaker och lösningar:

• Unsupported key type – Microsoft Entra stöder RSA-certifikat för tokenkryptering. Kontrollera att certifikatet använder ett RSA-nyckelpar (inte EC/ECDSA).
• Nyckelstorleken är för liten – Använd en nyckelstorlek på minst 2 048 bitar. RSA-nycklar som är mindre än 2 048 bitar kan avvisas.
• Algorithm stöds inte – Microsoft Entra använder RSA-OAEP för nyckelomslutning. Se till att certifikat- och programinfrastrukturen stöder den här algoritmen.

Krypterade token utfärdas inte

Symptom: Programmet tar emot okrypterade token trots att du har konfigurerat tokendekryptering.

Orsaker och lösningar:

• tokenEncryptionKeyId inte konfigurerad – Du måste uttryckligen ange den här egenskapen via Microsoft Graph. Det räcker inte att ladda upp certifikatet ensamt.
• Certifikatet har upphört att gälla vid appregistrering – Kontrollera att certifikatet som laddats upp till din appregistrering inte har upphört att gälla. Ladda upp ett nytt certifikat om det behövs.
• Åtkomsttoken krypteras inte – Tokenkryptering gäller endast för ID-token och SAML-token . Åtkomsttoken från Microsoft Entra krypteras inte med ditt certifikat.

Jämför tokendekryptering och klientautentiseringsuppgifter

Autentiseringsuppgifter för tokenkryptering har ett annat syfte än klientautentiseringsuppgifter. Programmet kan använda samma certifikat för båda eller använda separata certifikat.

I följande exempel visas en konfiguration som använder samma Key Vault certifikat för både autentisering och tokendekryptering:

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

Följ metodtipsen

Använd dessa rekommendationer när du implementerar tokendekryptering.

Använd Azure Key Vault – Lagra dekrypteringscertifikat i Key Vault för centraliserad hantering, åtkomstkontroll och granskningsloggning.

Planera för rotation – Ha alltid en rotationsstrategi innan du distribuerar tokenkryptering. Inkludera både de nya och gamla certifikaten under rotationsfönstret.

Använd RSA 2048-bitars eller större nycklar – Se till att dina certifikat använder RSA-nycklar på minst 2 048 bitar för tillräcklig säkerhet.

Övervaka certifikatets giltighetstid – Konfigurera aviseringar i Azure Key Vault eller övervakningssystemet för att meddela dig innan certifikaten upphör att gälla.

Test i en mellanlagringsmiljö – Verifiera tokenkryptering och dekryptering i en icke-produktionsmiljö innan du aktiverar den i produktion.

Det går inte att lagra privata nycklar i källkontrollen – Använd Key Vault, miljövariabler eller en hemlighetshanterare för certifikatlagring.

Ta inte bort det gamla certifikatet för tidigt under rotationen – Håll båda certifikaten aktiva i minst 24 timmar så att cachelagrade token upphör att gälla.

Aktivera inte tokenkryptering utan att ett dekrypteringscertifikat har konfigurerats – Programmet kan inte bearbeta token om det inte kan dekryptera dem.

Relaterat innehåll

• Översikt över autentiseringsuppgifter
• Översikt över tokencache
• Auktorisering i webb-API:er
• Certifikatautentiseringsuppgifter