適用于 .NET 的應用程式驗證用戶端程式庫 - 1.6.0 版

發行項
04/03/2023

注意

Microsoft.Azure.Services.AppAuthentication 已淘汰，不再支援或維護。它會由適用于 .NET、JAVA、TypeScript 和 Python 的 Azure 身分識別用戶端程式庫 取代。如需如何移轉至 Azure Identity 的資訊，請參閱這裡： AppAuthentication 至 Azure.Identity 移轉指導。

若要使用服務主體向 Azure 服務進行驗證，您需要 Azure Active Directory (Azure AD) 認證、共用秘密或憑證。

管理這類認證可能很困難。將認證包含在來源或組態檔中，以將認證組合至應用程式。 .NET 程式庫的 Microsoft.Azure.Services.AppAuthentication 可簡化此問題。它會使用開發人員的認證，在本機開發期間進行驗證。當解決方案在稍後部署至 Azure 時，程式庫會自動切換至應用程式認證。在本機開發期間使用開發人員認證更為安全，因為您不需要建立 Azure AD 認證或在開發人員之間共用認證。

連結 Microsoft.Azure.Services.AppAuthentication 庫會自動管理驗證，這可讓您專注于您的解決方案，而不是您的認證。它支援使用 Microsoft Visual Studio、Azure CLI 或 Azure AD 整合式驗證進行本機開發。如果部署到支援受控執行個體的 Azure 資源，程式庫會自動使用 Azure 資源的受控識別。不需要任何程式碼或設定變更。程式庫也支援在無法使用受控識別時直接使用 Azure AD 用戶端認證，或在本機開發期間無法判斷開發人員的安全性內容時。

| 原始程式碼套件 (nuget) | Azure Active Directory 檔

必要條件

Visual Studio 2019 或 Visual Studio 2017 v15.5。
Visual Studio 的應用程式驗證擴充功能，可作為 Visual Studio 2017 Update 5 的個別擴充功能，並隨附于 Update 6 和更新版本中的產品。使用 Update 6 或更新版本，您可以從 Visual Studio 安裝程式內選取 [Azure 開發工具] 來確認應用程式驗證延伸模組的安裝。

使用程式庫

對於 .NET 應用程式，使用受控識別最簡單的方式是透過 Microsoft.Azure.Services.AppAuthentication 套件。如何開始使用：

選取[工具>NuGet 套件管理員>管理方案的 NuGet 套件]，將Microsoft.Azure.Services.AppAuthentication和Microsoft.Azure.KeyVault NuGet 套件的參考新增至您的專案。

使用 AzureServiceTokenProvider 簡化 Azure 用戶端的要求存取權杖，如下列範例所示：

using Microsoft.Azure.Services.AppAuthentication;
using Microsoft.Azure.KeyVault;
using System.Data.SqlClient

// Use AzureServiceTokenProvider’s built-in callback for KeyVaultClient
var azureServiceTokenProvider = new AzureServiceTokenProvider();
var kv = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));

// Request an access token for SqlConnection
sqlConnection = new SqlConnection(YourConnectionString)) 
{ 
    sqlConnection.AccessToken = await azureServiceTokenProvider.GetAccessTokenAsync("https://database.windows.net"); 
    sqlConnection.Open(); 
}

安全線程 AzureServiceTokenProvider 類別會快取記憶體中的權杖，並在到期前從 Azure AD 擷取權杖。這表示您一律不需要在呼叫 GetAccessTokenAsync 方法之前檢查權杖的到期日。

GetAccessTokenAsync 方法需要資源識別碼。若要深入瞭解 Microsoft Azure 服務，請參閱什麼是適用于 Azure 資源的受控識別。

本機開發驗證

針對本機開發，有兩個主要驗證案例：向 Azure 服務進行驗證，以及向自訂服務進行驗證。

向 Azure 服務驗證

本機電腦不支援 Azure 資源的受控識別。因此，Microsoft.Azure.Services.AppAuthentication 程式庫會使用您的開發人員認證，以在本機開發環境中執行。當解決方案部署至 Azure 時，程式庫會使用受控識別切換至 OAuth 2.0 用戶端的認證授與流程。這種方法表示您可以在本機和遠端測試相同的程式碼，而不必擔心。

