Minimum Permissions for Scan Accounts

Forcepoint DSPM scans Databricks (Unity Catalog) data sources for cataloguing and classification. This section describes the minimum Databricks privileges required for a scan account, so customers can provision a least-privilege service principal instead of a workspace/account admin.

Connection prerequisites
Requirement Reason
Network reachability to the Databricks workspace host (443) Establish the JDBC connection (HTTPS-only)
A service principal for the scanner Least-privilege, unattended identity
A personal access / on-behalf-of (OBO) token for that service principal The connector uses token auth (AuthMech=3): UID=token, PWD=<the token>
The SQL warehouse HTTP path The connector runs all queries on a SQL warehouse
The target catalog name The connector scopes to one Unity Catalog catalog

The connector uses the official Databricks JDBC driver. No workspace-admin or account-admin role is required.

A Databricks service principal is an account-plane identity - it cannot be created in SQL. Setup is therefore two parts: Part 1 (Databricks CLI) creates the service principal, grants CAN USE on the SQL warehouse, and mints the OBO token; Part 2 (SQL) applies the Unity Catalog read grants.

How Unity Catalog handles visibility

In Unity Catalog, privileges inherit downward: a SELECT on a catalog reaches every schema and table inside it (current and future); a SELECT on a schema reaches every table in that schema. So a single grant at the right level covers everything below it — no per-table grants are needed. An object also stays hidden until the principal holds a privilege that reaches it, so USE CATALOG / USE SCHEMA are needed to traverse down to the target. Access to system.information_schema requires Unity Catalog; the connector auto-detects it by probing system.information_schema.column_privileges.

Operations and required permissions
  1. Connection test & database metadata
    Operation Objects read Minimum grant
    Run queries SQL warehouse CAN USE on the SQL warehouse (Part 1)
    Catalog / schema enumeration information_schema (Unity Catalog) USE CATALOG, USE SCHEMA
    Table / view listing information_schema.tables / SHOW TABLES USE SCHEMA
    Column metadata (getColumns) information_schema.columns SELECT on the table (reaches columns)
    Row count, table size, primary keys DESCRIBE TABLE EXTENDED SELECT on the table
  2. Data sampling
    Operation Objects read Minimum grant
    TABLESAMPLE row sample Target user table/view USE CATALOG + USE SCHEMA + SELECT on the table.
    Column payload sampling Target user table/view Same as above
  3. Trustee (users & groups) extraction
    Operation Objects read Minimum grant
    List users and groups system.information_schema.*_privileges Nothing extra - system.information_schema is readable by the account users group out of the box
    Recursive group membership SHOW GROUPS WITH USER /SHOW GROUPS WITH GROUP Nothing extra
  4. Permissions extraction
    Operation Objects read Minimum grant
    Catalog-level grants system.information_schema.catalog_privileges + <catalog>.information_schema.catalog_privileges Nothing extra
    Schema-level grants ...schema_privileges Nothing extra
    Table-level grants ...table_privileges Nothing extra
    Column-level grants ...column_privileges Requires Unity Catalog (auto-detected)
    Admin holders resolved from the principal/user list Nothing extra

Granting scan access

The scanner needs exactly one load-bearing read grant at the chosen scope, plus the USE grants to traverse to it. Because Unity Catalog inherits downward, SELECT ON SCHEMA (or ON CATALOG) covers current and future tables - no per-table maintenance.

Part 1 - account setup (Databricks CLI)

Run as a workspace admin. Creates the service principal, grants CAN USE on the warehouse behind the connector's HTTP path, and mints the OBO token used as the connector password.
export DATABRICKS_HOST="https://<workspace-host>.cloud.databricks.com"
export DATABRICKS_TOKEN="<workspace-admin-PAT>"

# 1. Create the service principal, capture its applicationId
APP_ID=$(databricks service-principals create --display-name "fp-scanner" \
  | grep -o '[0-9a-fA-F]\{8\}-[0-9a-fA-F]\{4\}-[0-9a-fA-F]\{4\}-[0-9a-fA-F]\{4\}-[0-9a-fA-F]\{12\}' \
  | head -1)

# 2. Grant CAN_USE on the SQL warehouse (update-permissions MERGES, does not overwrite the ACL)
databricks warehouses update-permissions "<sql-warehouse-id>" \
--json '{
  "access_control_list": [
    { "service_principal_name": "'"$APP_ID"'", "permission_level": "CAN_USE" }
  ]
}'

# 3. Mint the OBO token (90 days). Shown ONCE - store it in your secret manager.
databricks token-management create-obo-token "$APP_ID" 7776000 --comment "Forcepoint scanner OBO token"

Part 2 - Unity Catalog read grants (SQL)

Run in a SQL editor as the catalog/schema owner or a metastore admin. Replace <applicationId> (from Part 1) and the object names. Pick the variant matching your scan scope.

Scope A - entire datasource (whole catalog):
GRANT USE CATALOG ON CATALOG `<catalog>` TO `<applicationId>`;
GRANT USE SCHEMA  ON CATALOG `<catalog>` TO `<applicationId>`;
GRANT SELECT      ON CATALOG `<catalog>` TO `<applicationId>`;
Scope B - a single schema:
GRANT USE CATALOG ON CATALOG `<catalog>`             TO `<applicationId>`;
GRANT USE SCHEMA  ON SCHEMA  `<catalog>`.`<schema>`  TO `<applicationId>`;
GRANT SELECT      ON SCHEMA  `<catalog>`.`<schema>`  TO `<applicationId>`;
Scope C - a single table:
GRANT USE CATALOG ON CATALOG `<catalog>`                      TO `<applicationId>`;
GRANT USE SCHEMA  ON SCHEMA  `<catalog>`.`<schema>`           TO `<applicationId>`;
GRANT SELECT      ON TABLE   `<catalog>`.`<schema>`.`<table>` TO `<applicationId>`;

The trustee/permission scan needs no grant beyond these - system.information_schema is already readable by the service principal via the account users group.

Verification

Connect as the service principal (UID=token, PWD=<OBO token>) and run:
SELECT current_catalog();
SHOW SCHEMAS IN `<catalog>`;
SELECT * FROM `<catalog>`.`<schema>`.`<table>` TABLESAMPLE (1 PERCENT) LIMIT 10;
SELECT count(*) FROM system.information_schema.table_privileges;
SELECT count(*) FROM system.information_schema.column_privileges;

All queries should return without an access error. Empty result sets are fine when the underlying object has no matching rows.

Known limitation - two reserved admin groups in the trustee scan

At minimum permissions the trustee scan captures every regular user and group, but not the two built-in reserved admin groups (the workspace-admins group and the account-admins group). This is by Databricks design: system.information_schema row-filters grant metadata to what the calling identity is a member of, and the reserved admin-group rows are visible only to principals that are themselves admins. No object-level grant — including MANAGE ON CATALOG — exposes them. The only way to surface them is to make the scanner an admin, which defeats minimum-permission scanning. This is acceptable: those two groups are the admin groups, which implicitly have full access anyway, so nothing meaningful is lost from an access-mapping standpoint. See Databricks: Information schema for more information.

What is not required

The scan account does not need any of:

  • Workspace-admin or account-admin membership.

  • MANAGE on the catalog, schema, or any object.

  • Per-table grants when a catalog- or schema-level SELECT already covers them (Unity Catalog inherits downward).

  • MODIFY, INSERT, or any write/DDL privilege.

  • ALL PRIVILEGES at any level.