在 Microsoft.Identity.Web 中設定令牌解密。

本文說明如何在 Microsoft.Identity.Web 中設定權杖解密憑證，以便你的應用程式能夠從 Microsoft 身分識別平台解密加密的權杖。

預設情況下，Microsoft 身分識別平台會以簽名但未加密的 JWT 形式發出權杖（ID 權杖、SAML 權杖）。任何攔截令牌的中介都能讀取其聲明。對於處理敏感索賠或在嚴格合規環境中運作的應用，Microsoft 身分識別平台支援token加密。啟用後，身份平台會使用與應用程式註冊的公鑰加密憑證有效載荷。只有你的應用程式——持有相應私鑰的應用程式——能解密並讀取該令牌。

令牌加密的運作方式

你產生一組包含公私密金鑰對的憑證。
你要在 Microsoft Entra ID 上載 public key（.cer 檔案）到你的應用程式註冊中。
當 Microsoft 身分識別平台為你的應用程式發行令牌時，會用你的公鑰加密該令牌。
你的應用程式會利用私鑰解密令牌，然後再處理申請。

加密採用兩層方案：憑證有效載荷以對稱內容加密金鑰加密，並用公鑰封裝（加密）。 Microsoft Entra 支援 RSA-OAEP 和 RSA-OAEP-256 金鑰包裝演算法。

判斷何時設定令牌解密

當您的應用程式符合以下條件之一時，請配置令牌解密：

接收加密的 SAML 令牌 — 企業應用程式使用基於 SAML 的單一登入，並因合規或法規原因需要加密的 SAML 聲明。
接收加密ID令牌 ——選擇使用ID令牌加密以保護敏感申索（群組成員、自訂申索）在傳輸過程中不被讀取的網頁應用程式。
適用於高安全性環境 — 適用於政府、金融或醫療情境中，政策要求代幣保密的應用。

備註

令牌加密是可選的。大多數應用程式不需要。只有在有特定需求時才啟用令牌加密，因為這會增加操作複雜度（憑證管理、輪替），也讓故障排除更困難。

符合先決條件

在設定令牌解密前，請先確認以下需求：

帶有私鑰的 X.509 憑證 — 您需要一份 .pfx（PKCS#12）格式的憑證，或儲存在應用程式可存取的地點（Azure Key Vault、憑證儲存庫或檔案系統）。解密代幣時需要私鑰。
App 註冊設定為令牌加密 — 將憑證的公鑰上傳到你的應用程式註冊於 Microsoft Entra ID。詳見本文後面的「註冊解密憑證」。
Microsoft.Identity.Web 2.1.0 或更新版本 — TokenDecryptionCredentials 設定屬性在 Microsoft.Identity.Web 2.1.0 及更新版本中可用。

在 appsettings.json 中設定令牌解密

Microsoft。Identity.Web 在你的 TokenDecryptionCredentials 設定區塊中使用了 AzureAd 陣列。此陣列遵循與 ClientCredentials 相同的憑證描述格式，因此你可以從 Azure Key Vault、憑證儲存庫、檔案路徑或 Base64 編碼的字串載入解密憑證。

建立基本配置

以下範例顯示從 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"
      }
    ]
  }
}

不需要額外的程式碼。當 Microsoft。Identity.Web 偵測 TokenDecryptionCredentials 設定，自動載入指定的憑證，並將其註冊至 OpenID Connect 認證處理程序以進行令牌解密。

選擇憑證來源

陣 TokenDecryptionCredentials 列支援與 ClientCredentials相同的來源類型。下表總結了每個選項：

來源類型	說明	必須的屬性
KeyVault	從 Azure Key Vault 載入憑證。推薦用於製作。	`KeyVaultUrl`、`KeyVaultCertificateName`
StoreWithThumbprint	從本地憑證儲存庫用指紋載入。	`CertificateStorePath`、`CertificateThumbprint`
具有專有名稱的存儲	從本地憑證存儲區依主體識別名稱載入。	`CertificateStorePath`、`CertificateDistinguishedName`
路徑	從 `.pfx` 檔案系統上的檔案載入。	`CertificateDiskPath`、`CertificatePassword`
Base64編碼	從 Base64 編碼 `.pfx` 的字串載入（對環境變數很有用）。	`Base64EncodedValue`

