Microsoft.Identity.Web で証明書を使用します。

Microsoft。Identity.Web では、機密クライアント アプリケーションのクライアント シークレットに代わるセキュリティで保護された代替手段として、証明書ベースの認証がサポートされています。 証明書では非対称暗号化が使用されるため、秘密キー所有者のみが認証できます。

この記事では、さまざまなソースから証明書の資格情報を構成し、アプリに登録して、運用環境で管理します。

証明書を使用する理由

どのように機能するのか

1. 秘密キーを使用して X.509 証明書を生成または取得します。
2. 証明書の public key (または拇印) をMicrosoft Entraアプリの登録に登録します。
3. 実行時に、Microsoft。Identity.Web は、構成されたソースから証明書 (秘密キーを含む) を読み込みます。
4. ライブラリは秘密キーを使用してクライアント アサーションに署名し、トークンを取得するためにMicrosoft Entra IDに送信します。

証明書のソース

Microsoft。Identity.Web では、複数のソースからの証明書の読み込みがサポートされています。

証明書資格情報は、ClientCertificates (またはAzureAd) 構成セクション内の AzureAdB2C 配列で構成します。 ローテーション シナリオでは、複数の証明書 (Microsoft) を指定できます。Identity.Web は、最初に検出された有効な証明書を使用します。

Azure Key Vaultから (推奨)

Azure Key Vaultは、運用環境の証明書に推奨されるソースです。 一元管理、アクセス制御、監査、自動ローテーション機能が提供されます。

コンフィギュレーション

証明書の構成を appsettings.jsonに追加します。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      }
    ]
  }
}

Key Vault アクセス ポリシーを設定する

アプリケーションの ID には、Key Vaultから証明書を読み取るアクセス許可が必要です。 これを付与する方法は、ボールト アクセス ポリシー モデルを使用するか、Azure ロールベースのアクセス制御 (RBAC) を使用するかによって決まります。

オプション 1: ボールト アクセス ポリシー

az keyvault set-policy \
  --name your-keyvault-name \
  --object-id <app-or-managed-identity-object-id> \
  --certificate-permissions get list \
  --secret-permissions get

オプション 2: AZURE RBAC

Key Vault Certificate User ロールをアプリケーションの ID に割り当てます。

az role assignment create \
  --role "Key Vault Certificate User" \
  --assignee <app-or-managed-identity-object-id> \
  --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<vault-name>

マネージド ID を使用してKey Vaultにアクセスする

アプリが Azure (App Service、Azure Functions、Azure Kubernetes Service、VM) で実行されている場合は、マネージド ID を使用してKey Vaultに対する認証を行います。 これにより、ボールトそのものにアクセスするための資格情報が必要なくなります。

システム割り当てマネージド ID

アプリでシステム割り当てマネージド ID が有効になっている場合は、Microsoft。Identity.Web は、DefaultAzureCredential を自動的に使用して、Key Vaultに対する認証を行います。 ClientCertificates エントリを超える追加の構成は必要ありません。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      }
    ]
  }
}

ユーザー割り当てマネージド ID

ユーザー割り当てマネージド ID の場合は、Key Vault証明書記述子で ManagedIdentityClientIdを指定します。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

証明書ストアから (Windowsのみ)

Windowsでは、Windows証明書ストアから証明書を読み込むことができます。 これは、オンプレミスまたは IIS でホストされる展開で一般的です。

拇印による認証

StoreWithThumbprintを使用して、SHA-1 拇印で証明書を識別します。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateThumbprint": "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2"
      }
    ]
  }
}

識別名

StoreWithDistinguishedNameを使用して、サブジェクト名で証明書を識別します。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateDistinguishedName": "CN=MyAppCertificate"
      }
    ]
  }
}

証明書ストアの場所

次の表に、一般的な証明書ストア パスと、それらにアクセスするために必要なアクセス許可を示します。

ファイル パスから

証明書は、ディスク上の .pfx (PKCS#12) ファイルから直接読み込むことができます。

コンフィギュレーション

証明書ファイルのパスとパスワードを appsettings.jsonに追加します。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "/path/to/certificate.pfx",
        "CertificatePassword": "your-certificate-password"
      }
    ]
  }
}

dotnet user-secrets set "AzureAd:ClientCertificates:0:CertificatePassword" "your-password"

