Microsoft.Identity.Web 的憑證概覽。

當你的應用程式使用 Microsoft 身分識別平台 認證時，會提供憑證來證明其身份。 Microsoft。Identity.Web 支援多種憑證類型，每種類型適合不同的環境與安全需求。

本文將協助你了解可用的憑證類型，選擇最適合你情境的類型，並在你的應用程式中設定憑證。

為什麼資格選擇很重要

應用程式所使用的憑證直接影響其安全態勢、營運負擔及部署彈性。 錯誤選擇的憑證可能會暴露機密、需要手動輪換，或限制應用程式執行的地點。

Microsoft。Identity.Web 提供統一的配置模型，讓您能夠：

• 指定多個憑證並自動備援。
• 在不修改應用程式代碼的情況下更改憑證類型。
• 根據環境（開發、預備、生產）使用不同的憑證。

支援的憑證類型

Microsoft。Identity.Web 支援三種機密客戶端應用程式的憑證類型：

無需證書的認證（聯邦身份憑證 + 管理式身份）

無憑證憑證結合 Azure 管理身份與聯邦身份憑證（FIC）來驗證您的應用程式，無需管理任何秘密或憑證。 Azure 完全負責憑證生命週期。

運作方式： 你的應用程式使用其管理身份取得一個憑證，Microsoft 身分識別平台透過預先設定的聯邦信任接受此憑證作為應用程式身份的證明。

最佳用途： 生產工作負載運行於 Azure。

了解更多關於無憑證認證的資訊

憑證

憑證提供強而有力且非對稱的基於金鑰的驗證。 你的應用程式透過簽署憑證私鑰的聲明來證明其身份。 Microsoft。Identity.Web 可從多個來源載入憑證：

• Azure Key Vault - 集中式、受管理的憑證儲存，並具備存取政策。
• 憑證儲存庫 - Windows憑證儲存庫（CurrentUser 或 LocalMachine）。
• 檔案路徑 - 磁碟上的憑證檔案（.pfx 格式）。
• Base64-encoded - 憑證直接嵌入設定中。

最佳用途： 適用於無法使用無證書憑證的生產工作負載或混合環境。

了解更多關於證書資格的資訊

用戶端密碼

用戶端秘密是你的應用程式呈現給 Microsoft 身分識別平台 的共享字串。 它們是最簡單設定的憑證類型，但安全性卻最弱。

最佳用途： 僅限於本地開發與測試。

了解更多關於客戶秘密的資訊

選擇合適的證照類型

請使用以下決策樹來判斷哪種憑證類型最適合你的情境。

Is your application running on Azure?
├── Yes
│   ├── Can you use Managed Identity?
│   │   ├── Yes → Use certificateless credentials (recommended)
│   │   └── No → Use certificates from Azure Key Vault
└── No
    ├── Is this a production environment?
    │   ├── Yes → Use certificates (Key Vault, Certificate Store, or file path)
    │   └── No → Use client secrets for development/testing

一般方針

選擇資格類型時請遵循以下原則：

• 在應用程式執行 Azure 時，永遠偏好無憑證憑證。 他們完全取消了資格管理。
• 當沒有無憑證憑證時，請使用憑證。 盡可能將它們存放在 Azure Key Vault。
• 將用戶端密鑰限制在開發環境中使用。 千萬不要在生產部署中使用客戶端秘密。

比較不同證照類型

下表總結了憑證類型之間的主要差異：

在 appsettings.json 中設定憑證

Microsoft。Identity.Web 在你的設定中使用 ClientCredentials 陣列來指定一個或多個憑證。 陣列中的每個項目都包含 SourceType 一個屬性，指示憑證的來源。

組態結構

以下範例展示了單一無憑證憑證的最小配置：

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

    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

SourceType 值

SourceType 屬性對應於 CredentialSource 列舉，並決定了 Microsoft.Identity.Web 如何載入憑證：

依類型分類的憑證範例

以下範例展示了如何在 appsettings.json 中配置每種憑證類型，若有可用，也可在 C# 程式碼中。

無憑證（受管理的身份）

透過指定用戶端 ID 來使用使用者指定的管理身份：

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

對於系統指派的管理身份，省略以下 ManagedIdentityClientId 屬性：

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity"
      }
    ]
  }
}

Azure 金鑰保存庫的憑證

透過指定保險庫網址和憑證名稱，載入儲存在Azure Key Vault中的憑證：

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

