Konfigurace dešifrování tokenů v Microsoft Identity.Web

Tento článek vysvětluje, jak nakonfigurovat dešifrovací certifikáty tokenů v Microsoft. Identity.Web, aby vaše aplikace mohl dešifrovat šifrované tokeny z Microsoft identity platform.

Ve výchozím nastavení Microsoft identity platform vydává tokeny (tokeny ID, tokeny SAML) jako podepsané, ale nešifrované JWT. Každý zprostředkovatel, který zachytí token, může číst jeho položky. U aplikací, které zpracovávají citlivé deklarace identity nebo pracují v striktních prostředích dodržování předpisů, Microsoft identity platform podporuje šifrování token. Pokud je tato funkce povolená, platforma identity zašifruje datovou část tokenu pomocí veřejného klíče zaregistrovaného ve vaší aplikaci. Pouze vaše aplikace, která obsahuje odpovídající privátní klíč, může dešifrovat a číst token.

Jak funguje šifrování tokenů

Vygenerujete certifikát s párem veřejného a privátního klíče.
Do registrace aplikace v Microsoft Entra ID nahrajete klíč public (soubor .cer).
Když Microsoft identity platform vydá token pro vaši aplikaci, zašifruje token pomocí vašeho veřejného klíče.
Vaše aplikace používá privátní klíč k dešifrování tokenu před zpracováním deklarací identity.

Šifrování používá dvouvrstvé schéma: datová část tokenu se šifruje pomocí šifrovacího klíče symetrického obsahu, který je zabalený (šifrovaný) pomocí veřejného klíče. Microsoft Entra podporuje algoritmy RSA-OAEP a RSA-OAEP-256 key-wrapping.

Určení, kdy nakonfigurovat dešifrování tokenu

Nakonfigurujte dešifrování tokenu, když vaše aplikace splňuje jednu z následujících podmínek:

Přijímá šifrované tokeny SAML – podnikové aplikace, které používají jednotné přihlašování založené na SAML a vyžadují šifrované kontrolní výrazy SAML z důvodů dodržování předpisů nebo právních předpisů.
Přijímá šifrované tokeny ID – webové aplikace, které se přihlašují k šifrování tokenů ID za účelem ochrany citlivých deklarací identity (členství ve skupinách, vlastní deklarace identity) před přenosem.
Pracuje v prostředích s vysokým zabezpečením – aplikace ve scénářích státní správy, financí nebo zdravotnictví, ve kterých zásady vyžadují důvěrnost tokenů.

Poznámka:

Šifrování tokenu je volitelné. Většina aplikací ji nepotřebuje. Šifrování tokenů povolte jenom v případě, že máte konkrétní požadavek, protože zvyšuje provozní složitost (správu certifikátů, obměnu) a ztěžuje řešení potíží.

Splnění požadavků

Před konfigurací dešifrování tokenu ověřte následující požadavky:

Certifikát X.509 s privátním klíčem – Potřebujete certifikát ve formátu .pfx (PKCS#12) nebo uložený na místě přístupném pro vaši aplikaci (Azure Key Vault, úložiště certifikátů, nebo souborový systém). K dešifrování tokenů se vyžaduje privátní klíč.
Registrace aplikace konfigurována pro šifrování tokenů — Nahrajte veřejný klíč certifikátu do registrace vaší aplikace v Microsoft Entra ID. Viz Registrace dešifrovacího certifikátu dále v tomto článku.
Microsoft. Identity.Web 2.1.0 nebo novější – vlastnost konfigurace TokenDecryptionCredentials je dostupná v Microsoft. Identity.Web 2.1.0 a novější

Konfigurace dešifrování tokenů v appsettings.json

Microsoft. Identity.Web používá pole TokenDecryptionCredentials v části konfigurace AzureAd. Toto pole se řídí stejným formátem popisu přihlašovacích údajů jako ClientCredentials, takže můžete načíst dešifrovací certifikáty z Azure Key Vault, úložiště certifikátů, cestu k souboru nebo řetězec s kódováním Base64.

Nastavení základní konfigurace

Následující příklad ukazuje minimální konfiguraci pro načtení dešifrovacího certifikátu z 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"
      }
    ]
  }
}