export AzureAd__ClientCertificates__0__CertificatePassword="your-password"

Base64 でエンコードされた値から

証明書は Base64 でエンコードされた文字列として指定できます。 この方法は、環境変数、Kubernetes シークレット、または CI/CD パイプライン変数を使用して証明書を挿入する場合に便利です。

コンフィギュレーション

Base64 でエンコードされた証明書の値を appsettings.jsonに追加します。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCertificates": [
      {
        "SourceType": "Base64Encoded",
        "Base64EncodedValue": "MIIKcQIBAzCCCi0GCSqGSIb3DQEHAaCCCh4Egg..."
      }
    ]
  }
}

Base64 値を生成する

.pfx ファイルを Base64 文字列に変換します。

PowerShell:

$certBytes = [System.IO.File]::ReadAllBytes("path/to/certificate.pfx")
$base64 = [System.Convert]::ToBase64String($certBytes)
$base64 | Set-Clipboard  # Copies to clipboard

Bash：

base64 -w 0 path/to/certificate.pfx

Kubernetes シークレットでの使用

Base64 でエンコードされた証明書を Kubernetes シークレットに格納し、環境変数にマップします。

apiVersion: v1
kind: Secret
metadata:
  name: app-cert-secret
type: Opaque
data:
  AzureAd__ClientCertificates__0__Base64EncodedValue: <base64-encoded-pfx>

デプロイ内のシークレットを参照する。

env:
  - name: AzureAd__ClientCertificates__0__SourceType
    value: "Base64Encoded"
  - name: AzureAd__ClientCertificates__0__Base64EncodedValue
    valueFrom:
      secretKeyRef:
        name: app-cert-secret
        key: AzureAd__ClientCertificates__0__Base64EncodedValue

CI/CD パイプラインでの使用

Azure DevOpsまたはGitHub Actionsで、Base64 でエンコードされた証明書をシークレット変数として格納し、実行時に環境変数として設定します。

GitHub Actions例:

env:
  AzureAd__ClientCertificates__0__SourceType: "Base64Encoded"
  AzureAd__ClientCertificates__0__Base64EncodedValue: ${{ secrets.APP_CERTIFICATE_BASE64 }}

Azure DevOps例:

variables:
  AzureAd__ClientCertificates__0__SourceType: "Base64Encoded"
  AzureAd__ClientCertificates__0__Base64EncodedValue: $(AppCertificateBase64)

C# コードで証明書を構成する

JSON 構成に加えて、CredentialDescription の Microsoft.Identity.Abstractions クラスを使用して、証明書資格情報をプログラムで構成できます。

ヘルパー メソッド

CredentialDescription クラスは、証明書のソースの種類ごとに静的ヘルパー メソッドを提供します。

using Microsoft.Identity.Abstractions;

// From Azure Key Vault
var kvCredential = CredentialDescription.FromKeyVault(
    "https://your-keyvault-name.vault.azure.net",
    "your-certificate-name");

// From certificate store (by thumbprint)
var thumbprintCredential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    thumbprint: "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2");

// From certificate store (by distinguished name)
var dnCredential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    distinguishedName: "CN=MyAppCertificate");

// From file path
var pathCredential = CredentialDescription.FromCertificatePath(
    "/path/to/certificate.pfx",
    "your-certificate-password");

// From Base64-encoded string
var base64Credential = CredentialDescription.FromBase64String(
    "MIIKcQIBAzCCCi0GCSqGSIb3DQEHAaCCCh4Egg...");

ASP.NET Coreで使用する

認証を構成するときに、資格情報の説明を直接渡します。

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(options =>
    {
        options.Instance = "https://login.microsoftonline.com/";
        options.TenantId = "your-tenant-id";
        options.ClientId = "your-client-id";
        options.ClientCredentials = new[]
        {
            CredentialDescription.FromKeyVault(
                "https://your-keyvault-name.vault.azure.net",
                "your-certificate-name")
        };
    });

開発用の自己署名証明書を作成する

ローカルでの開発とテストでは、自己署名証明書を作成できます。 運用環境では自己署名証明書を使用しないでください。

PowerShell の使用 (Windows)

次のコマンドを実行して自己署名証明書を作成し、エクスポートし、拇印を表示します。