針對本機開發，AzureServiceTokenProvider 會使用 Visual Studio、Azure 命令列介面 (CLI)，或 Azure AD 整合式驗證來擷取權杖。會依序嘗試每個選項，而程式庫會使用第一個成功的選項。如果沒有選項可用，AzureServiceTokenProviderException 會擲回包含詳細資訊的例外狀況。

使用 Visual Studio 進行驗證

若要使用 Visual Studio 進行驗證：

登入 Visual Studio 並使用[工具> 選項] 開啟[選項]。
選取 [Azure 服務驗證]，選擇用於本機開發的帳戶，然後選取 [ 確定]。

如果您使用 Visual Studio 遇到問題，例如涉及權杖提供者檔案的錯誤，請仔細檢閱上述步驟。

您可能需要重新驗證開發人員權杖。若要這樣做，請選取[工具>選項]，然後選取 [Azure 服務驗證]。在選取的帳戶下尋找 [重新驗證 ] 連結。選取該項目並進行驗證。

使用 Azure CLI 進行驗證

若要使用 Azure CLI 進行本機開發，請確定您有 Azure CLI v2.0.12 版或更新版本。

若要使用 Azure CLI：

在 Windows 工作列中搜尋 Azure CLI 以開啟 Microsoft Azure 命令提示字元。
登入Azure 入口網站：az login以登入 Azure。
輸入az account get-access-token --resource https://vault.azure.net來驗證存取權。如果您收到錯誤，請檢查是否已正確安裝正確的 Azure CLI 版本。

如果未將 Azure CLI 安裝至預設目錄，您可能會收到錯誤報表，指出 AzureServiceTokenProvider 找不到 Azure CLI 的路徑。使用 AzureCLIPath 環境變數來定義 Azure CLI 安裝資料夾。必要時，AzureServiceTokenProvider 會將 AzureCLIPath 環境變數中指定的目錄新增至路徑環境變數。
如果您使用多個帳戶登入 Azure CLI，或您的帳戶可以存取多個訂用帳戶，您必須指定要使用的訂用帳戶。輸入 az account set --subscription 命令。

此命令只會在失敗時產生輸出。若要確認目前的帳戶設定，請輸入命令 az account list 。

使用 Azure AD 驗證進行驗證

若要使用 Azure AD 驗證，請確認下列事項：

您的內部部署的 Active Directory同步處理至 Azure AD。如需詳細資訊，請參閱什麼是 Azure Active Directory 的混合式身分識別？。
您的程式碼正在加入網域的電腦上執行。

向自訂服務驗證

當服務呼叫 Azure 服務時，上述步驟即會開始作用，因為 Azure 服務允許存取使用者和應用程式。

建立會呼叫自訂服務的服務時，請在本機開發驗證上使用 Azure AD 用戶端認證。有兩個選項：

使用服務主體登入 Azure：
1. 建立服務主體。如需詳細資訊，請參閱使用 Azure CLI 建立 Azure 服務主體。
2. 使用 Azure CLI 使用下列命令登入：
```
az login --service-principal -u <principal-id> --password <password> --tenant <tenant-id> --allow-no-subscriptions
```
  因為服務主體可能無法存取訂用帳戶，所以使用 --allow-no-subscriptions 引數。
使用環境變數來指定服務主體詳細資料。如需詳細資訊，請參閱使用服務主體執行應用程式。

登入 Azure 之後， AzureServiceTokenProvider 請使用服務主體來擷取用於本機開發的權杖。

此方法僅適用于本機開發。當您將解決方案部署至 Azure 時，程式庫會切換為以受控識別進行驗證。

使用受控識別或使用者指派的身分識別執行應用程式

當您在 Azure App Service 或啟用受控識別的 Azure VM 上執行程式碼時，程式庫會自動使用受控識別。不需要變更程式碼，但受控識別必須具有其嘗試存取之資源的許可權。例如，受控識別需要存取原則，才能存取金鑰保存庫中的任何秘密。