Nevyžaduje se žádný další kód. Když Microsoft. Identity.Web detekuje konfiguraci TokenDecryptionCredentials, automaticky načte zadaný certifikát a zaregistruje ho pomocí obslužné rutiny ověřování OpenID Connect pro dešifrování tokenu.

Volba zdroje přihlašovacích údajů

Pole TokenDecryptionCredentials podporuje stejné zdrojové typy jako ClientCredentials. Jednotlivé možnosti shrnuje následující tabulka:

Typ zdroje	Description	Požadované vlastnosti
KeyVault	Načtěte certifikát z Azure Key Vault. Doporučeno pro produkční prostředí.	`KeyVaultUrl`, `KeyVaultCertificateName`
StoreWithThumbprint	Načtěte z místního úložiště certifikátů kryptografickým otiskem.	`CertificateStorePath`, `CertificateThumbprint`
StoreWithDistinguishedName	Načíst z místního úložiště certifikátů podle rozlišujícího názvu subjektu.	`CertificateStorePath`, `CertificateDistinguishedName`
Path	Načíst data z `.pfx` souboru uloženého ve file systému.	`CertificateDiskPath`, `CertificatePassword`
Base64Encoded	Načtení z řetězce s kódováním `.pfx` Base64 (užitečné pro proměnné prostředí)	`Base64EncodedValue`

Key Vault (doporučeno pro produkční prostředí)

Následující konfigurace načte dešifrovací certifikát z Azure Key Vault:

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

Spravovaná identita nebo instanční objekt vaší aplikace musí mít oprávnění Get a List pro certifikáty Key Vault.

Úložiště certifikátů (Windows)

Následující konfigurace načte certifikát z úložiště certifikátů Windows kryptografickým otiskem:

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

Cesta k souboru

Následující konfigurace načte certifikát ze .pfx souboru na disku:

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

Výstraha

Vyhněte se ukládání hesel certifikátů v appsettings.json produkčním prostředí. Místo toho použijte proměnné prostředí, odkazy na Azure Key Vault nebo správce tajemství.

Kódování Base64

Následující konfigurace načte certifikát z řetězce s kódováním Base64:

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

Tato možnost je užitečná, když certifikát vložíte prostřednictvím proměnné prostředí nebo tajného klíče kanálu CI/CD.

Konfigurace několika dešifračních certifikátů

V poli můžete zadat více certifikátů TokenDecryptionCredentials . Microsoft.Identity.Web zkouší každý certifikát v pořadí, dokud se token úspěšně dešifruje. Tato funkce je nezbytná pro obměnu certifikátů (viz obměně certifikátů).

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

Registrace dešifrovacího certifikátu v Microsoft Entra ID

Aby platforma Microsoft Identity mohla za účelem zašifrování tokenů pro vaši aplikaci, musíte nahrát veřejný klíč certifikátu do registrace vaší aplikace:

Přihlaste se k Centrum pro správu Microsoft Entra.
Přejděte na Identity>Applications>Registrace aplikací a vyberte aplikaci.
Vyberte Certifikáty & tajemstvíCertifikátyNahrát certifikát.
.cer Nahrajte soubor (jenom veřejný klíč) dešifrovacího certifikátu.
Po nahrání si poznamenejte hodnotu kryptografického otisku – musí odpovídat certifikátu, který vaše aplikace používá.

Povolení šifrování tokenů pro aplikaci

Po nahrání certifikátu musíte aplikaci nakonfigurovat tak, aby přijímala šifrované tokeny. Tato konfigurace je aktuálně dostupná prostřednictvím Microsoft Graph API nebo PowerShellu:

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
}

Důležité

Vlastnost tokenEncryptionKeyId objektu aplikace identifikuje, který nahraný certifikát Microsoft Entra používá k šifrování tokenů. Najednou může být aktivní jenom jeden šifrovací klíč.

Rotovat certifikáty pro dešifrování

Obměně certifikátů pro dešifrování tokenů vyžaduje opatrný a fázovaný přístup, aby nedocházelo k výpadkům:

Postup obměně

Vygenerujte nový certifikát – vytvořte nový certifikát X.509 s privátním klíčem.
Přidejte nový certifikát do konfigurace aplikace – přidejte nový certifikát do TokenDecryptionCredentials pole spolu s existujícím certifikátem. Nejprve umístěte nový certifikát do pole.
Nahrajte nový veřejný klíč — Nahrajte soubor nového certifikátu .cer do registrace vaší aplikace v Microsoft Entra.
Nasaďte aplikaci – Nasaďte aktualizovanou konfiguraci, aby vaše aplikace dešifruje tokeny pomocí některého certifikátu.
Přepněte aktivní šifrovací klíč – Aktualizujte objekt aplikace tak, aby odkazoval na nový certifikát tokenEncryptionKeyIdkeyId.
Ověření – Ověřte , že vaše aplikace úspěšně dešifruje tokeny zašifrované pomocí nového certifikátu.
Odeberte starý certifikát – po období odkladu (alespoň 24 hodin, než vyprší platnost tokenů uložených v mezipaměti), odeberte starý certifikát z registrace aplikace i konfigurace vaší aplikace.

Konfigurace během rotace

Během okna rotace by vaše TokenDecryptionCredentials mělo obsahovat oba certifikáty:

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

Návod

Automatizujte obměnu certifikátů pomocí funkce automatické rotace Azure Key Vault v kombinaci s oznámeními událostí Key Vault pro opětovné nasazení aplikace.

Řešení potíží s dešifrováním tokenů

Při diagnostice a řešení běžných problémů s dešifrování tokenů využijte následující doprovodné materiály.

Selhání dešifrování tokenů

Příznakem: Aplikace vyvolá SecurityTokenDecryptionFailedException nebo vrátí chybu 401/500 při zpracování tokenů.

Běžné příčiny:

Příčina	Řešení
Certifikát nebyl nalezen.	Ověřte, že certifikát existuje v nakonfigurovaném umístění (Key Vault, uložení nebo cesta k souboru). Zkontrolujte, jestli má vaše aplikace požadovaná oprávnění pro přístup.
Nesprávný certifikát	Ověřte, že kryptografický otisk certifikátu v konfiguraci vaší aplikace odpovídá certifikátu nahranému do registrace aplikace.
`tokenEncryptionKeyId` nenastaveno	Nastavte vlastnost `tokenEncryptionKeyId` objektu aplikace v Microsoft Entra. Bez této vlastnosti platforma identit nešifruje tokeny.

Chybějící privátní klíč

Příznak:CryptographicException: The certificate key is not accessible nebo InvalidOperationException: Certificate does not have a private key.

Příčiny a jejich řešení:

Exportovaný certifikát bez privátního klíče – Znovu exportujte certifikát ve .pfx formátu a ujistěte se, že jste během exportu zahrnuli privátní klíč.
Key Vault zásada přístupu — Při použití služby Azure Key Vault se ujistěte, že identita vaší aplikace má oprávnění Get pro Certificates a Secrets. Privátní klíč je uložený jako tajný kód v Key Vault.
Certificate store permissions – Na Windows ověřte, jestli má identita fondu aplikací nebo účet služby přístup pro čtení k privátnímu klíči. Použijte možnost Spravovat privátní klíče v modulu snap-in MMC úložiště certifikátů.

Neshoda algoritmů

Příznak:SecurityTokenDecryptionFailedException se zprávou označující nepodporovaný algoritmus.

Příčiny a jejich řešení:

Nepodporovaný typ klíče – Microsoft Entra podporuje certifikáty RSA pro šifrování tokenů. Ujistěte se, že váš certifikát používá dvojici klíčů RSA (ne EC/ECDSA).
Velikost klíče je příliš malá – použijte velikost klíče nejméně 2048 bitů. Klíče RSA menší než 2048 bitů můžou být odmítnuty.
Algorithm se nepodporuje – Microsoft Entra používá RSA-OAEP pro zabalení klíče. Ujistěte se, že váš certifikát a infrastruktura aplikací podporují tento algoritmus.

Nevystavované šifrované tokeny

