IP 访问列表IP access lists

备注

该功能需要 Azure Databricks Premium 计划This feature requires the Azure Databricks Premium Plan.

使用云 SaaS 应用程序的安全意识较强的企业需要限制其员工的访问权限。Security-conscious enterprises that use cloud SaaS applications need to restrict access to their own employees. 身份验证有助于证明用户身份,但对用户的网络位置并没有强制要求。Authentication helps to prove user identity, but that does not enforce network location of the users. 从不安全的网络访问云服务会给企业带来安全风险,尤其是在用户可能已获得授权访问敏感数据或个人数据的情况下。Accessing a cloud service from an unsecured network can pose security risks to an enterprise, especially when the user may have authorized access to sensitive or personal data. 企业网络外围应用安全策略,并限制对外部服务(例如防火墙、代理、DLP 和日志记录)的访问,因此超出这些控制的访问被视为是不可信的。Enterprise network perimeters apply security policies and limit access to external services (for example, firewalls, proxies, DLP, and logging), so access beyond these controls are assumed to be untrusted.

例如,假设一名医院员工访问 Azure Databricks 工作区。For example, suppose a hospital employee accesses an Azure Databricks workspace. 如果该员工从办公室前往了一家咖啡店,则即使该员工具有访问 Web 应用程序和 REST API 的正确凭据,医院仍可阻止与 Azure Databricks 工作区的连接。If the employee walks from the office to a coffee shop, the hospital can block connections to the Azure Databricks workspace even if the customer has correct credentials to access the web application and the REST API.

可以配置 Azure Databricks 工作区,以便员工只通过具有安全外围的现有企业网络连接到服务。Azure Databricks workspaces can be configured so that employees connect to the service only through existing corporate networks with a secure perimeter. Azure Databricks 客户可以使用 IP 访问列表功能来定义一组已批准的 IP 地址。Azure Databricks customers can use the IP access lists feature to define a set of approved IP addresses. 对 Web 应用程序和 REST API 的所有传入访问都要求用户从已授权的 IP 地址进行连接。All incoming access to the Web application and REST APIs requires the user connect from an authorized IP address.

对于远程办公或出差的员工而言,他们可以使用 VPN 连接到公司网络,从而实现对工作区的访问。For employees who are remote or travelling, employees could use VPN to connect to the corporate network, which in turn enables access to the workspace. 对于上一个示例,医院可以允许员工在咖啡店中使用 VPN 来访问 Azure Databricks 工作区。Using the previous example, the hospital could allow an employee to use a VPN from the coffee shop to access the Azure Databricks workspace.

IP 访问列表概述关系图IP access lists overview diagram

灵活配置Flexible configuration

IP 访问列表功能非常灵活:The IP access lists feature is flexible:

  • 你自己的工作区管理员控制公共 Internet 上允许访问的 IP 地址集。Your own workspace administrators control the set of IP addresses on the public Internet that are allowed access. 这就是所谓的允许列表。This is known as the allow list. 显式地或以整个子网(例如 216.58.195.78/28)的形式允许多个 IP 地址。Allow multiple IP addresses explicitly or as entire subnets (for example 216.58.195.78/28).
  • 工作区管理员可以选择性地指定要阻止的 IP 地址或子网,即使它们包含在允许列表中也是如此。Workspace administrators can optionally specify IP addresses or subnets to block even if they are included in the allow list. 这就是所谓的阻止列表。This is known as the block list. 如果允许的 IP 地址范围包括较小范围的基础结构 IP 地址(这些地址实际上超出了实际的安全网络外围),则可以使用此功能。You might use this feature if an allowed IP address range includes a smaller range of infrastructure IP addresses that in practice are outside the actual secure network perimeter.
  • 工作区管理员使用 REST API 来更新允许和阻止的 IP 地址和子网的列表。Workspace administrators use REST APIs to update the list of allowed and blocked IP addresses and subnets.

功能详细信息 Feature details

利用 IP 访问列表 API,Azure Databricks 管理员可以为工作区配置 IP 允许列表和阻止列表。The IP Access List API enables Azure Databricks admins to configure IP allow lists and block lists for a workspace. 如果对工作区禁用了该功能,则允许所有访问。If the feature is disabled for a workspace, all access is allowed. 支持允许列表(包含)和阻止列表(排除)。There is support for allow lists (inclusion) and block lists (exclusion).

