Protect Your Databricks Workspace with IP Access Lists

By default, a Databricks workspace exposes its sign-in page to any IP address on the internet. In enterprise environments, requirements like "only allow access from the corporate VPN" or "restrict access to specific office IPs" come up constantly. IP Access Lists is the feature that controls which IP address ranges can reach a workspace, using CIDR notation.

This article walks through how IP Access Lists work, the differences between Allow Lists and Block Lists, REST API configuration steps, CIDR notation basics, and when to use VPN or Private Link instead.

How IP Access Lists Work

IP Access Lists are a workspace-level network access control. When enabled, every request to the workspace (UI sign-in, REST API calls, JDBC/ODBC connections) is checked against the source IP address. Requests from IPs that are not permitted are rejected with 403 Forbidden.

There are two kinds of IP Access Lists, each with a different role.

The evaluation order is Block List → Allow List. If a request matches the Block List, it is denied even if it also matches the Allow List. When at least one Allow List is defined, any IP that does not match any Allow List is implicitly denied.

CIDR Notation Basics

IP Access Lists configuration uses CIDR (Classless Inter-Domain Routing) notation. Here is a quick refresher for data engineers who are not network-management specialists.

The number after the slash is the network prefix length. A larger value means a smaller range. /32 represents a single IP address, while /0 covers every IP address.

Allow List vs Block List Evaluation Flow

When IP Access Lists are enabled, requests are processed in the following order.

1. Capture the source IP address of the request
2. Match against the Block List: if the IP matches any Block List CIDR → reject immediately with 403
3. Match against the Allow List: if the IP matches any Allow List CIDR → permit (continue to normal authentication)
4. No Allow List match → implicit deny (403)

If there are zero Allow Lists and only Block Lists, then every IP not on a Block List is permitted. In practice, however, the recommended pattern is to make Allow Lists the primary control and use Block Lists for exception exclusions.

Configuring IP Access Lists via the REST API

You can configure IP Access Lists from the UI, but for IaC management and automation you use the REST API. The example below creates an Allow List with curl.

# Create an Allow List (corporate VPN CIDRs)
curl -X POST \
  "https://<workspace-url>/api/2.0/ip-access-lists" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Corporate VPN",
    "list_type": "ALLOW",
    "ip_addresses": [
      "10.0.0.0/16",
      "172.16.0.0/12"
    ]
  }'

To add a Block List, change list_type to "BLOCK".

# Add a Block List (exclude a specific subnet)
curl -X POST \
  "https://<workspace-url>/api/2.0/ip-access-lists" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Exclude Guest Network",
    "list_type": "BLOCK",
    "ip_addresses": [
      "10.0.99.0/24"
    ]
  }'

Enabling or disabling the IP Access Lists feature itself is done through the workspace configuration API.

# Enable the IP Access List feature
curl -X PATCH \
  "https://<workspace-url>/api/2.0/workspace-conf" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enableIpAccessLists": "true"
  }'

Comparing VPN, Private Link, and IP Access List

Databricks offers several network security features, and they are easy to mix up on the exam. Here is a comparison of what each one protects and how it behaves.

IP Access List is the simplest to roll out and takes effect immediately. However, since traffic still flows over the internet, you need Private Link when the requirement is that data must never traverse any external network. Many organizations start with IP Access List and migrate to Private Link as compliance requirements tighten — a phased approach.

Operational Best Practices for IP Access Lists

• Keep Allow Lists minimal: instead of allowing the whole corporate network (/8 or /16), specify VPN egress IPs (/32) or office subnets (/24) to keep the attack surface small.
• Do not forget automation pipeline IPs: CI/CD runner IP ranges from services like GitHub Actions or Jenkins must also be in the Allow List, or deployments will fail.
• Manage with labels: give each list a meaningful label ("Tokyo Office", "CI/CD Runners", etc.) so you can tell later why each list was created.
• Test before enabling: stick to the order of "create the Allow List first, then enable the feature." Enabling first leads to the classic incident: "empty allow list → everyone is blocked."
• The Account Console is unaffected: even if you are locked out of the workspace, you can fix the lists from the Account Console — keep this escape hatch in mind.

Managing with Terraform

To manage IP Access Lists as IaC, use the databricks_ip_access_list resource from the Databricks Terraform Provider.

resource "databricks_ip_access_list" "corporate_vpn" {
  label    = "Corporate VPN"
  list_type = "ALLOW"
  ip_addresses = [
    "10.0.0.0/16",
    "172.16.0.0/12",
  ]
}

resource "databricks_ip_access_list" "guest_block" {
  label    = "Block Guest Network"
  list_type = "BLOCK"
  ip_addresses = [
    "10.0.99.0/24",
  ]
}

resource "databricks_workspace_conf" "ip_access" {
  custom_config = {
    "enableIpAccessLists" = "true"
  }
}

Managing with Terraform enforces a review process for IP changes (PR, approve, apply) and naturally leaves an audit trail of who changed which IP and when.

Key Points for the Exam

• "How do I restrict workspace access to specific IPs?" → IP Access List
• "How do I connect to the workspace without traversing the internet?" → Private Link (not IP Access List)
• "Which has priority, Block List or Allow List?" → Block List wins
• "At what level are IP Access Lists scoped?" → Workspace level
• "A CI/CD pipeline got blocked by IP restrictions — what now?" → Add the runner IPs to the Allow List

Check Yourself

Frequently Asked Questions