你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

在 Azure AI 搜索中启用或禁用基于角色的访问控制

Azure AI 搜索默认使用基于密钥的身份验证,但它通过 Azure 基于角色的访问控制 (RBAC) 完全支持所有控制平面和数据平面操作的 Microsoft Entra ID 身份验证和授权。

在分配角色以对 Azure AI 搜索进行授权的数据平面访问之前,必须在搜索服务上启用基于角色的访问控制。 服务管理(控制平面)的角色是内置的,无法启用或禁用。

注意

“数据平面”是指针对搜索服务终结点的操作(例如索引编制或查询),或者是指搜索服务 REST API 或等效 Azure SDK 客户端库中指定的任何其他操作。 “控制平面”是指 Azure 资源管理,例如创建或配置搜索服务

先决条件

为数据平面操作启用基于角色的访问

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

为数据平面启用角色时,更改会立即生效,但请等待几秒钟,然后再分配角色。

未经授权的请求的默认失败模式为 http401WithBearerChallenge。 或者,可以将失败模式设置为 http403

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

  2. 选择“设置”,然后在左侧导航窗格中选择“键”。

    包含身份验证选项的密钥页的屏幕截图。

  3. 如果当前使用的是密钥,并且需要时间将客户端转换为基于角色的访问控制,请选择“基于角色的控制”或“两者”

    选项 说明
    API 密钥 (默认值)。 需要用请求标头上的 API 密钥进行授权。
    基于角色的访问控制 需要是角色分配中的成员才能完成任务, 还需要请求上的授权标头。
    推送、请求和匿名 使用 API 密钥或基于角色的访问控制的请求均有效,但如果在同一请求中提供这两种方式,则使用 API 密钥。
  4. 作为管理员,如果你选择仅限角色的方法,请为用户帐户分配数据平面角色,以还原对 Azure 门户中数据平面操作的完全管理访问权限。 角色包括搜索服务参与者、搜索索引数据参与者和搜索索引数据读取者。 如果需要等效的访问权限,则需要前两个角色。

    有时,角色分配可能需要五到十分钟才能生效。 在此之前,用于数据平面操作的 Azure 门户页面中会出现以下消息。

    指出权限不足的门户消息的屏幕截图。

禁用基于角色的访问控制

可以禁用数据平面操作的基于角色的访问控制,并改用基于密钥的身份验证。 可以在测试工作流中执行此操作,例如排除权限问题。

倒过来完成前面执行的步骤以启用基于角色的访问。

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

  2. 选择“设置”,然后在左侧导航窗格中选择“键”。

  3. 选择 API 密钥

禁用 API 密钥身份验证

如果专用于使用内置角色和Microsoft Entra 身份验证,则可以在服务上禁用密钥访问或本地身份验证。 禁用 API 密钥会导致搜索服务拒绝在标头中传递 API 密钥的所有与数据相关的请求。

可以禁用管理员 API 密钥,但不能删除。 可以删除查询 API 密钥。

禁用安全功能需要所有者或参与者权限。

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

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

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

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

基于角色的访问控制的影响

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

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

后续步骤