金鑰保存庫（建議用於正式環境）

以下配置會載入來自 Azure Key Vault 的解密憑證：

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

你的應用程式的管理身份或服務主體必須在金鑰保存庫憑證上擁有Get和List權限。

憑證儲存（Windows）

以下設定是透過拇指指紋從 Windows 憑證儲存庫載入憑證：

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

檔案路徑

以下設定是從 .pfx 磁碟上的檔案載入憑證：

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

警告

避免在生產環境中儲存憑證密碼 appsettings.json 。請改用環境變數、Azure Key Vault 參考或秘密管理器。

Base64編碼

以下配置是從 Base64 編碼的字串載入憑證：

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

當你透過環境變數或 CI/CD 管線秘密注入憑證時，這個選項非常有用。

設定多個解密憑證

你可以在陣列中指定多個憑證 TokenDecryptionCredentials 。 Microsoft。Identity.Web 依序嘗試每張憑證，直到成功解密該憑證為止。此功能對 憑證輪替 至關重要（參見憑證輪替）。

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

在 Microsoft Entra ID 註冊解密憑證

為了讓Microsoft 身分識別平台加密您的應用程式的憑證，您必須將憑證的公鑰上傳至您的應用程式註冊中：

請登入Microsoft Entra 系統管理中心。
請進入 Identity>Applications>應用程式註冊 選擇您的申請。
選取 [憑證和祕密]>[憑證]>[上傳憑證]。
上傳 .cer 你的解密憑證檔案（僅限公開金鑰）。
上傳後，注意指紋值 — 必須與你的應用程式所使用的憑證相符。

啟用應用程式的令牌加密

上傳憑證後，您必須設定應用程式以接收加密令牌。此設定目前可透過 Microsoft 圖形 API 或 PowerShell 取得：

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
}

這很重要

應用程式物件上的 tokenEncryptionKeyId 屬性用來識別Microsoft Entra用來加密憑證的上傳憑證。同一時間只能啟用一把加密金鑰。

輪換解密憑證

憑證解密的憑證輪替需要謹慎且分階段的方式，以避免停機：

旋轉步驟

產生新憑證 — 建立一枚帶有私鑰的新 X.509 憑證。
將新憑證加入你的應用程式設定 — 將新憑證與現有憑證一同加入 TokenDecryptionCredentials 陣列。將新憑證放在陣列中最前面。
上傳新的公鑰 — 將新憑證的 .cer 檔案上傳到你的應用程式註冊Microsoft Entra。
部署您的應用程式 — 部署更新後的設定，以便您的應用程式能使用任一憑證解密令牌。
切換現用加密金鑰 — 更新應用程式物件上的tokenEncryptionKeyId使其指向新憑證的keyId。
驗證 — 確認您的應用程式成功解密了以新憑證加密的憑證。
移除舊憑證 — 經過一段寬限期（至少 24 小時讓快取憑證過期）後，從你的應用程式註冊和應用程式設定中移除舊憑證。

旋轉時的配置

在輪替期間，你的 TokenDecryptionCredentials 應包含兩份證書：

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

小提示

利用 Azure Key Vault 的自動輪換功能結合金鑰保存庫事件通知，自動啟動應用程式重新部署。

令牌解密故障排除

請依照以下指引診斷並解決常見的令牌解密問題。

令牌解密失敗

症狀： 你的應用程式在處理代幣時會拋 SecurityTokenDecryptionFailedException 出或回傳 401/500 錯誤。

常見原因：

原因	解決方案
找不到憑證	確認憑證是否存在於設定的位置（金鑰保存庫、儲存或檔案路徑）。檢查你的應用程式是否擁有存取所需的權限。
錯誤的證書	確認你應用程式設定中的憑證指紋是否與上傳到應用程式註冊的憑證相符。
`tokenEncryptionKeyId` 未設定	在 Microsoft Entra 中，將應用程式物件上的 `tokenEncryptionKeyId` 屬性設定。若沒有此特性，身份平台就無法加密令牌。

遺失的私鑰

症狀：CryptographicException: The certificate key is not accessible 或 InvalidOperationException: Certificate does not have a private key。

