IP access lists

Note

This feature requires the Enterprise plan.

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. 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.

For example, suppose a hospital employee accesses a Databricks workspace. If the employee walks from the office to a coffee shop, the hospital can block connections to the Databricks workspace even if the customer has correct credentials to access the web application and the REST API.

Databricks workspaces can be configured so that employees connect to the service only through existing corporate networks with a secure perimeter. Databricks customers can use the IP access lists feature to define a set of approved IP addresses. All incoming access to the Web application and REST APIs requires the user connect from an authorized IP address.

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. Using the previous example, the hospital could allow an employee to use a VPN from the coffee shop to access the Databricks workspace.

IP access list overview diagram

Flexible configuration

The IP access lists feature is flexible:

  • 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. Allow multiple IP addresses explicitly or as entire subnets (for example 216.58.195.78/28).
  • 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. 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.
  • Workspace administrators use REST APIs to update the list of allowed and blocked IP addresses and subnets.

Feature details

The IP Access List API enables 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. If the connection IP address matches any block list, the connection is rejected.

2. If the connection was not rejected by block lists, the IP address is compared with the allow lists. If there is at least one allow list for the workspace, the connection is allowed only if the IP address matches an allow list. If there are no allow lists for the workspace, all IP addresses are allowed.

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.

After changes to the IP access list feature, it can take a few minutes for changes to take effect.

IP access list flow diagram

How to use the IP access list API

This article discusses the most common tasks you can perform with the API. For the complete REST API reference, see IP Access List API. To learn about authenticating to Databricks APIs, see Authentication using Databricks personal access tokens.

The base path for the endpoints described in this article is https://<databricks-instance>/api/2.0, where <databricks-instance> is the <account>.cloud.databricks.com domain name of your Databricks deployment.

Check if your workspace has the IP access list feature enabled

To check if your workspace has the IP access list feature enabled, call the get feature status API (GET /workspace-conf). Pass keys=enableIpAccessLists as arguments to the request.

In 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",
}

Enable or disable the IP access list feature for a workspace

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).

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"
}

Add an IP access list

To add an IP access list, call the add an IP access list API (POST /ip-access-lists).

In the JSON request body, specify:

  • label — Label for this list.
  • list_type — Either ALLOW (allow list) or BLOCK (a block list, which means exclude even if in allow list).
  • ip_addresses — A JSON array of IP addresses and CIDR ranges, as String values.

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. 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
  }
}

To add a block list, do the same thing but with list_type set to BLOCK.

Update an IP access list

To update an IP access list, call the update an IP access list API (PUT /ip-access-lists/<list-id>).

In the JSON request body, specify:

  • label — Label for this list.
  • list_type — Either ALLOW (allow list) or BLOCK (block list, which means exclude even if in allow list).
  • ip_addresses — A JSON array of IP addresses and CIDR ranges, as String values.
  • enabled — Specifies whether this list is enabled. Pass true or false.

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"
    }'

Delete an IP access list

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"
    }'