在 Azure 认知搜索中使用 Azure 基于角色的访问控制 (Azure RBAC)

Azure 为平台上运行的所有服务提供全局的基于角色的访问控制 (RBAC) 授权系统。 在认知搜索中,可以:

  • 使用正式版角色进行服务管理。

  • 将新的预览角色用于数据请求,包括创建、加载和查询索引。

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

内置角色包括正式发布和预览角色。 如果这些角色不足以满足要求,请创建自定义角色

角色 说明和可用性
所有者 (正式发布)对搜索资源拥有完全访问权限,包括能够分配 Azure 角色。 默认情况下,订阅管理员是成员。

(预览版)此角色与数据平面上的搜索服务参与者角色具有相同的访问权限。 它包括对所有数据平面操作的访问权限,但查询搜索索引或索引文档的能力除外。
参与者 (正式发布)访问权限级别与所有者相同,但无法分配角色或更改授权选项。

(预览版)此角色与数据平面上的搜索服务参与者角色具有相同的访问权限。 它包括对所有数据平面操作的访问权限,但查询搜索索引或索引文档的能力除外。
读者 (正式发布)对部分服务信息拥有有限访问权限。 在门户中,读取者角色可以访问服务“概述”页、“概要”部分和“监视”选项卡中的信息。在所有其他选项卡和页面中的访问权限受限制。

此角色有权访问服务信息:服务名称、资源组、服务状态、位置、订阅名称和 ID、标记、URL、定价层、副本、分区和搜索单位。 此角色还有权访问服务指标:搜索延迟、受限制请求百分比、每秒平均查询数。

此角色不支持访问 API 密钥、角色分配、内容(索引或同义词映射)或内容指标(存储消耗量、对象数)。

(预览)为数据平面启用 RBAC 预览时,读者角色在整个服务中具有读取访问权限。 这样便可以读取搜索指标、内容指标(使用的存储空间、对象数),以及数据平面资源的定义(索引、索引器等)。 读者角色仍无权读取 API 密钥或读取索引中的内容。
搜索服务参与者 (正式版)此角色与参与者角色相同,适用于控制平面操作。