或者，您可以使用使用者指派的身分識別進行驗證。如需使用者指派身分識別的詳細資訊，請參閱關於 Azure 資源的受控識別。若要使用使用者指派的身分識別進行驗證，您必須在連接字串中指定使用者指派身分識別的用戶端識別碼。連接字串是在連接字串支援中指定。

使用服務主體執行應用程式

這可能需要建立 Azure AD 用戶端認證，才可進行驗證。這種情況可能發生在下列範例中：

您的程式碼在本機開發環境中執行，但不是在開發人員的身分識別下執行。例如，Service Fabric 在本機開發上使用 NetworkService 帳戶。
您的程式碼在本機開發環境中執行，而且向自訂服務進行驗證，因此您無法使用您的開發人員身分識別。
您的程式碼是在尚未支援 Azure 資源的受控識別的 Azure 計算資源上執行，例如Azure Batch。

使用服務主體執行應用程式的主要方法有三種。若要使用其中任何一項，您必須先建立服務主體。如需詳細資訊，請參閱使用 Azure CLI 建立 Azure 服務主體。

使用本機密鑰存放區中的憑證來登入 Azure AD

使用 Azure CLI az ad sp create-for-rbac 命令建立服務主體憑證。
```
az ad sp create-for-rbac --create-cert
```
此命令會建立 .pem 檔案 (儲存在主目錄中的私密金鑰) 。使用命令將 .pem 檔案轉換為 PFX 憑證：
```
openssl pkcs12 -export -in test.pem -out test.pfx
```
將名為 AzureServicesAuthConnectionString 的環境變數設定為下列值：
```
RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};
      CertificateStoreLocation={CertificateStore}
```
使用步驟 1 產生的值取代 {AppId}、{TenantId} 和 {Thumbprint}。根據您的部署計畫，將 {CertificateStore} 取代為 LocalMachine' 或 CurrentUser。
執行應用程式。

使用共用秘密認證登入 Azure AD

使用 Azure CLI az ad sp create-for-rbac 命令搭配 --sdk-auth 參數建立具有密碼的服務主體憑證。
```
az ad sp create-for-rbac --sdk-auth
```
將名為 AzureServicesAuthConnectionString 的環境變數設定為下列值：
```
RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}
```
使用步驟 1 產生的值取代 {AppId}、{TenantId}和 {ClientSecret}。
執行應用程式。

當所有項目都正確地設定之後，便不必再變更任何程式碼。 AzureServiceTokenProvider 會使用環境變數和憑證來向 Azure AD 進行驗證。

使用金鑰保存庫中的憑證登入 Azure AD

此選項可讓您將服務主體的用戶端憑證儲存在金鑰保存庫中，並將其用於服務主體驗證。您可以針對下列案例使用此選項：

本機驗證，您想要使用明確的服務主體進行驗證，並想要在金鑰保存庫中安全地保留服務主體認證。開發人員帳戶必須能夠存取金鑰保存庫。
您想要使用明確認證的 Azure 驗證，並想要在金鑰保存庫中安全地保留服務主體認證。您可以針對跨租使用者案例使用此選項。受控識別必須能夠存取金鑰保存庫。

受控識別或開發人員身分識別必須具有從金鑰保存庫擷取用戶端憑證的許可權。 AppAuthentication 程式庫會使用擷取的憑證作為服務主體的用戶端認證。

若要使用用戶端憑證進行服務主體驗證：

建立服務主體憑證，並將其自動儲存在您的金鑰保存庫中。使用 Azure CLI az ad sp create-for-rbac --keyvault keyvaultname < --cert < certificatename >> --create-cert --skip-assignment命令：
```
az ad sp create-for-rbac --keyvault <keyvaultname> --cert <certificatename> --create-cert --skip-assignment
```
憑證識別碼會是格式的 URL https://<keyvaultname>.vault.azure.net/secrets/<certificatename>

將此連接字串中的取代 {KeyVaultCertificateSecretIdentifier} 為憑證識別碼：

RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}