原因和解決方案：

未包含私鑰的憑證已被匯出 — 重新以.pfx格式匯出憑證，並確保在匯出過程中包含私鑰。
金鑰保存庫存取政策 — 使用 Azure Key Vault 時，請確保應用程式的身份在 Certificates 和 Secrets 上都擁有 Get 權限。私鑰會以秘密形式儲存在金鑰保存庫中。
憑證儲存權限 — Windows 時，確認應用程式池身份或服務帳號是否擁有私鑰的讀取權限。請使用憑證儲存 MMC snap-in 中的 「管理私鑰 」選項。

演算法不匹配

症狀：SecurityTokenDecryptionFailedException 並附有訊息表示該演算法不被支援。

原因和解決方案：

Unsupported key type — Microsoft Entra 支援 RSA 憑證用於令牌加密。請確保您的憑證使用RSA金鑰對（而非EC/ECDSA）。
金鑰大小過小 — 使用至少 2048 位元的金鑰大小。 RSA 金鑰小於 2048 位元可能會被拒絕。
演算法不支援 — Microsoft Entra 使用 RSA-OAEP 進行金鑰包裝。確保您的憑證與應用程式基礎架構支援此演算法。

未發出加密令牌

症狀： 即使你設定了令牌解密，你的應用程式仍會收到未加密的令牌。

原因和解決方案：

tokenEncryptionKeyId 未設定 — 您必須透過 Microsoft Graph 明確設定此屬性。僅僅上傳憑證是不夠的。
應用程式註冊時的證書已過期 — 確認上傳到應用程式註冊的證書是否已過期。如果需要，請上傳新的證書。
存取權杖不 加密——令牌加密僅適用於 ID 令牌 和 SAML 令牌 。 Microsoft Entra 的存取權杖並未使用你的憑證進行加密。

比較令牌解密與用戶端憑證

令牌解密憑證與用戶端憑證有不同的用途。你的應用程式可以同時使用同一個憑證，或使用不同的憑證。

以下範例展示了一種使用相同金鑰保存庫憑證進行認證與令牌解密的設定：

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

備註

當你同時使用同一張憑證時，憑證必須包含 KeyEncipherment 金鑰使用並使用 KeyExchange 金鑰規範（而非 Signature）。用 Certs KeySpec = Signature 產生的憑證對用戶端憑證有效，但在 token 解密時失敗。

遵循最佳做法

在實施令牌解密時，請應用這些建議。

使用 Azure Key Vault — 將解密憑證儲存在金鑰保存庫中，用於集中管理、存取控制及稽核記錄。

規劃輪替 — 在部署令牌加密前，務必先制定輪替策略。在輪替期間，請同時包含新舊證書。

使用 RSA 2048 位元或以上的金鑰 — 確保您的憑證至少使用 2048 位元的 RSA 金鑰以確保安全性。

監控憑證到期 — 在Azure Key Vault或監控系統中設置警示，在憑證到期前通知您。

在暫存環境中測試 — 在非生產環境中驗證令牌加密與解密，然後再啟用於正式環境。

不要將私鑰儲存在原始碼控制 — 憑證儲存時使用金鑰保存庫、環境變數或秘密管理器。

不要在輪替時太早移除舊憑證——保持兩張憑證至少有效 24 小時，以便讓快取的權杖過期。

未設定解密憑證前不要啟用令牌加密 ——如果應用程式無法解密令牌，它將無法處理。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-29

在 Microsoft.Identity.Web 中設定令牌解密。

令牌加密的運作方式

判斷何時設定令牌解密

符合先決條件

在 appsettings.json 中設定令牌解密

建立基本配置

選擇憑證來源

金鑰保存庫（建議用於正式環境）

憑證儲存（Windows）

檔案路徑

Base64編碼

設定多個解密憑證

在 Microsoft Entra ID 註冊解密憑證

啟用應用程式的令牌加密

輪換解密憑證

旋轉步驟

旋轉時的配置

令牌解密故障排除

令牌解密失敗

遺失的私鑰

演算法不匹配

未發出加密令牌

比較令牌解密與用戶端憑證

遵循最佳做法

相關內容

意見反應

其他資源