使用 Azure 基于角色的访问控制 (Azure RBAC) 连接到 Azure 认知搜索

  • 项目

Azure 为平台上运行的所有服务提供一种全局基于角色的访问控制授权系统。 在认知搜索中，可以将 Azure 角色用于：

  • 控制平面操作（通过 Azure 资源管理器执行的服务管理任务）。

  • 数据平面操作，例如创建、加载和查询索引。

不支持按用户访问搜索结果（有时称为行级安全性或文档级安全性）。 一种解决方法是创建安全筛选器，以根据用户标识来精选结果，并删除请求者不应访问的文档。

注意

在认知搜索中，“控制平面”是指管理 REST API 或等效客户端库中支持的操作。 “数据平面”是指针对搜索服务终结点的操作（例如索引编制或查询），或者搜索 REST API 或等效客户端库中指定的任何其他操作。

以下角色是内置角色。 如果这些角色不足以满足要求，请创建自定义角色。

角色 平面 说明
所有者 控制平面和数据平面 对搜索资源的控制平面拥有完全访问权限，包括能够分配 Azure 角色。 只有所有者角色可以启用或禁用身份验证选项或管理其他用户的角色。 默认情况下，订阅管理员是成员。

在数据平面上，此角色具有与搜索服务参与者角色相同的访问权限。 它包括对除了查询文档或编制文档索引之外的所有数据平面操作的访问权限。
参与者 控制平面和数据平面 与所有者相同的控制平面访问权限级别，但无法分配角色或更改身份验证选项。

