配置搜索服务以使用托管标识进行连接

2025-10-16

可以将 Microsoft Entra ID 安全主体和角色分配用于从 Azure AI 搜索到其他 Azure 资源（在索引或查询期间提供数据、应用 AI 或向量化）的出站连接。

若要在出站连接上使用角色，请先将搜索服务配置为使用系统分配的托管标识或用户分配的托管标识作为 Microsoft Entra 租户中搜索服务的安全原则。获得托管标识后，你可以为授权的访问分配角色。使用托管标识和角色分配，便无需在连接字符串或代码中传递机密和凭据。

先决条件

基本层或更高层的搜索服务（任何区域中）。
一种 Azure 资源，用于接受来自具有有效角色分配的 Microsoft Entra 安全主体的传入请求。
若要创建托管标识，你必须是所有者或用户访问管理员角色。若要分配角色，必须是所有者、用户访问管理员、基于角色的访问控制管理员或具有 Microsoft.Authorization/roleAssignments/write 权限的自定义角色的成员。

支持的方案

可以将托管标识用于这些方案。

Scenario	System	用户分配
连接到索引器数据源¹	是的	是 ²
通过技能/向量器 ³ 连接到 Azure OpenAI、Azure AI Foundry 和 Azure Functions 中的嵌入和聊天完成模型	是的	是的
连接到 Azure Key Vault 以获取客户管理的密钥	是的	是的
连接到调试会话（托管在 Azure 存储中）¹	是的	否
连接到知识存储（托管在 Azure 存储中）¹	是的	是 ²

¹ 对于搜索和存储之间的连接，网络安全会对可以使用哪种类型的托管标识施加约束。只有系统托管标识可用于与 Azure 存储的同一区域连接，并且该连接必须通过 受信任的服务异常 或资源实例规则进行。有关详细信息，请参阅访问受网络保护的存储帐户。

² 用户分配的托管标识可用于数据源连接字符串。但是，只有较新的预览版 REST API 和预览包支持连接字符串中用户分配的托管标识。如果将 SearchIndexerDataUserAssignedIdentity 设置为 identity 数据源连接中的预览 API，请务必切换到预览 API。

³ 通过技能/向量器连接到 Azure OpenAI、Azure AI Foundry 和 Azure Functions 包括：自定义技能、自定义向量器、 Azure OpenAI 嵌入技能、 Azure OpenAI 向量器和 Azure AI Foundry 模型目录向量器。

⁴ AI 搜索服务当前无法连接到已关闭共享密钥访问的存储帐户上的表。

创建系统托管标识

系统分配的托管标识是自动创建并链接到 Azure 资源（例如 Azure AI 搜索服务）的Microsoft Entra ID 安全主体。

对于每个搜索服务，可以有一个系统分配的托管标识。它对于搜索服务是唯一的，并绑定到服务的生存期。

启用系统分配的托管标识时，Microsoft Entra ID 会为搜索服务创建一个安全主体，用于向其他 Azure 资源进行身份验证。然后，可以在角色分配中使用此标识来授权访问数据和作。

登录到 Azure 门户并查找你的搜索服务。
在左窗格中，选择 “设置>标识”。
在“系统分配”选项卡上的“状态”下，选择“开”。
选择“保存”。

保存设置后，页面将更新以显示分配给搜索服务的对象标识符。

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

有关详细信息，请参阅使用系统分配的托管标识创建搜索服务 (Azure PowerShell)。

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

有关详细信息，请参阅使用系统分配的托管标识创建搜索服务 (Azure CLI)。

使用服务 - 创建或更新（REST API）来构建请求。

PUT https://management.chinacloudapi.cn/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2025-05-01  HTTP/1.1
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

响应包括系统分配的托管标识的确认和对象标识符。

创建用户分配的托管标识

用户分配的托管标识是一种 Azure 资源，可以限定为订阅、资源组或资源类型。

可以创建多个用户分配的托管身份，以便更精细地进行角色分配。例如，你可能希望针对不同的应用程序和方案使用单独的标识。作为独立创建和管理的资源，它不会绑定到服务本身。

设置用户分配的托管标识的步骤如下：

在 Azure 订阅中，创建用户分配的托管标识。
在搜索服务中，将用户分配的托管标识与搜索服务相关联。
在其他要连接到的 Azure 服务中，为标识创建角色分配。

Azure 门户、搜索管理 REST API 和提供该功能的 SDK 包支持将用户分配的托管标识与 Azure AI 搜索服务相关联。

Azure 门户
REST API

登录到 Azure 门户。
在仪表板的左上角，选择“创建资源”。
使用搜索框查找 用户分配的托管标识，然后选择“ 创建”。
选择订阅、资源组和区域。为标识提供描述性名称。
选择“创建”，并等待资源完成部署。

使用标识前需要几分钟时间。
在搜索服务页上，选择 “设置>标识”。
在“用户分配”选项卡上，选择“添加”。
选择之前创建的订阅和用户分配的托管标识。

可以使用搜索管理 REST API 来分配用户分配的托管标识，而不是 Azure 门户。

使用服务 - 更新（REST API）来构建请求。

PUT https://management.chinacloudapi.cn/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2025-05-01  HTTP/1.1
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[name of resource group]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
    }
  }
}

