Set up Lakewatch access control

When you set up Lakewatch with the Recommended configuration, all account users can administer the environment and work in every folder. That's a fast way to start, but most security teams want to separate who ingests data, who authors detection rules, and who works alerts. This page replaces that default access with four groups, each with only the permissions its role needs. Apply it during setup with Custom configuration, or at any time afterward from the environment settings.

Lakewatch permissions are Unity Catalog grants. The environment is a catalog, each folder is a schema, and each permission group (such as Datasource manager) is a set of Unity Catalog privileges. For the privileges in each permission group, see Roles and capabilities.

Personas

This setup uses four groups, one per role on a typical security team. Groups are recommended but optional. The same permissions work for any account-level user, group, or service principal.

The steps use the default folder names, datasources for datasources and detection for detection rules and alerts. If you renamed them during setup, use your names instead.

Requirements

• Account administrator, to create the groups in step 1.
• To set up access while you create the environment: CREATE CATALOG on the metastore for a new catalog, or MANAGE and CREATE SCHEMA on an existing catalog. See Set up Lakewatch for your workspace.
• To change access on an existing environment: MANAGE on the catalog to change Lakewatch administrators, and MANAGE on a folder to change its permissions.

1. Create the groups

In the account console, go to User management > Groups and create the four groups: lakewatch-admins, lakewatch-data-engineers, lakewatch-detection-engineers, and lakewatch-analysts. Then add members to each group.

Lakewatch permissions are granted to account-level principals, so create these as account groups, not workspace-local groups. For production, Databricks recommends groups managed by Microsoft Entra ID. See Deployment models.

2. Assign Lakewatch administrators

Lakewatch admin is granted on the environment's catalog and applies to every folder, datasource, and detection rule in it. Lakewatch administrators can also add folders and change their permissions.

During setup

1. On the Welcome to Lakewatch screen, under Get started with Lakewatch, select Custom configuration.
2. Next to Admins, select the pencil icon.
3. Add lakewatch-admins, then select Add. Every administrator gets the Lakewatch admin permission group.
4. Next to All account users, select Remove.
5. Select Done.

Continue to step 3 before you select Create.

After setup

1. In Lakewatch, go to Settings > Environment.
2. Under Lakewatch administrators, add lakewatch-admins, then select Grant.
3. Next to All account users, select Revoke.

Changes to Lakewatch administrators apply immediately.

Add lakewatch-admins before you remove All account users, so the environment is never left without an administrator. Setup requires at least one catalog-level grant.

3. Set folder permissions

Folder permissions apply to every datasource and detection rule in the folder. Select one or more permission groups for each principal. If you select individual permissions instead, the grant becomes Custom.

Grant the following on each folder, and remove All account users from both:

lakewatch-admins doesn't need folder grants, because its catalog-level Lakewatch admin grant already covers every folder.

During setup

1. Next to Datasource folder, select the pencil icon.
2. In Configure datasource folder, set the grants for the datasources folder, then select Done.
3. Next to Detection & Alerts folder, select the pencil icon.
4. In Configure detection & alert folder, set the grants for the detection folder, then select Done.
5. Select Create.

After setup

1. In Lakewatch, go to Settings > Environment.
2. Under Folders, find the folder and select Edit.
3. Add and remove principals and permission groups, then select Save.

To give a team its own space, select Add folder under Folders and grant that team's group permissions on the new folder. Adding a folder requires MANAGE and CREATE SCHEMA on the catalog.

To create an API connector datasource, data engineers must also have CREATE CONNECTION on the metastore to create a new connection, or USE CONNECTION on an existing connection. Permission groups don't include these privileges, because connections are metastore-level objects.

4. Set up a run-as service principal (recommended)

Each scheduled datasource and detection rule runs as its Run as principal. By default, that's the person who creates it, so the resource stops working if that person loses access or leaves. Anyone who later edits the resource must also be able to use its run-as principal, or change Run as to themselves or a service principal they can use. Running production resources as a shared service principal avoids both problems.

To set up a run-as service principal, complete the following steps:

1. In the account console, go to User management > Service principals and create the Lakewatch run-as service principal. Copy its applicationId (a UUID) for use as <sp> in the following grants.
2. On the service principal's Permissions tab, assign Service Principal Manager to lakewatch-admins. Then assign Service Principal User to lakewatch-data-engineers and lakewatch-detection-engineers, so that members of those groups can set the service principal as Run as.
3. In Settings > Environment, edit the datasources and detection folders, and grant the service principal Custom permissions on each: Read Lakewatch tables, Modify Lakewatch tables, and Create Lakewatch tables.
4. Go to SQL Warehouses. For each warehouse your detection rules run on, grant Can use to the service principal on the warehouse's Permissions tab. This requires Can manage on the warehouse.

When your team creates a datasource or detection rule, they set Run as to the service principal. Granting Service Principal User enables members of a group to run jobs with the service principal's access, so grant it only to groups you trust with that access.

5. Grant access to sources (optional)

A datasource or detection rule that reads from outside the environment must have access to that source. Grant these to the run-as principal, and only for the sources you use. To run these grants, you must own the securable, own its catalog or schema, have MANAGE on it, or be a metastore administrator. See Who can manage privileges?.

To let the service principal read from an external location, run the following:

GRANT READ FILES ON EXTERNAL LOCATION <external_location> TO `<sp>`;

To let the service principal use every connection in the metastore, run the following:

GRANT USE CONNECTION ON METASTORE TO `<sp>`;

To let the service principal read an existing source table, run the following:

GRANT USE CATALOG ON CATALOG <src_catalog> TO `<sp>`;
GRANT USE SCHEMA ON SCHEMA <src_catalog>.<src_schema> TO `<sp>`;
GRANT SELECT ON TABLE <src_catalog>.<src_schema>.<src_table> TO `<sp>`;

6. Verify

In Settings > Environment, confirm that Lakewatch administrators lists only lakewatch-admins, and that the Permissions column under Folders shows the expected principals for each folder.

Folder permissions are Unity Catalog grants, so SHOW GRANTS also lists them. Replace lakewatch with your catalog name, then run the following:

SHOW GRANTS ON CATALOG lakewatch;
SHOW GRANTS ON SCHEMA lakewatch.datasources;
SHOW GRANTS ON SCHEMA lakewatch.detection;

The output also lists the USE CATALOG and USE SCHEMA grants that Lakewatch gives all account users on the catalog and every folder. See Permission groups.

Limitations

• Granting USE CONNECTION ON METASTORE lets the service principal use every connection in the metastore, which is broader than least-privilege. Use it only on a metastore dedicated to Lakewatch.

Additional resources

• Set up Lakewatch for your workspace
• Access control model
• Roles and capabilities
• Deployment models