Příznakem: Vaše aplikace přijímá nešifrované tokeny, i když jste nakonfigurovali dešifrování tokenů.

Příčiny a jejich řešení:

tokenEncryptionKeyId nenakonfigurováno – Tuto vlastnost musíte explicitně nastavit prostřednictvím Microsoft Graph. Samotné nahrání certifikátu nestačí.
Platnost certifikátu vypršela při registraci aplikace – Ověřte, jestli nevypršela platnost certifikátu nahraného do vaší registrace aplikace. V případě potřeby nahrajte nový certifikát.
Přístupové tokeny nejsou šifrované – Šifrování tokenů se vztahuje pouze na tokeny ID a tokeny SAML . Přístupové tokeny z Microsoft Entra nejsou pomocí vašeho certifikátu šifrované.

Porovnání dešifrování tokenů a přihlašovacích údajů klienta

Přihlašovací údaje pro dešifrování tokenů slouží k jinému účelu než přihlašovací údaje klienta. Vaše aplikace může použít stejný certifikát pro obojí nebo použít samostatné certifikáty.

Následující příklad ukazuje konfiguraci, která používá stejný Key Vault certifikát pro dešifrování ověřování i tokenu:

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

Poznámka:

Pokud použijete stejný certifikát pro oba účely, musí mít použití klíče KeyEncipherment a použít specifikaci KeyExchange klíče (ne Signature). Certifikáty vygenerované pomocí KeySpec = Signature fungují pro klientské přihlašovací údaje, ale při dešifrování tokenu selhávají.

Dodržujte osvědčené postupy.

Tato doporučení použijte při implementaci dešifrování tokenu.

Použití Azure Key Vault – Ukládání dešifrovacích certifikátů ve Key Vault pro centralizovanou správu, řízení přístupu a protokolování auditu.

Plán pro rotaci – Před nasazením šifrování tokenu vždy mějte strategii rotace. Během okna otáčení zahrňte nové i staré certifikáty.

Používejte 2048bitové nebo větší klíče RSA – Zajistěte, aby vaše certifikáty používaly klíče RSA nejméně 2048 bitů pro zajištění odpovídajícího zabezpečení.

Monitorovat vypršení platnosti certifikátu – Nastavte upozornění v Azure Key Vault nebo monitorovacím systému, abyste vás informovali před vypršením platnosti certifikátů.

Testování v přípravném prostředí – Před povolením v produkčním prostředí ověřte šifrování a dešifrování tokenu v neprodukčním prostředí.

Neukládejte soukromé klíče v systému správy verzí — Pro ukládání certifikátů použijte Key Vault, proměnné prostředí nebo správce tajemství.

Během obměny neodebívejte starý certifikát příliš brzy – nechte oba certifikáty aktivní alespoň 24 hodin, aby platnost tokenů uložených v mezipaměti vypršela.

Nepovolujte šifrování tokenů bez nakonfigurovaného dešifrovacího certifikátu – Vaše aplikace nebude moct zpracovávat tokeny, pokud je nedokáže dešifrovat.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-04-29

Konfigurace dešifrování tokenů v Microsoft Identity.Web

Jak funguje šifrování tokenů

Určení, kdy nakonfigurovat dešifrování tokenu

Splnění požadavků

Konfigurace dešifrování tokenů v appsettings.json

Nastavení základní konfigurace

Volba zdroje přihlašovacích údajů

Key Vault (doporučeno pro produkční prostředí)

Úložiště certifikátů (Windows)

Cesta k souboru

Kódování Base64

Konfigurace několika dešifračních certifikátů

Registrace dešifrovacího certifikátu v Microsoft Entra ID

Povolení šifrování tokenů pro aplikaci

Rotovat certifikáty pro dešifrování

Postup obměně

Konfigurace během rotace

Řešení potíží s dešifrováním tokenů

Selhání dešifrování tokenů

Chybějící privátní klíč

Neshoda algoritmů

Nevystavované šifrované tokeny

Porovnání dešifrování tokenů a přihlašovacích údajů klienta

Dodržujte osvědčené postupy.

Související obsah

Váš názor

Další materiály