(预览版)当你为数据平面启用 RBAC 预览版时,此角色还会提供对 Microsoft.Search/searchServices/* 定义的索引、同义词映射、索引器、数据源和技能组执行所有操作的完全访问权限。 此角色不允许你访问查询搜索索引或索引文档。 此角色适用于需要管理搜索服务及其对象但无法查看或访问对象数据的搜索服务管理员。

与参与者一样,此角色的成员无法创建或管理角色分配,也无法更改授权选项。 若要使用此角色的预览版功能,必须按本文中所述为服务启用预览版功能。
搜索索引数据参与者 (预览版)提供对搜索服务中所有索引内容的完全数据平面访问权限。 此角色适用于需要导入、刷新或查询索引文档集合的开发人员或索引所有者。
搜索索引数据读取者 (预览版)提供对搜索服务中搜索索引的只读数据平面访问权限。 此角色适用于运行查询的应用和用户。

注意

Azure 资源具有控制平面和数据平面操作类别的概念。 在认知搜索中,“控制平面”是指管理 REST API 或等效客户端库中支持的任何操作。 “数据平面”是指针对搜索服务终结点的操作(例如索引编制或查询),或者搜索 REST API 或等效客户端库中指定的任何其他操作。

预览功能和限制

  • 针对数据平面操作(例如创建索引或查询索引)的基于角色的访问控制目前以公共预览版提供,使用此功能需要遵守补充使用条款

  • 使用 Azure RBAC 预览版没有任何区域、层或定价限制,但搜索服务必须位于 Azure 公有云中。 预览版不适用于 Azure 中国云、Azure 德国或 Azure 中国世纪互联。

  • 如果将 Azure 订阅迁移到新租户,则需要重新启用 RBAC 预览版。

  • 采用 Azure RBAC 可能会增大某些请求的延迟。 请求中使用的服务资源(索引、索引器等)和服务主体的每个唯一组合都会触发授权检查。 这些授权检查可能会给请求最多增加 200 毫秒的延迟。

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

注册预览版

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

新的内置预览角色授予对搜索服务上内容的权限。 尽管内置角色在 Azure 门户中始终可见,但需要完成预览版注册,这些角色才能起作用。

  1. 打开 Azure 门户并找到你的搜索服务。

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

  3. 在提到预览版的蓝色横幅中,选择“注册”,将该功能添加到订阅。

    显示如何在门户中注册 rbac 预览版的屏幕截图

此外,还可使用 Azure 功能公开控制 (AFEC) 并搜索针对搜索服务的基于角色的访问控制(预览版)来注册预览版。

注意

将预览版添加到订阅后,订阅中的所有服务都将永久注册到预览版中。 如果你不想要针对给定服务使用 RBAC,可按后一部分中所述,为数据平面操作禁用 RBAC。

为数据平面操作启用 RBAC 预览版

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

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

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

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

  3. 选择“API 访问控制”机制。

    选项 状态 说明
    API 密钥 正式发布(默认) 需要请求标头中的管理员或查询 API 密钥才能授权。 不使用任何角色。
    基于角色的访问控制 预览 需要角色分配中的成员身份才能完成任务,如下一步所述。 它还需要授权标头。 选择此选项会限制为支持 2021-04-30-preview REST API 的客户端。
    两者 预览 请求使用 API 密钥或授权令牌都有效。

如果无法保存所做的选择,或者收到“无法更新搜索服务 <name> 的 API 访问控制。 DisableLocalAuth 为预览版且未为此订阅启用”,则表示你的订阅注册尚未启动或尚未处理。

分配角色

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

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

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

  1. 打开 Azure 门户

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

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

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

    打开了“添加角色分配”菜单的“访问控制(IAM)”页。

  5. 选择适用的角色:

    • 所有者
    • 参与者
    • 读者
    • 搜索服务参与者(数据平面请求的预览版)
    • 搜索索引数据参与者(预览版)
    • 搜索索引数据读取者(预览版)
  6. 在“成员”选项卡上,选择 Azure AD 用户或组标识。

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

测试角色分配

  1. 打开 Azure 门户

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

  3. 在“概述”页上,选择“索引”选项卡:

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

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

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

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

门户目前不支持此粒度级别的角色分配,但可以使用 PowerShellAzure 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 密钥,使搜索服务拒绝所有在内容相关请求的头中传递 API 密钥的数据相关请求。

若要禁用基于密钥的身份验证,请使用管理 REST API 版本 2021-04-01-Preview 并对更新服务发送两个连续请求。

需要拥有所有者或参与者权限才能禁用功能。 使用 Postman 或其他 Web 测试工具完成以下步骤(参阅下面的“提示”):

  1. 在第一个请求上,将“AuthOptions”设置为“aadOrApiKey”以启用 Azure AD 身份验证。 请注意,选项指示了以下任一方法的可用性:Azure AD 或本机 API 密钥。

    PUT https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-Preview
    {
      "location": "{{region}}",
      "sku": {
        "name": "standard"
      },
      "properties": {
        "authOptions": {
          "aadOrApiKey": {
            "aadAuthFailureMode": "http401WithBearerChallenge"
          }
        }
      }
    }
    
  2. 在第二个请求上,将“disableLocalAuth”设置为 true。 此步骤将关闭“aadOrApiKey”选项的 API 密钥部分,只留下 Azure AD 身份验证。

    PUT https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-Preview
    {
      "location": "{{region}}",
      "sku": {
        "name": "standard"
      },
      "properties": {
        "disableLocalAuth": true
      }
    }
    

不能将步骤 1 和 2 结合使用。 在步骤 1 中,“disableLocalAuth”必须为 false 以符合“AuthOptions”的设置要求,而步骤 2 将该值更改为 true。

若要重新启用密钥身份验证,请重新运行最后一个请求,并将“disableLocalAuth”设置为 false。 搜索服务将自动继续接受请求上的 API 密钥(假设已指定)。

提示

将会通过 Azure Active Directory 对管理 REST API 调用进行身份验证。 有关设置安全主体和请求的指导,请参阅博客文章:Azure REST APIs with Postman (2021)(通过 Postman 使用 Azure REST API(2021 年))。 已使用该博客文章中提供的说明和 Postman 集合对前面的示例进行了测试。

条件性访问

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

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

  1. 登录 Azure 门户。

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

  3. 选择“策略”。

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

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

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

  7. 保存策略。

重要

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