使用角色連線到 Azure AI 搜尋

發行項
06/30/2024

Azure 會針對平台上執行的所有服務，提供全域驗證和角色型授權系統。在 Azure AI 搜尋服務中，您可以針對下列項目指派 Azure 角色：

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

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

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

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

必要條件

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

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

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

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

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

注意

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

指派角色

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

服務管理

角色識別碼

Owner 8e3af657-a8ff-443c-a75c-2fe8c4bcb635

Contributor b24988ac-6180-42a0-ab88-20f7382dd24c

Reader acdd72a7-3385-48ef-bd42-f606fba81ae7

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

搜尋服務的開發或寫入存取

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

查詢的唯讀存取

角色識別碼

Search Index Data Reader with PowerShell 1407120a-92aa-4202-b7e9-c0e197c71c8f

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

指派服務管理的角色

身為服務管理員，您可以建立及設定搜尋服務，並執行管理 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 來建立自訂角色。

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

重要

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

Azure 入口網站
PowerShell

登入 Azure 入口網站。
瀏覽至您的搜尋服務。
在左側導覽窗格中選取 [存取控制 (IAM)]。
選取 [+新增]>[新增角色指派]。
選取角色：
- 搜尋服務參與者 (索引、索引子、技能集和其他最上層物件的建立、讀取、更新、刪除作業)
- 搜尋索引資料參與者 (載入文件並執行編製索引工作)
- 搜尋索引資料讀取者 (查詢索引)
提供完整存取權的另一個角色組合是 [參與者] 或 [擁有者]，以及 [搜尋索引資料讀取者]。
在 [成員] 索引標籤上，選取 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 AI 搜尋 (不需金鑰) 以取得設定應用程式進行角色型存取的完整指示。

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

測試角色指派

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

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

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

此方法假設 Visual Studio Code 具有 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 毫秒的延遲。
在少數情況下，其中的要求源自大量不同的服務主體，都以不同服務資源為目標 (索引、索引子等)，授權檢查可能會導致節流。只有在一秒內使用了數百個唯一的搜尋服務資源和服務主體的組合時，才會發生節流。

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

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

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

共用方式為

使用角色連線到 Azure AI 搜尋

必要條件

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

指派角色

指派服務管理的角色

指派用於開發的角色

為唯讀查詢指派角色

測試角色指派

以目前使用者的身分測試

授與單一索引的存取權

建立自訂角色

條件式存取

限制

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

意見反應

意見反應

其他資源