你也可以使用 CredentialDescription C# 中的輔助方法：

var credential = CredentialDescription.FromKeyVault(
    "https://your-keyvault.vault.azure.net",
    "your-certificate-name");

憑證庫的憑證

從 Windows 憑證儲存庫透過拇指指紋載入憑證：

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateThumbprint": "ABC123DEF456...",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

您也可以使用特殊名稱，這樣可以簡化證書輪替，因為新證書會自動選擇：

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateDistinguishedName": "CN=YourAppCertificate",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

在 C# 中，使用輔助工具方法：

// By thumbprint
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    thumbprint: "ABC123DEF456...");

// By distinguished name (recommended for rotation)
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    distinguishedName: "CN=YourAppCertificate");

從檔案路徑取得憑證

從 .pfx 磁碟上的檔案載入憑證：

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "/var/certs/app-cert.pfx",
        "CertificatePassword": "certificate-password"
      }
    ]
  }
}

Base64 編碼憑證

將憑證直接嵌入設定中，以 Base64 編碼的字串形式：

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Base64Encoded",
        "Base64EncodedValue": "MIIKcQIBAzCCCi0..."
      }
    ]
  }
}

客戶端密碼

指定一個開發與測試用的客戶端秘密字串：

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

使用多重憑證並備用備援

你可以在陣列中指定多個憑證 ClientCredentials 。 Microsoft。Identity.Web 會依序嘗試每個憑證，若目前的憑證失敗，則回退到下一個憑證。 此模式對於在多個環境中執行的應用程式非常有用。

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "your-managed-identity-client-id"
      },
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      },
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "development-only-secret"
      }
    ]
  }
}

在此範例中：

1. 應用程式首先嘗試無憑證驗證，使用管理身份（可在 Azure 上運作）。
2. 如果管理身份無法使用，則會回退到 金鑰保存庫 的憑證。
3. 最後手段是使用用戶端秘密（用於本地開發）。

這種方法讓你能在不同環境中使用相同的設定檔，而無需修改程式碼。

在程式碼中設定憑證

你也可以以程式方式配置憑證，在 Program.cs 或 Startup.cs：

using Microsoft.Identity.Web;

builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("MyApi", builder.Configuration.GetSection("MyApi"))
    .AddDistributedTokenCaches();

// Or configure credentials programmatically
builder.Services.Configure<MicrosoftIdentityOptions>(options =>
{
    options.ClientCredentials = new[]
    {
        new CredentialDescription
        {
            SourceType = CredentialSource.SignedAssertionFromManagedIdentity,
            ManagedIdentityClientId = "your-managed-identity-client-id"
        }
    };
});

令牌解密憑證

除了客戶憑證用於認證之外，還有 Microsoft。Identity.Web 也支援用於令牌解密的憑證。 當你的應用程式收到加密令牌並需要解密時，使用令牌解密憑證。

令牌解密憑證使用與用戶端憑證相同的 SourceType 值與設定模式，但會在陣 TokenDecryptionCredentials 列中指定：

{
  "AzureAd": {
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "token-decryption-cert"
      }
    ]
  }
}

了解更多關於令牌解密的資訊

最佳做法

在為您的應用程式設定憑證時，請牢記以下建議：

在生產環境中，應優先使用無證書憑證。 它們消除了秘密暴露的風險，並消除了與輪替相關的額外負擔。 只要你的應用程式在支援管理身份的 Azure 運算資源上執行時，就使用它們。

使用憑證備援以提升可攜性。 依優先順序配置多個憑證，讓你的應用程式能在開發、暫存和生產環境間運作，且不需更改程式碼。

絕不要在生產環境中使用客戶端秘密。 用戶端秘密可能透過日誌、設定檔或原始碼控制洩漏。 改用憑證或無證書憑證。

將敏感值儲存在設定檔之外。 使用 Azure Key Vault、environment variables，或 ASP.NET Core Secret Manager 來管理憑證密碼和用戶端秘密。 不要將敏感值交給原始碼控制。

在證書過期前輪換。 監控證書到期日並建立輪調流程。 Azure Key Vault 可以自動化憑證更新。

使用 Azure Key Vault 來儲存憑證。 金鑰保存庫 提供集中管理、存取政策、稽核記錄及憑證自動輪替功能。

相關內容

• 無憑證認證
• 證書資格
• 令牌解密
• 用戶端秘密