使用 .NET 的 Azure AI 服務驗證和授權

發行項
07/15/2024

必須驗證對 Azure AI 服務的應用程式要求。在本文中，您會探索使用 .NET 向 Azure OpenAI 和其他 AI 服務驗證的選項。這些概念適用語意核心 SDK，以及來自 Azure OpenAI 等特定服務的 SDK。大部分的 AI 服務提供兩種驗證應用程式和使用者的主要方式：

金鑰型驗證使用袐密金鑰值來存取 Azure 服務。這些袐密值有時稱為 API 金鑰或存取金鑰，視服務而定。
Microsoft Entra ID 提供完整的身分識別和存取管理解決方案，以確保正確的身分識別具有不同 Azure 資源的正確存取層級。

前面的各節提供這兩種方法的概念性概觀，而不是詳細的實作步驟。如需連線到 Azure 服務的詳細資訊，請瀏覽下列資源：

注意

本文中的範例主要著重於與 Azure OpenAI 的連線，但相同的概念和實作步驟也直接適用許多其他 Azure AI 服務。

使用金鑰進行驗證

存取金鑰可讓應用程式和工具使用服務提供的袐密金鑰向 Azure AI 服務 (例如 Azure OpenAI) 進行驗證。使用 Azure 入口網站或 Azure CLI 之類的工具來擷取袐密金鑰，並用它來設定應用程式程式碼以連線到 AI 服務：

builder.Services.AddAzureOpenAIChatCompletion(
    "deployment-model",
    "service-endpoint",
    "service-key"); // Secret key
var kernel = builder.Build();

使用金鑰是一個簡單的選項，但應該謹慎使用此方法。金鑰不是建議的驗證選項，因為它們：

並未遵循最低權限原則，無論使用者是誰或用於什麼工作，它們都會提供提升的權限。
不小心簽入原始檔控制或儲存在不安全的位置。
可以輕鬆地共用或傳送給不應該有存取權的各方。
通常需要手動管理和輪替。

相反地，請考慮使用 Microsoft Entra ID 進行驗證，這是大多數案例的建議解決方案。

使用 Microsoft Entra ID 進行驗證

Microsoft Entra ID 是雲端式身分識別和存取管理服務，可為不同的商務和應用程式案例提供大量的功能。 Microsoft Entra ID 是連線到 Azure OpenAI 和其他 AI 服務的建議解決方案，並提供下列優點：

使用身分識別的無金鑰驗證。
角色型存取控制 (RBAC) 用來指派身分識別所需的最低權限。
可以使用 Azure.Identity 用戶端程式庫來偵測不同環境的不同認證，而不需要變更程式碼。
自動處理系統管理維護工作，例如輪替基礎金鑰。

在您的應用程式中實作 Microsoft Entra 驗證的工作流程通常包含下列項目：

本機開發：
1. 使用 Azure CLI 或 Visual Studio 等本機開發工具登入 Azure。
2. 將您的程式碼設定為使用 Azure.Identity 用戶端程式庫和 DefaultAzureCredential 類別。
3. 為您用來登入的帳戶指派 Azure 角色，以啟用 AI 服務的存取權。
Azure 託管的應用程式：
1. 將應用程式設定為使用 Azure.Identity 用戶端程式庫進行驗證之後，將應用程式部署至 Azure。
2. 為 Azure 託管的應用程式指派受控識別。
3. 為該受控識別指派 Azure 角色，以啟用 AI 服務的存取權。

下列各節中會探索此工作流程的重要概念。

在本機向 Azure 驗證

在本機開發連線至 Azure AI 服務的應用程式時，請使用 Visual Studio 或 Azure CLI 之類的工具向 Azure 進行驗證。 Azure.Identity 用戶端程式庫可以探索您的本機認證，並用來向 Azure 服務驗證您的應用程式，如設定應用程式程式碼一節所述。

例如，若要使用 Azure CLI 在本機向 Azure 驗證，請執行下列命令：

az login

設定應用程式程式碼

使用來自 Azure SDK 的 Azure.Identity 用戶端程式庫，在您的程式碼中實作 Microsoft Entra 驗證。 Azure.Identity 程式庫包含 DefaultAzureCredential 類別，其會根據目前環境和可用的工具自動探索可用的 Azure 認證。瀏覽 Azure SDK for .NET 文件，以取得一組完整的支援環境認證，以及其搜尋順序。

例如，使用下列程式碼使用 DefaultAzureCredential 來設定語意核心進行驗證：

Kernel kernel = Kernel
    .CreateBuilder()
    .AddAzureOpenAITextGeneration(
        "your-model",
        "your-endpoint",
        new DefaultAzureCredential())
    .Build();

DefaultAzureCredential 可讓應用程式從本機開發升級至生產環境，而不需要變更程式碼。例如，在開發期間，DefaultAzureCredential 會使用來自 Visual Studio 或 Azure CLI 的本機使用者認證向 AI 服務進行驗證。將應用程式部署至 Azure 時，DefaultAzureCredential 會使用指派給應用程式的受控識別。

將角色指派給您的身分識別

Azure 角色型存取控制 (Azure RBAC) 是一個系統，可提供 Azure 資源更細微的存取管理。將角色指派給 DefaultAzureCredential 用來連線到 Azure AI 服務的安全性主體，無論是個別使用者、群組、服務主體或受控識別。 Azure 角色是權限集合，可讓身分識別執行各種工作，例如產生完成或建立和刪除資源。

使用 Azure CLI、Bicep 或 Azure 入口網站等工具，將認知服務 OpenAI 使用者 (角色識別碼：5e0bd9bd-7b93-4f28-af87-19fc36ad61bd) 等角色指派給相關的身分識別。例如，使用 az role assignment create 命令來使用 Azure CLI 指派角色：

az role assignment create \
        --role "5e0bd9bd-7b93-4f28-af87-19fc36ad61bd" \
        --assignee-object-id "$PRINCIPAL_ID" \
        --scope /subscriptions/"$SUBSCRIPTION_ID"/resourceGroups/"$RESOURCE_GROUP" \
        --assignee-principal-type User

使用下列資源深入了解 Azure RBAC：

將受控識別指派給應用程式

在大部分情況下，Azure 託管的應用程式應該使用受控識別來連線到 Azure OpenAI 等其他服務。受控識別會在 Microsoft Entra ID 中提供完全受控識別，讓應用程式在連線到支援 Microsoft Entra 驗證的資源時使用。 DefaultAzureCredential 會探索與您的應用程式相關聯的身分識別，並用它來向其他 Azure 服務進行驗證。

您可以指定給應用程式的受控識別有兩個類型：

系統指派的身分識別會繫結至您的應用程式，如果您的應用程式已刪除，則會被刪除。應用程式只能有一個系統指派的身分識別。
使用者指派的身分識別是一項獨立 Azure 資源，可指派給您的應用程式。應用程式可以有多個使用者指派的身分識別。

將角色指派給受控識別，就像是處理個別使用者帳戶，例如認知服務 OpenAI 使用者角色。深入了解使用下列資源來處理受控識別：

共用方式為