使用角色型訪問控制連線到 Azure AI 搜尋

發行項
06/13/2024

Azure 會針對平台上執行的所有服務，提供全域角色型存取控制授權系統。在 Azure AI 搜尋中，您可以為下列專案指派 Azure 角色：

服務管理
搜尋服務的開發或寫入存取權
查詢的唯讀存取
單一索引的範圍存取

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

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

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

必要條件

擁有者、 使用者存取管理員或具有 Microsoft.Authorization/roleAssignments/write 許可權的自定義角色。
在任何區域中啟用角色型存取的任何區域中的搜尋服務。

Azure AI 搜尋中使用的內建角色

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

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

注意

如果您停用 Azure 角色型存取，控制平面的內建角色 (擁有者、參與者、讀者) 仍可繼續使用。停用角色型存取只會移除與這些角色相關聯的數據相關許可權。如果停用數據平面角色，Search Service 參與者相當於控制平面參與者。

指派角色

在本節中，為下列專案指派角色：

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

指派服務管理的角色

身為服務管理員，您可以建立及設定搜尋服務，並執行管理 REST API 或對等用戶端連結庫中所述的所有控制平面作業。視角色而定，您也可以執行大部分的數據平面搜尋 REST API 工作。

Azure 入口網站
PowerShell

登入 Azure 入口網站。
瀏覽至您的搜尋服務。
在左側導覽窗格中選取 [存取控制 (IAM)]。
選取 [+新增]>[新增角色指派]。
選取適用的角色：
- 擁有者（所有數據平面和控制平面作業的完整存取權，但查詢許可權除外）
- 參與者（與擁有者相同，但指派角色的許可權除外）
- 讀者（可接受監視和檢視計量）
在 [成員] 索引標籤上，選取 Microsoft Entra 使用者或群組身分識別。
在 [檢閱 + 指派] 索引標籤上，選取 [檢閱 + 指派] 以指派角色。

當您使用PowerShell指派角色時，請呼叫 New-AzRoleAssignment、提供 Azure 使用者或組名，以及指派的範圍。

此範例會建立範圍設定為搜尋服務的角色指派：

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

指派用於開發的角色

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

注意

如果您提出要求，例如 REST 呼叫，其中包含 API 金鑰，而且您也是角色指派的一部分，API 金鑰會優先使用。例如，如果您有只讀角色指派，但使用系統管理 API 金鑰提出要求，則 API 金鑰授與的許可權會覆寫角色指派。只有在搜尋服務同時啟用密鑰和角色時，才會套用此行為。

Azure 入口網站
PowerShell

登入 Azure 入口網站。
瀏覽至您的搜尋服務。
在左側導覽窗格中選取 [存取控制 (IAM)]。
選取 [+新增]>[新增角色指派]。
選取角色：
- 搜尋服務參與者（索引器、索引器、技能集和其他最上層物件的 create-read-update-delete 作業）
- 搜尋索引數據參與者（載入檔並執行編制索引作業）
- 搜尋索引資料讀取器（查詢索引）
提供完整存取權的另一個角色組合是參與者或擁有者，以及搜尋索引數據讀取器。
在 [成員] 索引標籤上，選取 Microsoft Entra 使用者或群組身分識別。
在 [檢閱 + 指派] 索引標籤上，選取 [檢閱 + 指派] 以指派角色。
針對其他角色重複。大部分的開發人員都需要這三個。

當您使用PowerShell指派角色時，請呼叫 New-AzRoleAssignment、提供 Azure 使用者或組名，以及指派的範圍。

此範例會建立範圍設定為搜尋服務的角色指派：

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

此範例會建立範圍設定為特定索引的角色指派：

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

為唯讀查詢指派角色

針對只需要索引讀取許可權的應用程式和進程，使用搜尋索引數據讀取器角色。這是一個非常特定的角色。它會授與 GET 或 POST 對搜尋索引的檔集合進行搜尋、自動完成和建議的存取權。

它不支援索引或其他最上層物件的 GET 或 LIST 作業，或 GET 服務統計數據。

Azure 入口網站
PowerShell

登入 Azure 入口網站。
瀏覽至您的搜尋服務。
在左側導覽窗格中選取 [存取控制 (IAM)]。
選取 [+新增]>[新增角色指派]。
選取 [ 搜尋索引數據讀取器 ] 角色。
在 [成員] 索引標籤上，選取 Microsoft Entra 使用者或群組身分識別。如果您要設定另一個服務的許可權，您可能會使用系統或使用者管理的身分識別。如果角色指派適用於服務身分識別，請選擇該選項。
在 [檢閱 + 指派] 索引標籤上，選取 [檢閱 + 指派] 以指派角色。

使用 PowerShell 來指派角色時，請呼叫 New-AzRoleAssignment，提供 Azure 使用者或群組名稱，以及指派的範圍。

取得您的訂用帳戶標識碼、搜尋服務資源群組和搜尋服務名稱。

取得 Azure 服務的物件標識碼，例如 Azure OpenAI。

 Get-AzADServicePrincipal -SearchString <YOUR AZURE OPENAI RESOURCE NAME>

