IP access lists for workspaces

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.

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 though they have correct credentials.

You can configure Databricks workspaces 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.

If the internal VPN network is authorized, employees who are remote or traveling could use the VPN to connect to the corporate network, which in turn enables access to the workspace.

If you use PrivateLink, note that IP access lists apply only to requests over the internet (public IP addresses). Private IP addresses from PrivateLink traffic cannot be blocked by IP access lists. To block specific private IP addresses from PrivateLink traffic, use AWS Network Firewall. If you want to restrict the PrivateLink connection to a set of registered PrivateLink endpoints, change your workspace’s private access settings object to use the ENDPOINT access level.

Requirements

This feature requires the E2 version of the Databricks platform.

New accounts—except for select custom accounts—are created on the E2 platform, and most existing accounts have been migrated. If you are unsure whether your account is on the E2 platform, contact your Databricks representative.
This feature requires the Enterprise pricing tier.

IP access lists support only Internet Protocol version 4 (IPv4) addresses.

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 a REST API to update the allow lists and block lists.

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:

First all block lists are checked. If the connection IP address matches any block list, the connection is rejected.
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.

How to use the API

This article discusses the most common tasks you can perform with the API. For the complete REST API reference, see IP Access Lists API. To learn about authenticating to Databricks APIs, see the Token management API.

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

Warning

When the IP access lists feature is enabled and there are no allow lists or block lists for the workspace, all IP addresses are allowed. Adding IP addresses to the allow list blocks all IP addresses that are not on the list. Review the changes carefully to avoid unintended access restrictions.

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 list all IP access lists API (GET /ip-access-lists), and find the ID of the list you want to update.
Call the update an IP access list API (PATCH /ip-access-lists/<list-id>).

In the JSON request body, specify at least one of the following values to update:

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 disable a list:

curl -X PATCH -n \
  https://<databricks-instance>/api/2.0/ip-access-lists/<list-id>
  -d '{ "enabled": "false" }'

Replace an IP access list

To replace an IP access list:

Call the list all IP access lists API (GET /ip-access-lists), and find the ID of the list you want to replace.
Call the replace 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 replace the contents of the specified list with the following values:

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 list all IP access lists API (GET /ip-access-lists), and find the ID of the list you want to delete.
call the delete an IP access list API (DELETE /ip-access-lists/<list-id>).

For example:

curl -X DELETE -n \
  https://<databricks-instance>/api/2.0/ip-access-lists/<list-id>