使用 Azure 角色型存取控制連線至 Azure AI 搜尋服務（Azure RBAC）

發行項
03/19/2024

Azure 為平台上執行的所有服務提供全域角色型訪問控制授權系統。在 Azure AI 搜尋中，您可以使用 Azure 角色來執行下列工作：

控制平面作業（透過 Azure Resource Manager 的服務管理工作）。
數據平面作業，例如建立、載入和查詢索引。

不支援對搜尋結果的個別使用者存取（有時稱為數據列層級安全性或檔層級安全性）。因應措施是建立安全性篩選條件，以依使用者身分識別修剪結果，移除要求者不應該具有存取權的檔。

注意

在 Azure AI 搜尋中，「控制平面」是指管理 REST API 或對等用戶端連結庫所支持的作業。「數據平面」是指針對搜尋服務端點的作業，例如索引編製或查詢，或是搜尋 REST API 或對等用戶端連結庫中所指定的任何其他作業。

搜尋中使用的內建角色

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

角色	平面	描述
負責人	控制與數據	完整存取搜尋資源的控制平面，包括指派 Azure 角色的能力。只有擁有者角色可以啟用或停用驗證選項，或管理其他使用者的角色。訂用帳戶管理員預設為成員。在數據平面上，此角色具有與搜尋服務參與者角色相同的存取權。它包含存取所有數據平面動作，但查詢或編製檔索引的能力除外。
參與者	控制與數據	與擁有者相同的控制平面存取層級，減去指派角色或變更驗證選項的能力。在數據平面上，此角色具有與搜尋服務參與者角色相同的存取權。它包含存取所有數據平面動作，但查詢或編製檔索引的能力除外。
讀取者	控制與數據	讀取整個服務的存取權，包括搜尋計量、內容計量（已取用的記憶體、物件數目），以及數據平面資源的物件定義（索引、索引器等等）。不過，它無法在索引內讀取 API 金鑰或讀取內容。
搜尋服務參與者	控制與數據	物件定義的讀寫存取權（索引、同義字對應、索引器、數據源和技能集）。如需權限清單，請參閱 `Microsoft.Search/searchServices/*` 。此角色無法存取索引中的內容，因此沒有查詢或編製索引，但可以建立、刪除和列出索引、傳回索引定義和統計數據，以及測試分析器。此角色適用於需要管理搜尋服務及其物件的搜尋服務管理員，但不需要內容存取。
搜尋索引數據參與者	資料	對搜尋服務上所有索引中內容的讀寫存取權。此角色適用於需要匯入、重新整理或查詢索引檔集合的開發人員或索引擁有者。
搜尋索引數據讀取器	資料	對搜尋服務上所有搜尋索引的唯讀存取權。這個角色適用於執行查詢的應用程式和使用者。

注意

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

限制

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

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

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

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

Azure 入口網站
REST API

登入 Azure 入口網站並開啟搜尋服務頁面。
選取 左側瀏覽窗格中的 [金鑰 ]。

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

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

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

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

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

使用管理 REST API 建立或更新服務，為您的服務設定角色型訪問控制。

所有對管理 REST API 的呼叫都會透過 Microsoft Entra 識別碼進行驗證，並具有參與者或擁有者許可權。如需設定已驗證要求的說明，請參閱使用 REST 管理 Azure AI 搜尋。

取得服務設定，以便檢閱目前的組態。

GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01

使用 PATCH 更新服務組態。下列修改可啟用金鑰和角色型存取。如果您想要僅限角色的設定，請參閱停用 API 金鑰。

在 [屬性] 底下，將 “authOptions” 設定為 “aadOrApiKey”。 “disableLocalAuth” 屬性必須是 false，才能設定 “authOptions”。

選擇性地設定「aadAuthFailureMode」，以指定驗證失敗時是否傳回 401 而不是 403。有效值為「HTTP401WithBearerChallenge」或「HTTP403」。。
```
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
    "properties": {
        "disableLocalAuth": false,
        "authOptions": {
            "aadOrApiKey": {
                "aadAuthFailureMode": "http401WithBearerChallenge"
            }
        }
    }
}
```
遵循下一個步驟中的指示，為數據平面作業指派角色。

指派角色

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

您必須是 擁有者 或擁有 Microsoft.Authorization/roleAssignments/write 許可權，才能管理角色指派。

Azure 入口網站
PowerShell

入口網站中的角色指派是全服務。如果您想要將許可權授與單一索引，請改用 PowerShell 或 Azure CLI。