尝试连接时:When a connection is attempted:

  1. 首先,检查所有阻止列表。First all block lists are checked. 如果连接 IP 地址与任何阻止列表匹配,则连接将被拒绝。If the connection IP address matches any block list, the connection is rejected.

  2. 如果连接未被阻止列表拒绝,则 IP 地址将与允许列表进行比较。If the connection was not rejected by block lists, the IP address is compared with the allow lists. 如果工作区至少有一个允许列表,则仅当 IP 地址与一个允许列表匹配时,才允许连接。If there is at least one allow list for the workspace, the connection is allowed only if the IP address matches an allow list. 如果工作区没有允许列表,则允许所有 IP 地址。If there are no allow lists for the workspace, all IP addresses are allowed.

对于所有合并的允许列表和阻止列表,工作区最多支持 1000 个 IP/CIDR 值,其中一个 CIDR 作为单个值计数。For all allow lists and block lists combined, the workspace supports a maximum of 1000 IP/CIDR values, where one CIDR counts as a single value.

更改 IP 访问列表功能后,可能需要几分钟更改才能生效。After changes to the IP access list feature, it can take a few minutes for changes to take effect.

IP 访问列表流关系图IP access list flow diagram

如何使用 IP 访问列表 APIHow to use the IP access list API

本文介绍可以通过该 API 执行的最常见任务。This article discusses the most common tasks you can perform with the API. 有关完整的 REST API 参考,请下载 OpenAPI 规范并直接或使用读取 OpenAPI 3.0 的应用程序查看它。For the complete REST API reference, download the OpenAPI spec and view it directly or using an application that reads OpenAPI 3.0.

若要了解对 Azure Databricks API 的身份验证,请参阅使用 Azure Databricks 个人访问令牌进行身份验证To learn about authenticating to Azure Databricks APIs, see Authentication using Azure Databricks personal access tokens.

本文中所述的终结点的基路径为 https://<databricks-instance>/api/2.0,其中 <databricks-instance> 是 Azure Databricks 部署的 adb-<workspace-id>.<random-number>.databricks.azure.cn 域名。The base path for the endpoints described in this article is https://<databricks-instance>/api/2.0, where <databricks-instance> is the adb-<workspace-id>.<random-number>.databricks.azure.cn domain name of your Azure Databricks deployment.

检查工作区是否启用了 IP 访问列表功能Check if your workspace has the IP access list feature enabled

若要检查工作区是否启用了 IP 访问列表功能,请调用获取功能状态 API (GET /workspace-conf)。To check if your workspace has the IP access list feature enabled, call the get feature status API (GET /workspace-conf). keys=enableIpAccessLists 作为参数传递到请求。Pass keys=enableIpAccessLists as arguments to the request.

在响应中,enableIpAccessLists 字段指定 truefalseIn the response, the enableIpAccessLists field specifies either true or false.

例如:For example:

curl -X -n \
 https://<databricks-instance>/api/2.0/workspace-conf?keys=enableIpAccessLists

示例响应:Example response:

{
  "enableIpAccessLists": "true",
}

启用或禁用工作区的 IP 访问列表功能Enable or disable the IP access list feature for a workspace

若要启用或禁用工作区的 IP 访问列表功能,请调用启用或禁用 IP 访问列表 API (PATCH /workspace-conf)。To enable or disable the IP access list feature for a workspace, call the enable or disable the IP access list API (PATCH /workspace-conf).

在 JSON 请求正文中,将 enableIpAccessLists 指定为 true(已启用)或 false(已禁用)。In a JSON request body, specify enableIpAccessLists as true (enabled) or false (disabled).

例如,启用该功能:For example, to enable the feature:

curl -X PATCH -n \
  https://<databricks-instance>/api/2.0/workspace-conf \
  -d '{
    "enableIpAccessLists": "true"
    }'

示例响应:Example response:

{
  "enableIpAccessLists": "true"
}

添加 IP 访问列表Add an IP access list

