使用角色型訪問控制 連線 至 Azure AI 搜尋
Azure 為平台上執行的所有服務提供全域 角色型訪問控制授權系統 。 在 Azure AI 搜尋中,您可以使用 Azure 角色來執行下列工作:
控制平面作業(透過 Azure Resource Manager 的服務管理工作)。
數據平面作業,例如建立、載入和查詢索引。
不支援對搜尋結果的個別使用者存取(有時稱為 數據列層級安全性 或 檔層級安全性)。 因應措施是建立安全性篩選條件,以依使用者身分識別修剪結果,移除要求者不應該具有存取權的檔。
注意
關於術語的快速注意事項。 控制平面是指管理 REST API 或對等用戶端連結庫所支持的作業。 數據平面是指針對搜尋服務端點的作業,例如索引編製或查詢,或是搜尋 REST API 或對等用戶端連結庫中所指定的任何其他作業。
搜尋中使用的內建角色
下列角色是內建的。 如果這些角色不足, 請建立自定義角色。
角色 | 平面 | 描述 |
---|---|---|
負責人 | 控制與數據 | 完整存取搜尋資源的控制平面,包括指派 Azure 角色的能力。 只有擁有者角色可以啟用或停用驗證選項,或管理其他使用者的角色。 訂用帳戶管理員預設為成員。 在數據平面上,此角色具有與搜尋服務參與者角色相同的存取權。 它包含存取所有數據平面動作,但查詢或編製檔索引的能力除外。 |
參與者 | 控制與數據 | 與擁有者相同的控制平面存取層級,減去指派角色或變更驗證選項的能力。 在數據平面上,此角色具有與搜尋服務參與者角色相同的存取權。 它包含存取所有數據平面動作,但查詢或編製檔索引的能力除外。 |
讀取者 | 控制與數據 | 讀取整個服務的存取權,包括搜尋計量、內容計量(已取用的記憶體、物件數目),以及數據平面資源的物件定義(索引、索引器等等)。 不過,它無法在索引內讀取 API 金鑰或讀取內容。 |
搜尋服務參與者 | 控制與數據 | 物件定義的讀寫存取權(索引、別名、同義字對應、索引器、數據源和技能集)。 此角色適用於建立對象的開發人員,以及管理搜尋服務及其對象的系統管理員,但無法存取索引內容。 使用此角色來建立、刪除和列出索引、取得索引定義、取得服務資訊(統計數據和配額)、測試分析器、建立和管理同義字對應、索引器、數據源和技能集。 如需權限清單,請參閱 Microsoft.Search/searchServices/* 。 |
搜尋索引數據參與者 | 資料 | 索引中內容的讀寫存取權。 此角色適用於需要匯入、重新整理或查詢索引檔集合的開發人員或索引擁有者。 此角色不支持索引建立或管理。 根據預設,此角色適用於搜尋服務上的所有索引。 請參閱 授與單一索引 的存取權以縮小範圍。 |
搜尋索引數據讀取器 | 資料 | 查詢搜尋索引的唯讀存取權。 這個角色適用於執行查詢的應用程式和使用者。 此角色不支援物件定義的讀取許可權。 例如,您無法讀取搜尋索引定義或取得搜尋服務統計數據。 根據預設,此角色適用於搜尋服務上的所有索引。 請參閱 授與單一索引 的存取權以縮小範圍。 |
注意
如果您停用 Azure 角色型存取,控制平面的內建角色(擁有者、參與者、讀者)仍可繼續使用。 停用角色型存取只會移除與這些角色相關聯的數據相關許可權。 如果停用數據平面角色,Search Service 參與者相當於控制平面參與者。
限制
採用角色型訪問控制可能會增加某些要求的延遲。 在要求上使用的服務資源(索引、索引器等)和服務主體的每個唯一組合都會觸發授權檢查。 這些授權檢查最多可為要求增加 200 毫秒的延遲。
在少數情況下,要求源自大量不同的服務主體,所有目標都是不同的服務資源(索引、索引器等),授權檢查可能會導致節流。 只有在一秒內使用數百個唯一的搜尋服務資源和服務主體組合時,才會發生節流。
設定數據平面的角色型存取
適用於: 搜尋索引數據參與者、搜尋索引數據讀取器、搜尋服務參與者
在此步驟中,將搜尋服務設定為辨識 提供 OAuth2 存取令牌之數據要求上的授權 標頭。
登入 Azure 入口網站並開啟搜尋服務頁面。
選取 左側瀏覽窗格中的 [金鑰 ]。
選擇 API 存取控制選項。 如果您想要彈性或需要移轉應用程式,建議您 同時使用這兩者 。
選項 描述 API 金鑰 (預設)。 要求標頭上需要系統管理員或查詢 API 金鑰以進行授權。 不使用任何角色。 角色型存取控制 需要角色指派中的成員資格才能完成下一個步驟中所述的工作。 它也需要授權標頭。 兩者 要求是有效的,使用 API 金鑰或角色型存取控制。
變更會立即生效,但在測試之前請稍候幾秒鐘。
搜尋服務作業和內容的所有網路呼叫都會遵守您選取的選項:API 密鑰、持有人令牌,或選取 [兩者] 選項。
當您在入口網站中啟用角色型訪問控制時,如果授權失敗,失敗模式為 “HTTP401WithBearerChallenge”。
指派角色
角色指派在所有工具和客戶端連結庫中都是累積且普遍的。 您可以使用 Azure 角色型存取控制檔中所述的任何 支援方法 來指派角色。
您必須是 擁有者 或擁有 Microsoft.Authorization/roleAssignments/write 許可權,才能管理角色指派。
入口網站中的角色指派是全服務。 如果您想要 將許可權授與單一索引,請改用 PowerShell 或 Azure CLI。
登入 Azure 入口網站。
瀏覽至您的搜尋服務。
在左側瀏覽窗格中選取 [存取控制 [IAM]。
選取 [+新增]>[新增角色指派]。
選取適用的角色:
- 擁有者
- 參與者
- 讀取者
- 搜尋服務參與者
- 搜尋索引數據參與者
- 搜尋索引數據讀取器
在 [ 成員] 索引標籤上,選取 [Microsoft Entra 使用者或群組身分識別]。
在 [檢閱 + 指派] 索引標籤上,選取 [檢閱 + 指派] 以指派角色。
測試角色指派
使用客戶端來測試角色指派。 請記住,角色是訂用帳戶或資源群組範圍的累計和繼承角色,無法在資源層級刪除或拒絕。
請確定您已 使用 Microsoft Entra ID 註冊用戶端應用程式,並在測試存取權之前就位角色指派。
登入 Azure 入口網站。
瀏覽至您的搜尋服務。
在 [概觀] 頁面上,選取 [ 索引] 索引卷 標:
以目前使用者身分測試
如果您已經是搜尋服務的參與者或擁有者,您可以為使用者身分識別提供持有人令牌,以向 Azure AI 搜尋進行驗證。
使用 Azure CLI 取得目前使用者的持有人令牌:
az account get-access-token --scope https://search.azure.com/.default
或使用 PowerShell:
Get-AzAccessToken -ResourceUrl https://search.azure.com
在 Visual Studio Code 的新文字檔中,貼上下列變數:
@baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE @index-name = PASTE-YOUR-INDEX-NAME-HERE @token = PASTE-YOUR-TOKEN-HERE
貼上 ,然後傳送要求以確認存取權。 以下是查詢 hotels-quickstart 索引的查詢
POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-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 使用者或組名,以及指派的範圍。
Azure
載入和AzureAD
模組並連線到您的 Azure 帳戶:Import-Module -Name Az Import-Module -Name AzureAD Connect-AzAccount
將範圍設定為個別索引的角色指派:
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 自定義角色。 在搜尋服務頁面中支持從現有角色複製。
這些步驟會建立自定義角色,以增強搜尋查詢許可權,以依名稱包含清單索引。 一般而言,列出索引會被視為系統管理功能。
在 Azure 入口網站 中,流覽至您的搜尋服務。
在左側瀏覽窗格中,選取 [存取控制 (IAM)]。
在動作列中,選取 [ 角色]。
以滑鼠右鍵按兩下 [搜尋索引數據讀取器 ] (或其他角色),然後選取 [ 複製 ] 以開啟 [建立自定義角色 精靈]。
在 [基本] 索引標籤上,提供自定義角色的名稱,例如 「搜尋索引數據總管」,然後選取 [下一步]。
在 [許可權] 索引標籤上,選取 [ 新增許可權]。
在 [新增許可權] 索引標籤上,搜尋 ,然後選取 [Microsoft 搜尋] 圖格。
設定自定義角色的許可權。 在頁面頂端,使用預設 的 [動作] 選取專案:
- 在 [Microsoft.Search/operations] 底下,選取 [ 讀取:列出所有可用的作業]。
- 在 [Microsoft.Search/searchServices/indexes] 下,選取 [ 讀取:讀取索引]。
在相同的頁面上,切換至 [數據] 動作 ,然後在 [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": [] } ] } }
選取 [ 檢閱 + 建立 ] 以建立角色。 您現在可以將使用者和群組指派給角色。
停用 API 金鑰驗證
如果您使用搜尋服務參與者、搜尋索引數據參與者,以及搜尋索引數據讀取者角色和 Microsoft Entra 驗證,則可以在您的服務上停用密鑰存取或本機驗證。 停用 API 金鑰會導致搜尋服務拒絕在標頭中傳遞 API 金鑰的所有資料相關要求。
注意
管理員 API 金鑰只能停用,無法刪除。 您可以刪除查詢 API 金鑰。
需要擁有者或參與者許可權才能停用功能。
若要停用金鑰型驗證,請使用 Azure 入口網站 或管理 REST API。
在 Azure 入口網站 中,流覽至您的搜尋服務。
在左側瀏覽窗格中,選取 [金鑰]。
選取 [角色型訪問控制]。
變更會立即生效,但在測試之前請稍候幾秒鐘。 假設您有權將角色指派為擁有者、服務管理員或共同管理員的成員,您可以使用入口網站功能來測試角色型存取。
條件式存取
如果您需要強制執行組織原則,例如多重要素驗證,建議您 使用 Microsoft Entra 條件式存取 。
若要啟用 Azure AI 搜尋的條件式存取原則,請遵循下列步驟:
登入 Azure 入口網站。
搜尋 Microsoft Entra 條件式存取。
選取原則。
選取 [新增原則]。
在原則的 [雲端應用程式或動作] 區段中,根據您想要設定原則的方式,將 Azure AI 搜尋新增為雲端應用程式。
更新原則的其餘參數。 例如,指定套用此原則的使用者和群組。
儲存原則。
重要
如果您的搜尋服務已獲指派受控識別,特定搜尋服務會顯示為雲端應用程式,可納入或排除為條件式存取原則的一部分。 條件式存取原則無法在特定搜尋服務上強制執行。 請改為確定您選取一般 Azure AI 搜尋 雲端應用程式。
針對角色型訪問控制問題進行疑難解答
開發使用角色型存取控制進行驗證的應用程式時,可能會發生一些常見問題: