共用方式為

使用身分識別將您的應用程式連線到 Azure AI 搜尋

  • 發行項

在應用程式程式碼中，您可以設定與 Azure AI 搜尋服務的無金鑰連線，該連線使用 Microsoft Entra ID 和角色以進行驗證和授權。 對大部分 Azure 服務的應用程式要求都必須使用金鑰或無金鑰連線進行驗證。 開發人員必須盡可能避免在不安全的地方公開金鑰。 能夠取得金鑰存取權的任何人都可以進行服務驗證。 無金鑰驗證可透過帳戶金鑰提供改良的管理和安全性優勢，因為沒有要儲存的金鑰 (或連接字串)。

使用下列步驟啟用無金鑰連線：

  • 設定您的驗證。
  • 視需要設定環境變數。
  • 使用 Azure 身分識別程式庫認證類型來建立 Azure AI 搜尋用戶端物件。

必要條件

本機開發和生產工作負載都必須完成下列步驟：

建立 AI 搜尋資源

在繼續本文之前，您需要 Azure AI 搜尋資源才能使用。 如果您沒有資源，請立即建立您的資源。 針對資源啟用角色型存取控制 (RBAC)。

安裝 Azure 身分識別用戶端程式庫

若要使用無密鑰方法，請使用 Azure 身分識別用戶端連結庫來更新已啟用 AI 搜尋的程式代碼。

安裝適用於 .NET 的 Azure 身分識別用戶端程式庫：

dotnet add package Azure.Identity

更新來源程式碼以使用 DefaultAzureCredential

Azure 身分識別程式庫的 DefaultAzureCredential 可讓您在本機開發環境和 Azure 雲端中執行相同的程式碼。 建立單一認證，並視需要重複使用認證執行個體，以利用權杖快取。

如需 .NET 的 DefaultAzureCredential 詳細資訊，請參閱適用於 .NET 的 Azure 身分識別用戶端程式庫。

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;
using System;
using static System.Environment;

string endpoint = GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
string indexName = "my-search-index";

DefaultAzureCredential credential = new();
SearchClient searchClient = new(new Uri(endpoint), indexName, credential);
SearchIndexClient searchIndexClient = new(endpoint, credential);

本機開發

使用角色的本機開發包含下列步驟：

  • 將您的個人身分識別指派給特定資源上的 RBAC 角色。
  • 使用 Azure CLI 或 Azure PowerShell 之類的工具向 Azure 進行驗證。
  • 為您的資源建立環境變數。

用於本機開發的角色

身為本機開發人員，您的 Azure 身分識別需要完全控制數據平面作業。 以下是建議的角色：

  • 搜尋服務參與者、建立和管理物件
  • 搜尋索引數據參與者、載入和查詢索引

使用下列其中一個工具尋找您的個人身分識別。 使用該身分識別作為 <identity-id> 值。

  1. 登入 Azure CLI。

    az login

  2. 取得您的個人身分識別。

    az ad signed-in-user show \
    --query id -o tsv

  3. 將角色型存取控制 (RBAC) 角色指派給資源群組的身分識別。

    az role assignment create \
    --role "<role-name>" \
    --assignee "<identity-id>" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"

如果適用，請將 <identity-id>、<subscription-id> 和 <resource-group-name> 取代為您的實際值。

本機開發的驗證

使用本機開發環境中的工具對 Azure 身分識別進行驗證。 驗證之後，原始程式碼中的 DefaultAzureCredential 執行個體會尋找並使用驗證。

設定本機開發的環境變數

若要連線至 Azure AI 搜尋，您的程式碼必須知道您的資源端點。

為您的 Azure AI 搜尋端點建立名為 AZURE_SEARCH_ENDPOINT 的環境變數。 此 URL 的格式通常為 https://<YOUR-RESOURCE-NAME>.search.windows.net/。

生產工作負載

部署生產工作負載包括下列步驟：

  • 選擇遵循最低權限原則的 RBAC 角色。
  • 將 RBAC 角色指派給特定資源上的生產身分識別。
  • 為您的資源設定環境變數。

用於生產環境工作負載的角色

若要建立生產資源，您需要建立使用者指派的受控識別，然後將身分識別指派給具有正確角色的資源。

針對生產應用程式，建議使用下列角色：

角色名稱 Id
搜尋索引資料讀取者 1407120a-92aa-4202-b7e9-c0e197c71c8f

生產工作負載的驗證

使用下列 Azure AI 搜尋 Bicep 範本來建立資源並設定 identityId 的驗證。 Bicep 需要角色識別碼。 此 Bicep 片段中顯示的 name 不是 Azure 角色；而是特定於 Bicep 部署的。

// main.bicep
param environment string = 'production'
param roleGuid string = ''

module aiSearchRoleUser 'core/security/role.bicep' = {
    scope: aiSearchResourceGroup
    name: 'aiSearch-role-user'
    params: {
        principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity.properties.principalId 
        principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
        roleDefinitionId: roleGuid
    }
}

main.bicep 檔案會呼叫下列泛型 Bicep 程式碼來建立任何角色。 您可以選擇建立多個 RBAC 角色，例如一個用於使用者，另一個用於生產環境。 這可讓您在同一個的 Bicep 部署內啟用開發和生產環境。

// core/security/role.bicep
metadata description = 'Creates a role assignment for an identity.'
param principalId string // passed in from main.bicep

@allowed([
    'Device'
    'ForeignGroup'
    'Group'
    'ServicePrincipal'
    'User'
])
param principalType string = 'ServicePrincipal'
param roleDefinitionId string // Role ID

resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
    properties: {
        principalId: principalId
        principalType: principalType
        roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    }
}

設定生產工作負載的環境變數

若要連線至 Azure AI 搜尋，您的程式碼必須知道您的資源端點，以及受控識別的識別碼。

為已部署和無金鑰的 Azure AI 搜尋資源建立環境變數：

  • AZURE_SEARCH_ENDPOINT：此 URL 是 Azure AI 搜尋資源的存取點。 此 URL 的格式通常為 https://<YOUR-RESOURCE-NAME>.search.windows.net/。
  • AZURE_CLIENT_ID：這是要作為驗證的身分識別。

相關內容