在数据平面上，此角色具有与搜索服务参与者角色相同的访问权限。 它包括对除了查询文档或编制文档索引之外的所有数据平面操作的访问权限。
读者 控制平面和数据平面 跨整个服务的读取访问权限，包括搜索指标、内容指标（消耗的存储、对象数量）和数据平面资源的对象定义（索引、索引器等）。 但是，它无法读取 API 密钥或读取索引中的内容。
搜索服务参与者 控制平面和数据平面 对对象定义（索引、同义词映射、索引器、数据源和技能组）的读写访问权限。 有关权限列表，请参阅 Microsoft.Search/searchServices/*。 此角色无法访问索引中的内容，因此不会进行查询或索引编制，但它可以创建、删除和列出索引，返回索引定义和统计信息，以及测试分析器。 此角色适用于需要管理搜索服务及其对象但没有内容访问权限的搜索服务管理员。
搜索索引数据参与者 数据 对搜索服务上所有索引中的内容的读写访问权限。 此角色适用于需要导入、刷新或查询索引文档集合的开发人员或索引所有者。
搜索索引数据读取者 数据 对搜索服务上所有搜索索引的只读访问权限。 此角色适用于运行查询的应用和用户。

注意

如果禁用 Azure 基于角色的访问权限，则控制平面的内置角色（所有者、参与者、读取者）将继续可用。 禁用 Azure RBAC 只会删除与这些角色关联的数据相关权限。 在已禁用 RBAC 的场景下，搜索服务参与者等效于控制平面参与者。

限制

  • 采用基于角色的访问控制可能会增大某些请求的延迟。 请求中使用的服务资源（索引、索引器等）和服务主体的每个唯一组合都会触发授权检查。 这些授权检查可能会给请求最多增加 200 毫秒的延迟。

  • 在罕见的情况下，请求源自大量不同的服务主体，而这些服务主体针对不同的服务资源（索引、索引器等），对于这种情况，授权检查可能会导致发生限制。 仅当在一秒钟内使用了搜索服务资源和服务主体的数百个独特组合时，才会发生限制。

为数据平面配置基于角色的访问

适用于：搜索索引数据参与者、搜索索引数据读取者、搜索服务参与者

在此步骤中配置搜索服务，以识别提供 OAuth2 访问令牌的数据请求上的授权头。

  1. 登录到 Azure 门户，然后打开搜索服务页面。

  2. 在左侧导航窗格中，选择“密钥”。

    Screenshot of the keys page with authentication options.

  3. 选择一个 API 访问控制选项。 如果你希望拥有灵活性或需要迁移应用，建议使用“两者”。

    选项 说明
    API 密钥 （默认值）。 需要请求标头中的管理员或查询 API 密钥才能授权。 不使用任何角色。
    基于角色的访问控制 需要角色分配中的成员身份才能完成任务，如下一步所述。 它还需要授权标头。
    两者 使用基于 API 密钥或基于角色的访问控制时，请求都是有效的。

更改会立即生效，但请等待几秒钟，然后再进行测试。

对搜索服务操作和内容的所有网络调用都将遵循你选择的选项：API 密钥、持有者令牌或两者（如果你选择“两者”）。

在门户中启用基于角色的访问控制时，如果授权失败，失败模式将为“http401WithBearerChallenge”。

分配角色

角色分配会在所有工具和客户端库中很普遍的操作，并且会不断累计。 你可以使用 Azure 基于角色的访问控制文档中所述的任何受支持方法分配角色。

必须是所有者或拥有 Microsoft.Authorization/roleAssignments/write 权限才能管理角色分配。

门户中的角色分配是在服务范围内进行的。 如果要向单个索引授予权限，请改为使用 PowerShell 或 Azure CLI。

  1. 登录 Azure 门户。

  2. 导航到你的搜索服务。

  3. 在左侧导航窗格中，选择“访问控制(IAM)”。

  4. 选择“+ 添加” > “添加角色分配”。

    Access control (IAM) page with Add role assignment menu open.

  5. 选择适用的角色：

    • 所有者
    • 参与者
    • 读取器
    • 搜索服务参与者
    • 搜索索引数据参与者
    • 搜索索引数据读取者

  6. 在“成员”选项卡上，选择 Azure AD 用户或组标识。

  7. 在“查看 + 分配”选项卡上，选择“查看 + 分配”，以分配角色 。

测试角色分配

使用客户端测试角色分配。 请记住，角色是累积性的，并且在资源（搜索服务）级别无法删除或拒绝范围限定为订阅或资源组的继承角色。

在测试访问权限之前，请确保将客户端应用程序注册到 Azure Active Directory 并且角色分配已到位。

  1. 登录 Azure 门户。

  2. 导航到你的搜索服务。

  3. 在“概述”页上，选择“索引”选项卡：

    • 参与者可以查看和创建任何对象，但无法使用搜索资源管理器查询索引。

    • 搜索索引数据读取者可以使用搜索资源管理器查询索引。 可以使用任何 API 版本来检查访问权限。 你应该可以发送查询并查看结果，但无法查看索引定义。

    • 搜索索引数据参与者可以选择“新建索引”创建新索引。 保存新索引时会验证对服务的写入访问权限。

作为当前用户进行测试

如果你已经是搜索服务的参与者或所有者，则可为用户标识提供持有者令牌，以便向 Azure 认知搜索进行身份验证。 以下说明介绍了如何设置 Postman 集合，以便以当前用户身份发送请求。

  1. 获取当前用户的持有者令牌：

    az account get-access-token https://search.azure.com/.default

  2. 启动新的 Postman 集合并编辑其属性。 在“变量”选项卡中，创建以下变量：

    变量 说明
    bearerToken （从命令行上的 get-access-token 输出进行复制粘贴）

  3. 在“授权”选项卡中，选择“持有者令牌”作为类型。

  4. 在“令牌”字段中，指定变量占位符 {{bearerToken}}。

  5. 保存集合。

  6. 发送请求以确认访问权限。 下面的这个用于查询 hotels-quickstart 索引：

    POST https://<service-name>.search.azure.cn/indexes/hotels-quickstart/docs/search?api-version=2020-06-30
{
 "queryType": "simple",
 "search": "motel",
 "filter": "",
 "select": "HotelName,Description,Category,Tags",
 "count": true
 }

授予对单个索引的访问权限

在某些情况下，你可能希望限制应用程序对单个资源（如索引）的访问权限。

门户目前不支持此粒度级别的角色分配，但可以使用 PowerShell 或 Azure CLI 实现此操作。

在 PowerShell 中，使用 New-AzRoleAssignment，并提供 Azure 用户或组名称以及分配范围。

  1. 加载 Azure 和 AzureAD 模块并连接到 Azure 帐户：

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

  2. 添加范围限定为单个索引的角色分配：

    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 自定义角色。 支持在搜索服务页从现有角色克隆。

这些步骤将创建一个自定义角色来补充搜索查询权限，以包括按名称列出索引的权限。 通常，列出索引被视为一项管理功能。

  1. 在 Azure 门户中，导航到你的搜索服务。

  2. 在左侧导航窗格中，选择“访问控制(IAM)”。

  3. 在操作栏中，选择“角色”。

  4. 右键单击“搜索索引数据读取者”（或其他角色），然后选择“克隆”打开“创建自定义角色”向导。

  5. 在“基本信息”选项卡上，为自定义角色提供名称（例如“搜索索引数据浏览者”），然后选择“下一步”。

  6. 在“权限”选项卡上，选择“添加权限”。

  7. 在“添加权限”选项卡上，搜索并选择“Microsoft 搜索”磁贴。

  8. 为自定义角色设置权限。 在页面顶部，使用默认的“操作”选项：

    • 在“Microsoft.Search/operations”下，选择“读取: 列出所有可用操作”。
    • 在“Microsoft.Search/searchServices/indexes”下，选择“读取: 读取索引”。

  9. 在同一页上，切换到“数据操作”，然后在“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": []
         }
     ]
   }
 }

  10. 选择“查看 + 创建”以创建角色。 现在可将用户和组分配到该角色。

禁用 API 密钥身份验证

无法删除 API 密钥，但如果使用“搜索服务参与者”、“搜索索引数据参与者”和“搜索索引数据读取者”角色以及 Azure AD 身份验证，则可以对服务禁用这些密钥。 禁用 API 密钥会导致搜索服务拒绝在标头中传递 API 密钥的所有与数据相关的请求。

需要拥有所有者或参与者权限才能禁用功能。

若要禁用基于密钥的身份验证，请使用 Azure 门户或管理 REST API。

  1. 在 Azure 门户中，导航到你的搜索服务。

  2. 在左侧导航窗格中，选择“密钥”。

  3. 选择“基于角色的访问控制”。

更改会立即生效，但请等待几秒钟，然后再进行测试。 假设你有权将角色分配为所有者、服务管理员或共同管理员的成员，则可以使用门户功能来测试基于角色的访问。

条件性访问

条件访问是 Azure Active Directory 中用于强制实施组织策略的工具。 使用条件访问策略，可以在必要时应用适当的访问控制来确保组织的安全。 使用基于角色的访问控制访问 Azure 认知搜索服务时，条件访问可以强制实施组织策略。

若要为 Azure 认知搜索启用条件访问策略，请执行以下步骤：

  1. 登录 Azure 门户。

  2. 搜索“Azure AD 条件访问”。

  3. 选择“策略”。

  4. 选择“+ 新建策略”。

  5. 在策略的“云应用或操作”部分，根据你设置策略的方式，添加“Azure 认知搜索”作为云应用 。

  6. 更新策略的其余参数。 例如，指定要将此策略应用于哪些用户和组。

  7. 保存策略。

重要

如果为搜索服务分配了托管标识，则特定的搜索服务将显示为可在条件访问策略中包含或排除的云应用。 无法对特定的搜索服务强制实施条件访问策略。 应确保选择常规的“Azure 认知搜索”云应用。