例如，如果您的金鑰保存庫稱為 myKeyVault ，而且您已建立名為 myCert的憑證，則憑證識別碼會是：

RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier=https://myKeyVault.vault.azure.net/secrets/myCert

連接字串支援

根據預設， AzureServiceTokenProvider 會嘗試下列驗證方法，以擷取權杖：

若要控制處理程序，請使用傳遞至 AzureServiceTokenProvider 建構函式或 AzureServicesAuthConnectionString 環境變數中指定的連接字串。支援下列選項：

連接字串選項	案例	註解
`RunAs=Developer;DeveloperTool=AzureCli`	本機開發	`AzureServiceTokenProvider` 會使用 AzureCli 來取得權杖。
`RunAs=Developer;DeveloperTool=VisualStudio`	本機開發	`AzureServiceTokenProvider` 會使用 Visual Studio 來取得權杖。
`RunAs=CurrentUser`	本機開發	.NET Core 不支援。 `AzureServiceTokenProvider` 會使用 Azure AD 整合式驗證來取得權杖。
`RunAs=App`	適用於 Azure 資源的受控識別	`AzureServiceTokenProvider` 會使用受控識別來取得權杖。
`RunAs=App;AppId={ClientId of user-assigned identity}`	Azure 資源的使用者指派身分識別	`AzureServiceTokenProvider` 會使用使用者指派的身分識別來取得權杖。
`RunAs=App;AppId={TestAppId};KeyVaultCertificateSecretIdentifier={KeyVaultCertificateSecretIdentifier}`	自訂服務驗證	`KeyVaultCertificateSecretIdentifier` 是憑證的秘密識別碼。
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateThumbprint={Thumbprint};CertificateStoreLocation={LocalMachine or CurrentUser}`	服務主體	`AzureServiceTokenProvider` 會使用憑證從 Azure AD 取得權杖。
`RunAs=App;AppId={AppId};TenantId={TenantId};CertificateSubjectName={Subject};CertificateStoreLocation={LocalMachine or CurrentUser}`	服務主體	`AzureServiceTokenProvider` 會使用憑證從 Azure AD 取得權杖
`RunAs=App;AppId={AppId};TenantId={TenantId};AppKey={ClientSecret}`	服務主體	`AzureServiceTokenProvider` 會使用密碼從 Azure AD 取得權杖。

範例

若要查看作用中的連結 Microsoft.Azure.Services.AppAuthentication 庫，請參閱下列程式碼範例。

AppAuthentication 疑難排解

本機開發期間的常見問題

未安裝 Azure CLI、未登入，或沒有最新版本

執行 az account get-access-token 以查看 Azure CLI 是否為您顯示權杖。如果找不到 這類程式，請安裝最新版的 Azure CLI。系統會提示您登入。

AzureServiceTokenProvider 找不到 Azure CLI 的路徑

AzureServiceTokenProvider 會在其預設安裝位置尋找 Azure CLI。如果找不到 Azure CLI，請將環境變數 AzureCLIPath 設定為 Azure CLI 安裝資料夾。 AzureServiceTokenProvider 會將環境變數新增至 Path 環境變數。

您已使用多個帳戶登入 Azure CLI、相同的帳戶可以存取多個租使用者中的訂用帳戶，或在本機開發期間嘗試進行呼叫時收到拒絕存取錯誤

使用 Azure CLI，將預設訂用帳戶設定為具有您要使用的帳戶。訂用帳戶必須與您想要存取的資源位於相同的租使用者中： az account set --subscription [subscription-id]。如果沒有看到任何輸出，就會成功。使用 az account list確認正確的帳戶現在是預設值。

跨環境的常見問題

未經授權的存取、拒絕存取、禁止或類似的錯誤

使用的主體無法存取其嘗試存取的資源。將資源的使用者帳戶或App Service MSI 的「參與者」存取權授與您的使用者帳戶。這取決於您是在本機電腦上執行範例，還是部署在 Azure 中至您的App Service。某些資源，例如金鑰保存庫，也有自己的存取原則，可讓您使用授與主體的存取權，例如使用者、應用程式和群組。

部署至 Azure App 服務時的常見問題

未在App Service上設定受控識別

使用 Kudu 偵錯主控台檢查環境變數MSI_ENDPOINT且MSI_SECRET存在。如果這些環境變數不存在，則不會在App Service上啟用受控識別。

使用 IIS 在本機部署時的常見問題

在 IIS 中偵錯應用程式時無法擷取權杖

根據預設，AppAuth 會在 IIS 的不同使用者內容中執行。這就是為什麼它無法存取您的開發人員身分識別來擷取存取權杖的原因。您可以使用下列兩個步驟，將 IIS 設定為使用使用者內容執行：

設定 Web 應用程式的應用程式集區，以作為您目前的使用者帳戶執行。請在這裡參閱詳細資訊
將「setProfileEnvironment」設定為「True」。請參閱這裡的詳細資訊。
- 移至 %windir%\System32\inetsrv\config\applicationHost.config
- 搜尋「setProfileEnvironment」。如果設定為「False」，請將它變更為「True」。如果不存在，請將它新增為 processModel 元素的屬性， (/configuration/system.applicationHost/applicationPools/applicationPoolDefaults/processModel/@setProfileEnvironment) ，並將它設定為「True」。
深入了解 Azure 資源的受控識別。
深入了解 Azure AD 驗證案例。

適用于 .NET 的應用程式驗證用戶端程式庫 - 1.6.0 版

必要條件

使用程式庫

本機開發驗證

向 Azure 服務驗證

使用 Visual Studio 進行驗證

使用 Azure CLI 進行驗證

使用 Azure AD 驗證進行驗證

向自訂服務驗證

使用受控識別或使用者指派的身分識別執行應用程式

使用服務主體執行應用程式

使用本機密鑰存放區中的憑證來登入 Azure AD

使用共用秘密認證登入 Azure AD

使用金鑰保存庫中的憑證登入 Azure AD

連接字串支援

範例

AppAuthentication 疑難排解

本機開發期間的常見問題

未安裝 Azure CLI、未登入，或沒有最新版本

AzureServiceTokenProvider 找不到 Azure CLI 的路徑

您已使用多個帳戶登入 Azure CLI、相同的帳戶可以存取多個租使用者中的訂用帳戶，或在本機開發期間嘗試進行呼叫時收到拒絕存取錯誤

跨環境的常見問題

未經授權的存取、拒絕存取、禁止或類似的錯誤

部署至 Azure App 服務時的常見問題

未在App Service上設定受控識別

使用 IIS 在本機部署時的常見問題

在 IIS 中偵錯應用程式時無法擷取權杖

意見反應

其他資源

適用于 .NET 的應用程式驗證用戶端程式庫 - 1.6.0 版

必要條件

使用程式庫

本機開發驗證

向 Azure 服務驗證

使用 Visual Studio 進行驗證

使用 Azure CLI 進行驗證

使用 Azure AD 驗證進行驗證

向自訂服務驗證

使用受控識別或使用者指派的身分識別執行應用程式

使用服務主體執行應用程式

使用本機密鑰存放區中的憑證來登入 Azure AD

使用共用秘密認證登入 Azure AD

使用 金鑰保存庫 中的憑證登入 Azure AD

連接字串支援

範例

AppAuthentication 疑難排解

本機開發期間的常見問題

未安裝 Azure CLI、未登入，或沒有最新版本

AzureServiceTokenProvider 找不到 Azure CLI 的路徑

您已使用多個帳戶登入 Azure CLI、相同的帳戶可以存取多個租使用者中的訂用帳戶，或在本機開發期間嘗試進行呼叫時收到拒絕存取錯誤

跨環境的常見問題

未經授權的存取、拒絕存取、禁止或類似的錯誤

部署至 Azure App 服務 時的常見問題

未在App Service上設定受控識別

使用 IIS 在本機部署時的常見問題

在 IIS 中偵錯應用程式時無法擷取權杖

意見反應

其他資源

使用金鑰保存庫中的憑證登入 Azure AD

部署至 Azure App 服務時的常見問題