Microsoftでトークンの暗号化解除を構成します。Identity.Web

この記事では、Microsoftでトークン暗号化解除証明書を構成する方法について説明します。アプリケーションがMicrosoft ID プラットフォームから暗号化されたトークンを復号化できるようにする Identity.Web。

既定では、Microsoft ID プラットフォームはトークン (ID トークン、SAML トークン) を署名済みで暗号化されていない JWT として発行します。トークンをインターセプトするすべての仲介者は、その要求を読み取ることができます。機密性の高い要求を処理するアプリケーション、または厳密なコンプライアンス環境で動作するアプリケーションの場合、Microsoft ID プラットフォームは token 暗号化をサポートします。有効にすると、ID プラットフォームは、アプリケーションに登録されている公開キーを使用してトークンペイロードを暗号化します。トークンの暗号化を解除して読み取ることができるのは、対応する秘密キーを保持しているアプリケーションだけです。

トークン暗号化のしくみ

公開キーと秘密キーのペアを使用して証明書を生成します。
public key (.cer ファイル) をMicrosoft Entra IDのアプリ登録にアップロードします。
Microsoft ID プラットフォームがアプリケーションのトークンを発行すると、公開キーを使用してトークンが暗号化されます。
アプリケーションでは、要求を処理する前に 秘密キー を使用してトークンの暗号化を解除します。

暗号化では、2 層スキームが使用されます。トークンペイロードは対称コンテンツ暗号化キーで暗号化され、公開キーを使用してラップ (暗号化) されます。 Microsoft Entraでは、RSA-OAEP および RSA-OAEP-256 キーラッピングアルゴリズムがサポートされています。

トークン暗号化解除を構成するタイミングを決定する

アプリケーションが次のいずれかの条件を満たす場合にトークンの暗号化解除を構成します。

暗号化された SAML トークンを受信 します。SAML ベースのシングルサインオンを使用し、コンプライアンスまたは規制上の理由から暗号化された SAML アサーションを必要とするエンタープライズアプリケーション。
暗号化された ID トークンを受け取ります 。機密性の高い要求 (グループメンバーシップ、カスタムクレーム) が転送中に読み取られるのを防ぎ、ID トークン暗号化をオプトインする Web アプリケーション。
高セキュリティ環境で動作します 。トークンの機密性がポリシーによって義務付けられている、政府、財務、または医療のシナリオでのアプリケーション。

注

トークンの暗号化は省略可能です。ほとんどのアプリケーションでは必要ありません。操作の複雑さ (証明書の管理、ローテーション) が追加され、トラブルシューティングがより困難になるため、特定の要件がある場合にのみトークン暗号化を有効にします。

前提条件を満たす

トークンの暗号化解除を構成する前に、次の要件を確認します。