取得角色定義並檢閱許可權，以確定這是您想要的角色。
```
Get-AzRoleDefinition -Name "Search Index Data Reader"
```

建立角色指派，取代佔位符的有效值。

New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME

以下是限定為特定索引的角色指派範例：

New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID `
    -RoleDefinitionName "Search Index Data Reader" `
    -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME/indexes/YOUR-INDEX-NAME

測試角色指派

使用用戶端來測試角色指派。請記住，角色是訂用帳戶或資源群組層級範圍的累計和繼承角色，無法在資源層級刪除或拒絕。

在測試存取之前，請確定您使用 Microsoft Entra ID 註冊用戶端應用程式並進行角色指派。

登入 Azure 入口網站。
瀏覽至您的搜尋服務。
在 [概觀] 頁面上，選取 [索引] 索引標籤：
- 搜尋服務參與者可以檢視及建立任何物件，但無法載入檔或查詢索引。若要驗證許可權，請建立搜尋索引。
- 搜尋索引數據參與者可以載入檔。在 [匯入數據精靈] 外部的入口網站中沒有載入檔選項，但您可以重設並執行索引器來確認檔載入許可權。
- 搜尋索引數據讀取器可以查詢索引。若要驗證許可權，請使用搜尋總管。您應該能夠傳送查詢和檢視結果，但不應該能夠檢視索引定義或建立索引定義。

此方法假設Visual StudioCode具有REST用戶端擴充功能。

開啟 Azure CLI 的命令殼層，並登入您的 Azure 訂用帳戶。
```
az login
```
取得您的租用戶標識碼和訂用帳戶標識碼。識別碼會在未來的步驟中作為變數使用。
```
az account show
```

取得存取令牌。

az account get-access-token --query accessToken --output tsv

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

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

貼上，然後傳送使用您所指定變數的要求。針對「搜尋索引數據讀取者」角色，您可以傳送查詢。您可以使用任何支援的 API 版本。

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
     }

如需如何取得特定環境令牌的詳細資訊，請參閱使用 REST API 管理 Azure AI 搜尋服務和 Microsoft 身分識別平台驗證連結庫。

使用 Azure.Search.Documents 套件。
使用 Azure.Identity for .NET 進行權杖驗證。 Microsoft 建議您在大部分案例中採用 DefaultAzureCredential()。

以下是使用 DefaultAzureCredential() 的用戶端連線範例。

// 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());

這是使用用戶端秘密認證的另一個範例：

var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);

使用 azure.search.documents (適用於 Python 的 Azure SDK)。
使用 Azure.Identity for Python 進行權杖驗證。
如果 Python 用戶端是執行伺服器端的應用程式，請使用 DefaultAzureCredential。如果應用程式在瀏覽器中執行，請啟用互動式驗證。

以下是範例：

from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
endpoint = "https://<mysearch>.search.windows.net"
index_name = "myindex"
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

以目前使用者的身分測試

如果您已經是搜尋服務的參與者或擁有者，您可以為使用者身分識別提供持有人權杖，以向 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": []
         }
     ]
   }
 }

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

PowerShell 範例顯示用來建立自訂角色的 JSON 語法，其為搜尋索引資料讀取者的複製，但能夠依名稱列出所有索引。

檢閱不可部分完成的權限清單，以判斷您需要的權限。在此範例中，您將需要下列項目：

"Microsoft.Search/operations/read",
"Microsoft.Search/searchServices/read",
"Microsoft.Search/searchServices/indexes/read"

設定 PowerShell 工作階段以建立自訂角色。如需詳細指示，請參閱 Azure PowerShell
提供角色定義做為 JSON 文件。下列範例顯示用於使用 PowerShell 建立自訂角色的語法。

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

注意

如果可指派的範圍位於索引層級，則資料動作應該是 "Microsoft.Search/searchServices/indexes/documents/read"。

條件式存取

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

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

登入 Azure 入口網站。
搜尋 Microsoft Entra 條件式存取。
選取原則。
選取 [新增原則]。
在原則的 [雲端應用程式或動作] 區段中，根據您想要設定原則的方式，將 Azure AI 搜尋服務新增為雲端應用程式。
更新原則的其餘參數。例如，指定此原則適用的使用者和群組。
儲存原則。

重要

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

限制

角色型訪問控制可以增加某些要求的延遲。服務資源（索引、索引器等）和服務主體的每個唯一組合都會觸發授權檢查。這些授權檢查可為每個要求新增最多 200 毫秒的延遲。
在少數情況下，其中的要求源自大量不同的服務主體，都以不同服務資源為目標 (索引、索引子等)，授權檢查可能會導致節流。只有在一秒內使用了數百個唯一的搜尋服務資源和服務主體的組合時，才會發生節流。

針對角色型訪問控制問題進行疑難解答

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

如果授權令牌來自受控識別，且最近指派適當的許可權，可能需要數小時的時間，這些許可權指派才會生效。
搜尋服務的預設組態是以金鑰為基礎的驗證。如果您未將預設密鑰設定變更為 [兩者 ] 或 [角色型訪問控制]，則不論基礎許可權為何，都會自動拒絕使用角色型驗證的所有要求。

共用方式為