共用方式為

使用角色連線到 Azure AI 搜尋

  • 發行項

Azure 針對平台上執行的所有服務，透過 Microsoft Entra ID 提供全域驗證和 角色型訪問控制 。 在本文中，瞭解哪些角色可存取 Azure AI 搜尋服務上的搜尋內容和管理。

在 Azure AI 搜尋服務中，您可以針對下列項目指派 Azure 角色：

透過角色指派不支援對搜尋結果的每一使用者存取 (有時稱為資料列層級安全性或文件層級安全性)。 因應措施是建立安全性篩選，其會依使用者身分識別修剪結果，並移除要求者不應具有存取權的文件。 如需示範，請參閱此使用 RAG 的企業聊天範例。

角色指派在所有工具和用戶端程式庫中都會累積且普遍的。 您可以使用 Azure 角色型存取控制文件中所述的任何支援的方法來指派角色。

角色型存取是選用的，但建議使用。 替代方法是金鑰型驗證，這是預設值。

必要條件

如何在入口網站中指派角色

下列步驟適用於所有角色指派。

  1. 登入 Azure 入口網站。

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

  3. 啟用角色型存取。

  4. 在左側導覽窗格中選取 [存取控制 (IAM)]。

  5. 選取 [+ 新增>新增角色指派 ] 以啟動 [ 新增角色指派 精靈]。

    Azure 入口網站 中訪問控制頁面的螢幕快照。

  6. 選取角色。 您可以指派多個安全性主體，無論是使用者或受控識別到一次傳遞精靈中的角色，但您必須針對您定義的每個角色重複這些步驟。

  7. 在 [成員] 索引標籤上，選取 Microsoft Entra 使用者或群組身分識別。 如果您要設定另一個 Azure 服務的許可權，請選取系統或使用者受控識別。

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

數據平面是指針對搜尋服務端點的作業，例如編製索引或查詢，或搜尋服務 REST API 或對等的 Azure SDK 用戶端連結庫中指定的任何其他作業。

控制平面 是指 Azure 資源管理，例如建立或設定搜尋服務。

下列角色是內建的。 如果這些角色不足，請建立自訂角色。

角色 平面 描述
負責人 控制與資料 完整存取搜尋資源的控制平面，包括指派 Azure 角色的能力。 只有「擁有者」角色可以啟用或停用驗證選項，或管理其他使用者的角色。 訂用帳戶管理員預設為成員。

在資料平面上，此角色具有與「搜尋服務參與者」角色相同的存取權。 其包括所有資料平面動作的存取權，但查詢文件或編製文件索引的能力除外。
參與者 控制與資料 與「擁有者」具有相同的控制平面存取層級，減去指派角色或變更授權選項的能力。

在資料平面上，此角色具有與「搜尋服務參與者」角色相同的存取權。 其包括所有資料平面動作的存取權，但查詢文件或編製文件索引的能力除外。
讀取者 控制與資料 跨整個服務的讀取存取，包括搜尋計量、內容計量 (取用的儲存體、物件數目) 以及資料平面資源的物件定義 (索引、索引子等)。 但是，它無法讀取 API 金鑰或讀取索引中的內容。
搜尋服務參與者 控制與資料 對物件定義 (索引、別名、同義字對應、索引子、資料來源和技能集) 的讀寫存取權。 此角色適合建立物件的開發人員，以及管理搜尋服務及其物件的系統管理員，但無法存取索引內容。 使用此角色來建立、刪除和列出索引、取得索引定義、取得服務資訊 (統計資料和配額)、測試分析器、建立和管理同義詞對應、索引子、資料來源和技能集。 如需權限清單，請參閱 Microsoft.Search/searchServices/*。
搜尋索引資料參與者 資料 索引中內容的讀寫存取權。 此角色適用於需要匯入、重新整理或查詢索引文件集合的開發人員或索引擁有者。 此角色不支援索引建立或管理。 根據預設，此角色適合搜尋服務上的所有索引。 請參閱授與單一索引的存取權，以縮小範圍。
搜尋索引資料讀取者 資料 查詢搜尋索引的唯讀存取權。 此角色適用於執行查詢的應用程式和使用者。 此角色不支援物件定義的讀取存取權。 例如，您無法讀取搜尋索引定義或取得搜尋服務統計資料。 根據預設，此角色適合搜尋服務上的所有索引。 請參閱授與單一索引的存取權，以縮小範圍。

結合這些角色以取得足夠的使用案例權限。

注意

如果您停用 Azure 角色型存取，控制平面的內建角色 (擁有者、參與者、讀者) 仍可繼續使用。 停用角色型存取只會移除與這些角色相關聯的資料相關權限。 如果停用資料平面角色，搜尋服務參與者會相當於控制平面參與者。

摘要

權限 搜尋索引資料讀取者 搜尋索引資料參與者 搜尋服務參與者 擁有者/參與者 讀取者
在 Azure 入口網站中檢視資源 ❌ ❌ ✅ ✅ ✅
檢視資源屬性/計量/端點 ❌ ❌ ✅ ✅ ✅
列出資源上的所有物件 ❌ ❌ ✅ ✅ ✅
存取配額和服務統計數據 ❌ ❌ ✅ ✅ ❌
讀取/查詢索引 ✅ ❌ ❌ ❌ ❌
上傳用於編製索引的數據 ❌ ✅ ❌ ❌ ❌
建立或編輯索引/別名 ❌ ❌ ✅ ✅ ❌
建立、編輯和執行索引器/數據源/技能集 ❌ ❌ ✅ ✅ ❌
建立或編輯同義字對應 ❌ ❌ ✅ ✅ ❌
建立或編輯偵錯會話 ❌ ❌ ✅ ✅ ❌
建立或管理部署 ❌ ❌ ✅ ✅ ❌
建立或設定 Azure AI 搜尋資源 ❌ ❌ ✅ ✅ ❌
在 [金鑰] 底下檢視/複製/重新產生金鑰 ❌ ❌ ✅ ✅ ❌
檢視角色/原則/定義 ❌ ❌ ✅ ✅ ❌
設定驗證選項 ❌ ❌ ✅ ✅ ❌
設定私人連線 ❌ ❌ ✅ ✅ ❌
設定網路安全性 ❌ ❌ ✅ ✅ ❌

擁有者和參與者會授與相同的許可權，不同之處在於只有擁有者可以指派角色。

如果啟用 API 金鑰，擁有者和參與者可以在 Azure 入口網站 中建立、讀取、更新和刪除物件。 入口網站會在數據平面 API 的內部呼叫上使用金鑰。 在您後續將 Azure AI 搜尋設定為只使用「角色」時，擁有者和參與者將無法只使用這些角色指派來管理入口網站中的物件。 解決方案是指派更多角色，例如搜尋索引數據讀取器、搜尋索引數據參與者和搜尋服務參與者。

指派角色

在本節中，針對下列項目指派角色：

  • 服務管理
  • 搜尋服務的開發或寫入存取
  • 查詢的唯讀存取

指派服務管理的角色

身為服務管理員，您可以建立及設定搜尋服務，並執行管理 REST API 或對等用戶端程式庫中所述的所有控制平面作業。 如果您是擁有者或參與者，您也可以在 Azure 入口網站 中執行大部分的數據平面搜尋 REST API 工作。

角色 識別碼
Owner 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributor b24988ac-6180-42a0-ab88-20f7382dd24c
Reader acdd72a7-3385-48ef-bd42-f606fba81ae7

  1. 登入 Azure 入口網站。

  2. 指派這些角色：

    • 擁有者 (所有資料平面和控制平面作業的完整存取權，查詢權限除外)
    • 參與者 (與擁有者相同，指派角色的權限除外)
    • 讀取者 (可接受監視和檢視計量)

指派用於開發的角色

角色指派在搜尋服務之間是全域的。 若要將權限限定在單一索引，請使用 PowerShell 或 Azure CLI 來建立自訂角色。

Task 角色 識別碼
CRUD 作業 Search Service Contributor 7ca78c08-252a-4471-8644-bb5ff32d4ba0
載入文件，執行編製索引作業 Search Index Data Contributor 8ebe5a00-799e-43f5-93ac-243d3dce84a7
查詢索引 Search Index Data Reader 1407120a-92aa-4202-b7e9-c0e197c71c8f

提供完整存取權的另一個角色組合是 [參與者] 或 [擁有者]，以及 [搜尋索引資料讀取者]。

重要

如果您設定服務或索引的角色型存取，而且也在要求上提供 API 金鑰，搜尋服務會使用 API 金鑰進行驗證。

  1. 登入 Azure 入口網站。

  2. 指派這些角色：

    • 搜尋服務參與者 (索引、索引子、技能集和其他最上層物件的建立、讀取、更新、刪除作業)
    • 搜尋索引資料參與者 (載入文件並執行編製索引工作)
    • 搜尋索引資料讀取者 (查詢索引)

為唯讀查詢指派角色

針對只需要索引的讀取權限的應用程式和程序，使用 [搜尋索引資料讀取者] 角色。

角色 識別碼
Search Index Data Reader with PowerShell 1407120a-92aa-4202-b7e9-c0e197c71c8f

這是一個非常特定的角色。 它會授與 GET 或 POST 對搜尋索引的文件集合進行搜尋、自動完成和建議的存取權。 它不支援索引或其他最上層物件的 GET 或 LIST 作業，或 GET 服務統計資料。

本節提供設定角色指派的基本步驟並在此提供完整性，但建議您使用 Azure AI 搜尋 (不需金鑰) 以取得設定應用程式進行角色型存取的完整指示。

  1. 登入 Azure 入口網站。

  2. 指派搜尋 索引數據讀取者 角色。

測試角色指派

使用用戶端來測試角色指派。 請記住，角色是限定於訂用帳戶或資源群組層級的累計和繼承角色，無法在資源 (搜尋服務) 層級刪除或拒絕。

為應用程式設定無金鑰連線，並在測試之前備妥角色指派。

  1. 登入 Azure 入口網站。

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

  3. 在 [概觀] 頁面上，選取 [索引] 索引標籤：

    • 搜尋服務參與者可以檢視及建立任何物件，但無法載入文件或查詢索引。 若要驗證權限，請建立搜尋索引。

    • 搜尋索引資料參與者可以載入文件。 在 [匯入資料精靈] 外部的入口網站中沒有載入文件選項，但您可以重設並執行索引子來確認文件載入權限。

    • [搜尋索引資料讀取者] 可以查詢索引。 若要驗證權限，請使用搜尋總管。 您應該能夠傳送查詢及檢視結果，但您不應該能夠檢視索引定義或加以建立。

以目前使用者的身分測試

如果您已經是搜尋服務的參與者或擁有者，您可以為使用者身分識別提供持有人權杖，以向 Azure AI 搜尋服務進行驗證。

  1. 使用 Azure CLI 取得目前使用者的持有人權杖：

    az account get-access-token --scope https://search.azure.com/.default

    或使用 PowerShell：

    Get-AzAccessToken -ResourceUrl https://search.azure.com

  2. 在 Visual Studio Code 的新文字檔中，貼上下列變數。

    @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
@index-name = PASTE-YOUR-INDEX-NAME-HERE
@token = PASTE-YOUR-TOKEN-HERE

  3. 貼上，然後傳送要求以確認存取權。 以下是查詢 hotels-quickstart 索引的要求

    POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2024-07-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

    {
         "queryType": "simple",
         "search": "motel",
         "filter": "",
         "select": "HotelName,Description,Category,Tags",
         "count": true
     }

授與單一索引的存取權

在某些情況下，您可能想要限制應用程式對單一資源 (例如索引) 的存取權。

入口網站目前不支援此細微性層級的角色指派，但可以使用 PowerShell 或 Azure CLI 來完成。

在 PowerShell 中，使用 New-AzRoleAssignment，提供 Azure 使用者或群組名稱，以及指派的範圍。

  1. 載入 Azure 和 AzureAD 模組，並連線到您的 Azure 帳戶：

    Import-Module -Name Az
Import-Module -Name AzureAD
Connect-AzAccount

  2. 新增範圍限定於個別索引的角色指派：

    New-AzRoleAssignment -ObjectId <objectId> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

建立自訂角色

如果內建角色未提供正確的權限組合，您可以建立自訂角色以支援所需的作業。

此範例會複製搜尋索引資料讀取者，然後新增依名稱列出索引的能力。 通常，列出搜尋服務上的索引會被視為系統管理權限。

這些步驟衍生自使用 Azure 入口網站建立或更新 Azure 自訂角色。 在搜尋服務頁面中支援從現有角色複製。

這些步驟會建立自訂角色，以增強搜尋查詢權限，以依名稱包含列出索引。 一般而言，列出索引會被視為系統管理功能。

  1. 在 Azure 入口網站中，瀏覽至您的搜尋服務。

  2. 在左側瀏覽窗格中，選取 [存取控制 (IAM)]。

  3. 在動作列中，選取 [角色]。

  4. 以滑鼠右鍵按一下 [搜尋索引資料讀取者] (或其他角色)，然後選取 [複製] 以開啟 [建立自訂角色] 精靈。

  5. 在 [基本] 索引標籤上，提供自訂角色的名稱，例如「搜尋索引資料總管」，然後選取 [下一步]。

  6. 在 [權限] 索引標籤上，選取 [新增權限]。

  7. 在 [新增權限] 索引標籤上，搜尋並選取 [Microsoft 搜尋] 圖格。

  8. 設定自訂角色的權限。 在頁面頂端，使用預設的 [動作] 選取項目：

    • 在 Microsoft.Search/operations 底下，選取 [讀取: 列出所有可用的作業]。
    • 在 Microsoft.Search/searchServices/indexes 底下，選取 [讀取: 讀取索引]。

  9. 在相同頁面上，切換至 [資料動作]，然後在 Microsoft.Search/searchServices/indexes/documents 下，選取 [讀取: 讀取文件]。

    JSON 定義看起來像下列範例：

    {
 "properties": {
     "roleName": "search index data explorer",
     "description": "",
     "assignableScopes": [
         "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
     ],
     "permissions": [
         {
             "actions": [
                 "Microsoft.Search/operations/read",
                 "Microsoft.Search/searchServices/indexes/read"
             ],
             "notActions": [],
             "dataActions": [
                 "Microsoft.Search/searchServices/indexes/documents/read"
             ],
             "notDataActions": []
         }
     ]
   }
 }

  10. 選取 [檢閱 + 建立] 以建立角色。 您現在可以將使用者和群組指派給角色。

條件式存取

如果您需要強制執行組織原則，例如多重要素驗證，建議您使用 Microsoft Entra 條件式存取。

若要為 Azure AI 搜尋服務啟用條件式存取原則，請遵循下列步驟：

  1. 登入 Azure 入口網站。

  2. 搜尋 Microsoft Entra 條件式存取。

  3. 選取原則。

  4. 選取 [新增原則]。

  5. 在原則的 [雲端應用程式或動作] 區段中，根據您想要設定原則的方式，將 Azure AI 搜尋服務新增為雲端應用程式。

  6. 更新原則的其餘參數。 例如，指定此原則適用的使用者和群組。

  7. 儲存原則。

重要

如果您的搜尋服務已獲指派受控識別，則特定搜尋服務會顯示為雲端應用程式，可併入或排除為條件式存取原則的一部分。 無法在特定搜尋服務上強制執行條件式存取原則。 請改為確定您選取一般 Azure AI 搜尋服務雲端應用程式。

限制

  • 角色型存取控制可以增加某些要求的延遲。 服務資源 (索引、索引子等) 和服務主體的每個唯一組合，都會觸發授權檢查。 這些授權檢查最多可對每一要求增加 200 毫秒的延遲。

  • 在少數情況下，其中的要求源自大量不同的服務主體，都以不同服務資源為目標 (索引、索引子等)，授權檢查可能會導致節流。 只有在一秒內使用了數百個唯一的搜尋服務資源和服務主體的組合時，才會發生節流。

為角色型存取控制問題進行疑難排解

開發使用角色型存取控制進行驗證的應用程式時，可能會發生一些常見問題：

  • 如果授權權杖來自受控識別，且最近指派了適當的權限，可能需要數小時的時間，這些權限指派才會生效。

  • 搜尋服務的預設設定是以金鑰為基礎的驗證。 如果您未將預設金鑰設定變更為 [兩者] 或 [角色型存取控制]，則不論基礎權限為何，都會自動拒絕使用角色型驗證的所有要求。