将 identity.type 设置为身份的类型。
- 有效值为 SystemAssigned、UserAssigned 或 SystemAssigned, UserAssigned，适用于两者。
- 值为 None 会清除搜索服务中先前分配的任何身份。
更新 identity.userAssignedIdentities 以包含用户分配的托管标识的详细信息。必须先存在此标识，然后才能在请求中指定它。

分配角色

获得托管标识后，分配用于确定 Azure 资源的搜索服务权限的角色。

索引器数据连接，以及访问 Azure 密钥保管库中客户管理的密钥都需要读取者权限。
使用 Azure 存储托管调试会话数据、扩充缓存和知识存储中的长期内容存储的 AI 扩充功能需要写入权限。

下面的步骤演示了角色分配的工作流。此示例适用于 Azure OpenAI。对于其他 Azure 资源，请参阅连接到 Azure 存储、连接到 Azure Cosmos DB，或连接到 Azure SQL。

使用 Azure 帐户登录到 Azure 门户，并转到 Azure OpenAI 资源。
在左侧菜单中选择“访问控制”。
依次选择“添加”、“添加角色分配”。
在“工作职能角色”下，选择“认知服务 OpenAI 用户”，然后选择“下一步”。
在“成员”下，选择“托管标识”，然后选择“成员”。
按订阅和资源类型（搜索服务）进行筛选，然后选择搜索服务的托管标识。
选择审核 + 分配。

连接字符串示例

回想一下方案说明，可以在连接字符串中使用托管标识到其他 Azure 资源。本部分提供了示例。可以使用通用的 REST API 版本和 Azure SDK 包通过系统分配的托管标识进行连接。

小窍门

可以在 Azure 门户中创建大部分对象，并指定系统或用户分配的托管标识，然后查看 JSON 定义以获取连接字符串。

下面是各种方案的连接字符串的一些示例。

Blob 数据源（系统托管标识）：

索引器数据源包含一个 credentials 属性，用于确定如何与数据源建立连接。以下示例显示了一个连接字符串，该字符串指定存储帐户的唯一资源 ID。

当连接字符串是 Microsoft Entra ID 感知服务或应用程序的唯一资源 ID 时，将指示系统管理标识。用户分配的托管标识是通过属性 identity 指定的。

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Blob 数据源（用户托管标识）：

用户分配的托管标识也可以在索引器数据源连接字符串中使用。但是，只有较新的预览版 REST API 和预览包支持数据源连接字符串中用户分配的托管标识。如果将 SearchIndexerDataUserAssignedIdentity 设置为数据源连接中的标识，请务必切换到预览版。

在属性中 identity 指定了搜索服务用户标识。

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

知识存储：

知识存储定义包括到 Azure 存储的连接字符串。此连接字符串是存储帐户的唯一资源 ID。请注意，该字符串没有在路径中包括容器或表。它们是在嵌入的投影定义中定义的，而不是在连接字符串中定义的。

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}

扩充缓存：

索引器创建、使用并记住用于缓存扩充的容器。没有必要在缓存连接字符串中包括容器。可以在 Azure 门户中搜索服务的“标识”页上查找对象 ID。

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

调试会话：

调试会话在 Azure 门户中运行，并且在你启动该会话时，它会使用连接字符串。你可以粘贴类似于以下示例的字符串。

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

自定义技能：

自定义技能面向托管自定义代码的 Azure 函数或应用的终结点。

uri 是函数或应用的终结点。
authResourceId 可使搜索服务使用托管标识进行连接，并在属性中传递目标函数或应用的应用程序 ID。

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

模型的连接示例

对于使用托管标识建立的连接，本部分显示了搜索服务用于连接到另一个资源上的模型的连接信息的示例。通过系统托管标识建立的连接是透明的;标识和角色已到位，如果正确配置连接，则连接会成功。相比之下，用户托管标识需要额外的连接属性。

Azure OpenAI 嵌入技能和 Azure OpenAI 矢量器：

AI 搜索中的 Azure OpenAI 嵌入技能和矢量器以托管嵌入模型的 Azure OpenAI 的终结点为目标。终结点在 Azure OpenAI 嵌入技能定义和/或 Azure OpenAI 矢量器定义中进行指定。

如果 "apikey" 和 "authIdentity" 为空，将自动使用系统托管标识，如以下示例所示。 "authIdentity" 属性仅用于用户分配的托管标识。

系统托管标识示例：

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

下面是为系统分配的托管标识配置的向量器示例。向量器会在搜索索引中指定。

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
      }
    }
  ]

用户分配的托管标识示例：

如果 "apiKey" 为空并且提供了有效的 "authIdentity"，则使用用户分配的托管标识。

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ],
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
   }
}

下面是为用户分配的托管标识配置的向量器示例。向量器会在搜索索引中指定。

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
        "authIdentity": {
            "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
            "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
          }
      }
    }
  ]

检查防火墙访问

如果你的 Azure 资源位于防火墙后面，请确保有一个入站规则来接受来自你的搜索服务和来自 Azure 门户的请求。

对于与 Azure Blob 存储或 Azure Data Lake Storage Gen2 的同区域连接，请使用托管标识和受信任的服务异常。（可选）可以配置资源实例规则来允许请求。
对于所有其他资源和连接，配置 IP 防火墙规则来接受来自 Azure AI 搜索的请求。有关详细信息，请参阅索引器访问受 Azure 网络安全功能保护的内容。

Compartir a través de