登入 Azure 入口網站。
瀏覽至您的搜尋服務。
在左側瀏覽窗格中選取 [存取控制 [IAM]。
選取 [+新增]>[新增角色指派]。
選取適用的角色：
- 擁有者
- 參與者
- 讀取者
- 搜尋服務參與者
- 搜尋索引數據參與者
- 搜尋索引數據讀取器
在 [ 成員] 索引標籤上，選取 [Microsoft Entra 使用者或群組身分識別]。
在 [檢閱 + 指派] 索引標籤上，選取 [檢閱 + 指派] 以指派角色。

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

開始之前，請務必載入 Az 和 AzureAD 模組並連線至 Azure：

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

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

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>"

回想一下，您只能限制最上層資源的存取範圍，例如索引、同義字對應、索引器、數據源和技能集。您無法使用 Azure 角色控制搜尋檔（索引內容）的存取權。

測試角色指派

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

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

登入 Azure 入口網站。
瀏覽至您的搜尋服務。
在 [概觀] 頁面上，選取 [ 索引] 索引卷 標：
- 參與者可以檢視及建立任何物件，但無法使用搜尋總管查詢索引。
- 搜尋索引數據讀取器可以使用搜尋總管來查詢索引。您可以使用任何 API 版本來檢查存取權。您應該能夠傳送查詢和檢視結果，但不應該能夠檢視索引定義。
- 搜尋索引數據參與者可以選取 [ 新增索引 ] 來建立新的索引。儲存新的索引會驗證服務的寫入許可權。

此方法假設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 套件。
使用適用於 .NET 的 Azure.Identity 進行令牌驗證。 Microsoft 建議 DefaultAzureCredential() 在大部分情況下使用。
- 取得 OAuth 令牌時，範圍為 “https://search.azure.com/.default"。 SDK 需要物件為 “https://search.azure.com" ;。 “.default” 是 Microsoft Entra 慣例。
- SDK 會驗證使用者具有「user_impersonation」範圍，必須由您的應用程式授與，但 SDK 本身只會要求「https://search.azure.com/.default"」。

以下是使用 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）。
使用適用於 Python 的 Azure.Identity 進行令牌驗證。
如果 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://graph.microsoft.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/a5b1ca8b-bab3-4c26-aebe-4cf7ec4791a0/resourceGroups/heidist-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"。

停用 API 金鑰驗證

如果您使用搜尋服務參與者、搜尋索引數據參與者，以及搜尋索引數據讀取者角色和 Microsoft Entra 驗證，則可以在您的服務上停用密鑰存取或本機驗證。停用 API 金鑰會導致搜尋服務拒絕在標頭中傳遞 API 金鑰的所有資料相關要求。

注意

管理員 API 金鑰只能停用，無法刪除。您可以刪除查詢 API 金鑰。

需要擁有者或參與者許可權才能停用功能。

若要停用金鑰型驗證，請使用 Azure 入口網站或管理 REST API。

入口網站
REST API

在 Azure 入口網站中，流覽至您的搜尋服務。
在左側瀏覽窗格中，選取 [金鑰]。
選取 [角色型訪問控制]。

變更會立即生效，但在測試之前請稍候幾秒鐘。假設您有權將角色指派為擁有者、服務管理員或共同管理員的成員，您可以使用入口網站功能來測試角色型存取。

若要停用密鑰型驗證，請將「disableLocalAuth」設定為 true。

取得服務設定，以便檢閱目前的組態。

GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01

使用 PATCH 更新服務組態。下列修改會將「authOptions」設定為 null。

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
    "properties": {
        "disableLocalAuth": true
    }
}

僅包含 API 金鑰且沒有持有人令牌的要求會失敗，並產生 HTTP 401。

若要重新啟用密鑰驗證，請重新執行最後一個要求，將「disableLocalAuth」設定為 false。搜尋服務會自動在要求上繼續接受 API 金鑰（假設已指定它們）。

條件式存取

條件式存取是 Microsoft Entra ID 中用來強制執行組織原則的工具。藉由使用條件式存取原則，您可以視需要套用正確的訪問控制，以確保組織的安全。使用角色型訪問控制存取 Azure AI 搜尋服務時，條件式存取可以強制執行組織原則。

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

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

重要

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

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

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

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

使用 Azure 角色型存取控制 連線 至 Azure AI 搜尋服務 （Azure RBAC）