使用 Microsoft Entra 識別碼授權搜尋應用程式的存取權

  • 發行項

在 Azure AI 搜尋服務上建置的搜尋應用程式現在可以使用 Microsoft 身分識別平台 進行已驗證和授權的存取。 在 Azure 上，識別提供者是 Microsoft Entra ID。 使用 Microsoft Entra ID 的主要優點是您的認證和 API 金鑰不再需要儲存在程式碼中。 Microsoft Entra 會驗證執行應用程式的安全性主體（使用者、群組或服務）。 如果驗證成功，Microsoft Entra ID 會將存取令牌傳回給應用程式，然後應用程式可以使用存取令牌來授權對 Azure AI 搜尋的要求。

本文說明如何設定 Microsoft Entra 識別符的用戶端：

  • 若要進行驗證，請為您的應用程式建立 受控識別 。 您可以使用不同類型的安全性主體物件，但本文會使用受控識別，因為它們不需要管理認證。

  • 若要進行授權，請將 Azure 角色指派給受控識別，以授與執行查詢或管理索引作業的許可權。

  • 更新客戶端程式代碼以呼叫 TokenCredential()。 例如，您可以使用 Azure.Identity 透過 Microsoft Entra ID 開始使用新的 SearchClient（endpoint，newDefaultAzureCredential()） 進行驗證。

設定數據平面的角色型存取

適用於： 搜尋索引數據參與者、搜尋索引數據讀取器、搜尋服務參與者

在此步驟中，將搜尋服務設定為辨識 提供 OAuth2 存取令牌之數據要求上的授權 標頭。

  1. 登入 Azure 入口網站並開啟搜尋服務頁面。

  2. 選取 左側瀏覽窗格中的 [金鑰 ]。

    密鑰頁面的螢幕快照，其中包含驗證選項。

  3. 選擇 API 存取控制選項。 如果您想要彈性或需要移轉應用程式，建議您 同時使用這兩者 。

    選項 描述
    API 金鑰 （預設值） 要求標頭上需要系統管理員或查詢 API 金鑰 以進行授權。 不使用任何角色。
    角色型存取控制 需要角色指派中的成員資格才能完成下一個步驟中所述的工作。 它也需要授權標頭。
    兩者 要求是有效的，使用 API 金鑰或角色型存取控制。

變更會立即生效，但在測試之前請稍候幾秒鐘。

搜尋服務作業和內容的所有網路呼叫都會遵守您選取的選項：API 密鑰、持有人令牌，或選取 [兩者] 選項。

當您在入口網站中啟用角色型訪問控制時，如果授權失敗，失敗模式為 “HTTP401WithBearerChallenge”。

建立受控識別

在此步驟中，為用戶端應用程式建立 受控識別 。

  1. 登入 Azure 入口網站。

  2. 搜尋 受控識別。

  3. 選取 建立。

  4. 為您的受控識別指定名稱，然後選取區域。 然後，選取 [建立]。

    建立受控識別精靈的螢幕快照。

將角色指派給受控識別

接下來，您必須授與用戶端對搜尋服務的受控識別存取權。 Azure AI 搜尋具有各種 內建角色。 您也可以建立 自定義角色。

授與最低許可權是最佳做法。 如果您的應用程式只需要處理查詢，您應該指派 搜尋索引數據讀取器 角色。 或者，如果用戶端在搜尋索引上同時需要讀取和寫入存取權，您應該使用 搜尋索引數據參與者 角色。

  1. 登入 Azure 入口網站。

  2. 瀏覽至您的搜尋服務。

  3. 選取 左側瀏覽窗格中的 [存取控制][IAM ]。

  4. 選取 [+新增]>[新增角色指派]。

    [訪問控制 ][IAM] 頁面的螢幕快照，其中已開啟 [新增角色指派] 功能表。

  5. 選取適用的角色：

    • 擁有者

    • 參與者

    • 讀取者

    • 搜尋服務參與者

    • 搜尋索引數據參與者

    • 搜尋索引數據讀取器

      注意

      擁有者、參與者、讀者和搜尋服務參與者是控制平面角色，而且不會讓您存取搜尋索引內的數據。 針對數據存取，請選擇 [搜尋索引數據參與者] 或 [搜尋索引數據讀取者] 角色。 如需每個角色的範圍和用途的詳細資訊，請參閱 搜尋中使用的內建角色。

  6. 在 [ 成員] 索引標籤上，選取您想要授與搜尋服務的存取權的受控識別。

  7. 在 [檢閱 + 指派] 索引標籤上，選取 [檢閱 + 指派] 以指派角色。

如果您的應用程式需要完整存取搜尋服務、對象和內容，您可以指派多個角色，例如搜尋服務參與者和搜尋索引數據參與者。

您也可以 使用PowerShell指派角色。

在您的客戶端中設定 Microsoft Entra 驗證

在搜尋服務上擁有受控識別和角色指派之後，您就可以將程式代碼新增至應用程式，以驗證安全性主體並取得 OAuth 2.0 令牌。

使用下列用戶端連結庫進行角色型存取控制：

注意

若要深入瞭解 Microsoft Entra 識別碼所使用的 OAuth 2.0 程式代碼授與流程，請參閱 使用 OAuth 2.0 程式代碼授與流程授權 Microsoft Entra Web 應用程式的存取權。

下列指示會參考現有的 C# 範例，以示範程式代碼變更。

  1. 作為起點，請複製快速入門：使用 Azure SDK 進行全文搜索的 C# 區段原始程式碼。

    此範例目前使用金鑰型驗證和 AzureKeyCredential 來建立 SearchClient ， SearchIndexClient 但您可以進行小變更，以切換至角色型驗證。

  2. 將 Azure.Search.Documents NuGet 套件更新為 11.4 版或更新版本。

  3. 匯入 Azure.Identity 連結 庫以存取其他驗證技術。

  4. 不要在 Main() Program.cs 開頭使用 AzureKeyCredentialDefaultAzureCredential ，請使用 ，如下列代碼段所示：

    // Create a SearchIndexClient to send create/delete index commands
SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
// Create a SearchClient to load and query documents
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());

本機測試

使用者指派的受控識別只能在 Azure 環境中運作。 如果您在本機執行此程式碼， DefaultAzureCredential 請回復為使用您的認證進行驗證。 如果您打算在本機執行程式碼，請務必自行提供搜尋服務的必要存取權。

  1. 確認您的帳戶具有角色指派，以在快速入門範例中執行所有作業。 若要建立和查詢索引，請使用「搜尋索引數據讀取器」和「搜尋索引數據參與者」。

  2. 移至 [工具>選項>][Azure 服務驗證 ] 以選擇您的 Azure 登入帳戶。

您現在應該能夠從本機系統上的 Visual Studio 執行專案，並使用角色型訪問控制進行授權。

注意

Azure.Identity 檔有更多關於 DefaultAzureCredential Microsoft Entra 驗證與 Azure SDK for .NET 搭配使用的詳細數據。 DefaultAzureCredential 旨在透過處理具有合理預設行為的常見案例，來簡化開始使用 SDK 的過程。 想要更多控制或其案例未透過預設設定來提供的開發人員應該使用其他認證類型。

另請參閱