$cert = New-SelfSignedCertificate `
  -Subject "CN=MyDevCertificate" `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -KeyExportPolicy Exportable `
  -KeySpec Signature `
  -KeyLength 2048 `
  -KeyAlgorithm RSA `
  -HashAlgorithm SHA256 `
  -NotAfter (Get-Date).AddYears(2)

# Export the .pfx file (with private key)
$password = ConvertTo-SecureString -String "YourPassword123!" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath ".\MyDevCertificate.pfx" -Password $password

# Export the .cer file (public key only — for app registration)
Export-Certificate -Cert $cert -FilePath ".\MyDevCertificate.cer"

# Display the thumbprint
Write-Host "Thumbprint: $($cert.Thumbprint)"

OpenSSL (クロスプラットフォーム) の使用

次のコマンドを実行して証明書を生成し、 .pfx ファイルとしてパッケージ化し、拇印を表示します。

# Generate a self-signed certificate and private key
openssl req -x509 -newkey rsa:2048 \
  -keyout key.pem -out cert.pem \
  -days 730 -nodes \
  -subj "/CN=MyDevCertificate"

# Package into a .pfx file
openssl pkcs12 -export \
  -out MyDevCertificate.pfx \
  -inkey key.pem -in cert.pem \
  -passout pass:YourPassword123!

# Get the thumbprint
openssl x509 -in cert.pem -noout -fingerprint -sha1

.NET CLI の使用

開発用 HTTPS 証明書を .pfx ファイルとしてエクスポートします。

dotnet dev-certs https --export-path ./MyDevCertificate.pfx --password YourPassword123!

Microsoft Entra IDに証明書を登録する

証明書を作成または取得した後、その公開キーを Microsoft Entra ID のアプリ登録に登録する必要があります。

Azure ポータルの使用

1. Azure ポータルに移動し、Microsoft Entra ID>アプリの登録 に移動します。
2. アプリケーションを選択します。
3. 証明書とシークレット>Certificates>証明書のアップロードを選択します。
4. .cer含む.pemまたはファイルをアップロードします。 秘密キーを含む .pfx ファイルをアップロードしないでください。
5. アップロード後に表示される 拇印 の値に注意してください。構成に必要な場合があります。

Azure CLIの使用

az ad app credential reset \
  --id <application-client-id> \
  --cert @/path/to/certificate.pem \
  --append

--append フラグは、既存の資格情報を削除せずに証明書を追加します。

Microsoft Graph PowerShell の使用

$certData = [System.IO.File]::ReadAllBytes(".\MyDevCertificate.cer")
$base64Cert = [System.Convert]::ToBase64String($certData)

$keyCredential = @{
    type = "AsymmetricX509Cert"
    usage = "Verify"
    key = [System.Convert]::FromBase64String($base64Cert)
    displayName = "MyAppCertificate"
}

Update-MgApplication -ApplicationId <app-object-id> -KeyCredentials @($keyCredential)

証明書ローテーション

証明書のローテーションでは、期限切れの証明書が期限切れになる前に新しい証明書に置き換えられ、サービスが中断されないようにします。

戦略: 証明書の重複

推奨される方法では、重複する有効期間が使用されます。

1. 現在の証明書の有効期限が切れる前 (たとえば、30 ~ 60 日前) に新しい証明書を生成します。
2. 既存の証明書と共にMicrosoft Entraアプリの登録に新しい証明書を登録します。 Microsoft Entra IDは、登録されている証明書によって署名されたトークンを受け入れます。
3. 新しい証明書をアプリケーションの証明書ソース (Key Vault、証明書ストアなど) にデプロイします。
4. 新しい証明書をポイントするように構成を更新します (必要な場合)。
5. すべてのインスタンスが新しい証明書を使用することを確認した後、アプリの登録から古い証明書を削除します。

構成内の複数の証明書

Microsoft。Identity.Web では、複数の証明書の指定がサポートされています。 ライブラリはそれらを順番に試行し、最初の有効な証明書を使用します。

{
  "AzureAd": {
    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "new-cert-2026"
      },
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "current-cert-2025"
      }
    ]
  }
}

Azure Key Vaultを使用した自動回転

Azure Key Vaultでは、証明書の自動更新がサポートされます。 自動ローテーションを有効にする場合:

1. Key Vaultは、有効期限が切れる前に新しい証明書バージョンを生成します。
2. Microsoft。Identity.Web は、(次の証明書フェッチ時に) 最新バージョンを自動的に取得します。
3. 古い証明書のバージョンは、有効期限が切れるまで有効なままです。

Key Vaultで自動ローテーションを構成するには:

az keyvault certificate set-attributes \
  --vault-name your-keyvault-name \
  --name your-certificate-name \
  --policy @rotation-policy.json

証明書エラーのトラブルシューティングを行う

このセクションでは、一般的なエラー メッセージとその解決策を示します。

一般的なエラー

証明書が見つかりません

エラー メッセージ:

System.Security.Cryptography.CryptographicException: The certificate cannot be found.

考えられる原因と解決策:

Key Vaultへのアクセスが拒否されました

エラー メッセージ:

Azure.RequestFailedException: The user, group or application '...' does not have certificates get permission on key vault '...'

ソリューション

• アクセス ポリシーでgetとシークレットの両方アクセス許可が付与されていることを確認します。
• AZURE RBAC を使用する場合は、ID に Key Vault Certificate User ロールがあることを確認します。
• マネージド ID の場合は、ID が有効になっており、ポリシーで正しいオブジェクト ID が使用されていることを確認します。

証明書の秘密キーにアクセスできない

エラー メッセージ:

System.Security.Cryptography.CryptographicException: Keyset does not exist.

ソリューション

• Windows/IIS では、アプリケーション プール ID が秘密キーにread アクセスできることを確認します。 秘密 キーの管理を使用してアクセス権を付与するには、証明書 MMC スナップインを使用します。
• Linux では、 .pfx ファイルに適切なファイルアクセス許可 (chmod 600) があることを確認します。
• 証明書が秘密キー (Export-PfxCertificate または openssl pkcs12 -export) でエクスポートされていることを確認します。

証明書の有効期限が切れました

エラー メッセージ:

AADSTS700027: Client assertion contains an invalid signature. The key was expired.

ソリューション

• 証明書の有効期間 ( openssl x509 -in cert.pem -noout -dates) を確認します。
• 新しい証明書を生成し、アプリの登録とアプリケーションの構成の両方を更新します。
• 将来の有効期限の問題を防ぐために、証明書のローテーションを実装します。 「 証明書のローテーション」を参照してください。

証明書のパスワードが正しくありません

エラー メッセージ:

System.Security.Cryptography.CryptographicException: The specified network password is not correct.

ソリューション

• CertificatePasswordが、.pfx ファイルのエクスポート時に使用したパスワードと一致するかどうかを確認します。
• 環境変数を使用する場合は、エンコードの問題 (末尾の改行、特殊文字) を確認します。
• 既知のパスワードを使用して証明書を再エクスポートします。

診断チェックリスト

証明書認証が機能しない場合は、次のチェックリストを使用します。

• [ ] 証明書の有効性 — 証明書は有効期間内ですか? NotBeforeとNotAfterの日付を確認します。
• [ ] アプリの登録 — 証明書の公開キーは正しいアプリ登録にアップロードされていますか?
• [ ] 拇印の一致 — 構成の拇印はアプリ登録の証明書と一致しますか?
• [ ] 秘密キー アクセス — アプリケーション プロセスは証明書の秘密キーを読み取ることができますか?
• [ ] Key Vault アクセス許可 — Key Vault ソースの場合、ID には certificates/get と secrets/get アクセス許可の両方がありますか?
• [ ] 構成セクション — 正しいセクション (AzureAd または AzureAdB2C) の下の証明書の構成ですか?
• [ ] NuGet パッケージ — Microsoft.Identity.Webは最新ですか? 以前のバージョンでは、特定の証明書ソースの種類のサポートが不足している可能性があります。

ログ記録を有効にする

詳細な診断情報を取得するには、MSAL ログを有効にします。

builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

builder.Logging.AddFilter("Microsoft.Identity", LogLevel.Debug);

証明書の読み込み、クライアント アサーションの作成、トークンの取得に関するメッセージのログを確認します。

関連するコンテンツ

• 資格情報の概要
• 証明書レス認証 - マネージド ID とワークロード ID フェデレーション
• クライアント シークレット - 機密アプリの代替資格情報の種類
• トークンの暗号化解除 — トークンの暗号化 解除に証明書を使用する
• ログと診断