秘密キーを持つ X.509 証明書 — .pfx (PKCS#12) 形式の証明書が必要です。または、アプリケーション (Azure Key Vault、証明書ストア、またはファイルシステム) からアクセスできる場所に格納する必要があります。トークンの暗号化を解除するには、秘密キーが必要です。
トークン暗号化用に構成されたアプリケーション登録 — 証明書の公開キーを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`
StoreWithDistinguishedName	サブジェクト識別名を使用してローカル証明書ストアから読み込みます。	`CertificateStorePath`、`CertificateDistinguishedName`
Path	ファイルシステム上の `.pfx` ファイルから読み込みます。	`CertificateDiskPath`、`CertificatePassword`
Base64Encoded	Base64 でエンコードされた `.pfx` 文字列から読み込みます (環境変数に役立ちます)。	`Base64EncodedValue`

Key Vault (本番環境用に推奨)

次の構成では、Azure Key Vaultから暗号化解除証明書を読み込みます。

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

アプリケーションのマネージド ID またはサービスプリンシパルには、Key Vault証明書に対する 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"
    }
  ]
}

Warnung

運用環境の 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 ID プラットフォームがアプリケーションのトークンを暗号化するには、証明書の public key をアプリの登録にアップロードする必要があります。

Microsoft Entra 管理センターにサインインします。
Identity>Applications>アプリの登録 に移動し、アプリケーションを選択します。
証明書とシークレット>Certificates>証明書のアップロードを選択します。
暗号化解除証明書の .cer ファイル (公開キーのみ) をアップロードします。
アップロード後、拇印の値を書き留めます。これは、アプリケーションが使用する証明書と一致している必要があります。

アプリケーションのトークン暗号化を有効にする

証明書をアップロードした後、暗号化されたトークンを受信するようにアプリケーションを構成する必要があります。現在、この構成は Microsoft Graph API または PowerShell を通じて使用できます。

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
}

Important

アプリケーションオブジェクトの tokenEncryptionKeyId プロパティは、トークンの暗号化に使用Microsoft Entraアップロードされた証明書を識別します。一度にアクティブにできる暗号化キーは 1 つだけです。

暗号化解除証明書をローテーションする

トークン暗号化解除の証明書ローテーションでは、ダウンタイムを回避するために慎重で段階的なアプローチが必要です。

回転ステップ

新しい証明書を生成 する - 秘密キーを使用して新しい 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の自動ローテーション機能とKey Vaultイベント通知を組み合わせて使用して証明書のローテーションを自動化し、アプリケーションの再デプロイをトリガーします。

トークンの暗号化解除のトラブルシューティング

一般的なトークン暗号化解除の問題を診断して解決するには、次のガイダンスを使用します。

トークンの暗号化解除の失敗

症状： アプリケーションが SecurityTokenDecryptionFailedException をスローするか、トークンを処理するときに 401/500 エラーを返します。

一般的な原因:

原因	ソリューション
証明書が見つかりません	構成された場所 (Key Vault、ストア、またはファイルパス) に証明書が存在するかどうかを確認します。アプリケーションにアクセスするために必要なアクセス許可があることを確認します。
間違った証明書	アプリケーション構成の証明書の拇印が、アプリ登録にアップロードされた証明書と一致することを確認します。
`tokenEncryptionKeyId` 設定されていません	Microsoft Entraのアプリケーションオブジェクトに`tokenEncryptionKeyId` プロパティを設定します。このプロパティがないと、ID プラットフォームはトークンを暗号化しません。

秘密キーがありません

現象:CryptographicException: The certificate key is not accessible または InvalidOperationException: Certificate does not have a private key。

原因と解決策:

秘密キーなしでエクスポートされた証明書 — .pfx 形式で証明書を再エクスポートし、エクスポート時に秘密キーを含めます。
Key Vault アクセスポリシー — Azure Key Vaultを使用する場合は、アプリケーションの ID に、Certificates と Secrets の両方に対する Get アクセス許可があることを確認します。秘密キーはシークレットとしてKey Vaultに格納されます。
Certificate ストアのアクセス許可 — Windowsで、アプリケーションプール ID またはサービスアカウントが秘密キーへの読み取りアクセス権を持っていることを確認します。証明書ストア MMC スナップインの [秘密キーの管理 ] オプションを使用します。

アルゴリズムの不一致

現象:SecurityTokenDecryptionFailedException サポートされていないアルゴリズムを示すメッセージが表示されます。

原因と解決策:

サポートされていないキータイプ — Microsoft Entraでは、トークン暗号化用のRSA証明書がサポートされています。証明書で (EC/ECDSA ではなく) RSA キーペアを使用していることを確認します。
キーサイズが小さすぎます - 少なくとも 2048 ビットのキーサイズを使用します。 2048 ビットより小さい RSA キーは拒否される可能性があります。
アルゴリズムはサポートされていません — Microsoft Entra はキーラッピングに RSA-OAEP を使用しています。証明書とアプリケーションインフラストラクチャがこのアルゴリズムをサポートしていることを確認します。

暗号化されたトークンが発行されていない

症状： トークンの暗号化解除を構成した場合でも、アプリケーションは暗号化されていないトークンを受け取ります。

原因と解決策:

tokenEncryptionKeyId は構成されていません — Microsoft Graphを使用してこのプロパティを明示的に設定する必要があります。証明書だけをアップロードするだけでは不十分です。
アプリ登録で証明書の有効期限が切れた - アプリ 登録にアップロードされた証明書の有効期限が切れていないことを確認します。必要に応じて、新しい証明書をアップロードします。
アクセストークンは暗号化されません 。トークン暗号化は ID トークン と SAML トークン にのみ適用されます。 Microsoft Entraからのアクセストークンは、証明書で暗号化されません。

トークンの暗号化解除とクライアント資格情報を比較する

トークン暗号化解除資格情報は、クライアント資格情報とは異なる目的で機能します。アプリケーションでは、両方に同じ証明書を使用することも、個別の証明書を使用することもできます。

次の例は、認証とトークンの暗号化解除の両方に同じKey Vault証明書を使用する構成を示しています。

{
  "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キー仕様を使用する必要があります。 KeySpec = Signatureで生成された証明書はクライアント資格情報で機能しますが、トークンの暗号化解除では失敗します。

ベストプラクティスに従う

トークンの暗号化解除を実装するときに、これらの推奨事項を適用します。

Azure Key Vaultを使用する - Key Vaultに暗号化解除証明書を格納して、一元管理、アクセス制御、監査ログを行います。

ローテーションを計画する — トークン暗号化をデプロイする前に、常にローテーション戦略を立てる。ローテーションウィンドウの間に、新しい証明書と古い証明書の両方を含めます。

RSA 2048 ビット以上のキーを使用 する - 適切なセキュリティのために、証明書で少なくとも 2048 ビットの RSA キーを使用していることを確認します。

Monitor 証明書の有効期限 — 証明書の有効期限が切れる前に通知するように、Azure Key Vaultまたは監視システムでアラートを設定します。

ステージング環境でテスト する - 運用環境で有効にする前に、非運用環境でトークンの暗号化と暗号化解除を確認します。

秘密キーをソース管理に格納しないでください — 証明書ストレージにKey Vault、環境変数、またはシークレットマネージャーを使用します。

ローテーション中に古い証明書を削除しすぎないでください 。キャッシュされたトークンの有効期限が切れるように、両方の証明書を少なくとも 24 時間アクティブにしてください。

暗号化解除証明書を構成せずにトークン暗号化を有効にしないでください 。暗号化を解除できない場合、アプリケーションはトークンの処理に失敗します。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-04-19

Microsoftでトークンの暗号化解除を構成します。Identity.Web

トークン暗号化のしくみ

トークン暗号化解除を構成するタイミングを決定する

前提条件を満たす

appsettings.json でトークン暗号化解除を構成する

基本的な構成を設定する

資格情報ソースを選択する

Key Vault (本番環境用に推奨)

証明書ストア (Windows)

ファイルパス

Base64 エンコード

複数の暗号化解除証明書を構成する

暗号化解除証明書をMicrosoft Entra IDに登録する

アプリケーションのトークン暗号化を有効にする

暗号化解除証明書をローテーションする

回転ステップ

ローテーション中の構成

トークンの暗号化解除のトラブルシューティング

トークンの暗号化解除の失敗

秘密キーがありません

アルゴリズムの不一致

暗号化されたトークンが発行されていない

トークンの暗号化解除とクライアント資格情報を比較する

ベスト プラクティスに従う

関連するコンテンツ

フィードバック

その他のリソース

ベストプラクティスに従う