若要添加 IP 访问列表,请调用添加 IP 访问列表 API (POST /ip-access-lists)。To add an IP access list, call the add an IP access list API (POST /ip-access-lists).

在 JSON 请求正文中,指定:In the JSON request body, specify:

  • label - 此列表的标签。label — Label for this list.
  • list_type - ALLOW(允许列表)或 BLOCK(阻止列表,这意味着即使在允许列表中也要排除)。list_type — Either ALLOW (allow list) or BLOCK (a block list, which means exclude even if in allow list).
  • ip_addresses - 一个 IP 地址和 CIDR 范围的 JSON 数组,作为字符串值。ip_addresses — A JSON array of IP addresses and CIDR ranges, as String values.

响应是你传入的对象的副本,但带有一些其他字段,最重要的是 list_id 字段。The response is a copy of the object that you passed in, but with some additional fields, most importantly the list_id field. 你可能希望保存该值,以便之后可以更新或删除列表。You may want to save that value so you can update or delete the list later. 如果你不保存它,稍后仍可以通过对 /ip-access-lists 终结点的 GET 请求来查询完整的 IP 访问列表集,从而获取该 ID。If you do not save it, you are still able to get the ID later by querying the full set of IP access lists with a GET request to the /ip-access-lists endpoint.

例如,添加允许列表:For example, to add an allow list:

curl -X POST -n \
  https://<databricks-instance>/api/2.0/ip-access-lists
  -d '{
    "label": "office",
    "list_type": "ALLOW",
    "ip_addresses": [
        "1.1.1.1",
        "2.2.2.2/21"
      ]
    }'

示例响应:Example response:

{
  "ip_access_list": {
    "list_id": "<list-id>",
    "label": "office",
    "ip_addresses": [
        "1.1.1.1",
        "2.2.2.2/21"
    ],
    "address_count": 2,
    "list_type": "ALLOW",
    "created_at": 1578423494457,
    "created_by": 6476783916686816,
    "updated_at": 1578423494457,
    "updated_by": 6476783916686816,
    "enabled": true
  }
}

若要添加阻止列表,请执行相同的操作,但请将 list_type 设置为 BLOCKTo add a block list, do the same thing but with list_type set to BLOCK.

更新 IP 访问列表Update an IP access list

若要更新 IP 访问列表,请调用更新 IP 访问列表 API (PUT /ip-access-lists/<list-id>)。To update an IP access list, call the update an IP access list API (PUT /ip-access-lists/<list-id>).

在 JSON 请求正文中,指定:In the JSON request body, specify:

  • label - 此列表的标签。label — Label for this list.
  • list_type - ALLOW(允许列表)或 BLOCK(阻止列表,这意味着即使在允许列表中也要排除)。list_type — Either ALLOW (allow list) or BLOCK (block list, which means exclude even if in allow list).
  • ip_addresses - 一个 IP 地址和 CIDR 范围的 JSON 数组,作为字符串值。ip_addresses — A JSON array of IP addresses and CIDR ranges, as String values.
  • enabled - 指定是否启用了该列表。enabled — Specifies whether this list is enabled. 传递 truefalsePass true or false.

响应是你传入的对象的副本,其中包含其他的 ID 和修改日期字段。The response is a copy of the object that you passed in with additional fields for the ID and modification dates.

例如,更新允许列表以禁用它:For example, to update an allow list to disable it:

curl -X PUT -n \
  https://<databricks-instance>/api/2.0/ip-access-lists/<list-id>
  -d '{
    "label": "office",
    "list_type": "ALLOW",
    "ip_addresses": [
        "1.1.1.1",
        "2.2.2.2/21"
      ],
    "enabled": "false"
    }'

删除 IP 访问列表Delete an IP access list

若要删除 IP 访问列表,请调用删除 IP 访问列表 API (DELETE /ip-access-lists/<list-id>)。To delete an IP access list, call the delete an IP access list API (DELETE /ip-access-lists/<list-id>).

curl -X DELETE -n \
  https://<databricks-instance>/api/2.0/ip-access-lists/<list-id>
  -d '{
    "label": "office",
    "list_type": "ALLOW",
    "ip_addresses": [
        "1.1.1.1",
        "2.2.2.2/21"
      ],
    "enabled": "false"
    }'