Preparing Your Databricks Account

ALTR connects to your Databricks workspace as a service principal, and applies tag-based masking to Unity Catalog columns using native column masks.

Overview

1. Create the required groups.
2. Create the ALTR service principal.
3. Set the Metastore admin group.
4. Configure the workspace.
5. Configure the workspace cluster.

Requirements

ALTR supports Databricks Premium Tier on AWS with Unity Catalog enabled and a Metastore-level managed storage location. Contact ALTR support about connecting Databricks on Azure or Google Cloud Platform (GCP), Serverless Compute, or Hive Catalog.

This setup covers everything needed to run classification and data masking against Databricks. Both are separate, ALTR-side capabilities that don’t require additional Databricks-side configuration.

Prerequisites

Before you begin, confirm the following:

• You have a Databricks user with both account admin privilege (in the Databricks account portal, typically at https://accounts.cloud.databricks.com) and workspace admin privilege on the workspace you want ALTR to connect to.
• The Metastore you want ALTR to connect to has a Metastore-level managed storage location. If you already have a Metastore, see Databricks’ guide to configuring managed storage for an existing Metastore. If you’re creating a new Metastore, see Databricks’ guide to creating a Metastore.

Create a text file to record the following values as you work through this page — you’ll need them when you connect ALTR to your Databricks account:

Existing Metastore Admin Name:
Metastore Admin Group Name:
ALTR Service Principal Name:
ALTR Service Principal ID:
ALTR Service Principal OAuth Secret:
Databricks Workspace Hostname:
Databricks Workspace Cluster ID:

Create the Required Groups

To create the groups ALTR needs:

1. From the Databricks account portal, go to User management > Groups > Add group.
2. Enter altr-service-group for the Group name — this exact name is required.
3. Add another group and name it Metastore-admins (or a name of your choosing). Record the name you chose in your text file as the Metastore Admin Group Name.

Create the ALTR Service Principal

The ALTR service principal is a machine-to-machine Databricks service principal ALTR uses to manage tag-based masking objects on Unity Catalog.

To create the service principal:

1. From the Databricks account portal, select User management > Service Principals > Add service principal.

2. Enter a name for the service principal (for example, altr-service-principal). Record the name in your text file as the ALTR Service Principal Name.

3. Click Add. You’re returned to User management > Service Principals when this completes.

4. Click the service principal you just created.

5. Under OAuth secrets, click Generate Secret.

6. Choose an expiration time consistent with your company’s security policies.

   Caution

   Once this secret expires, ALTR’s connection to Databricks stops working until you generate a new secret and update ALTR with it.

7. Copy the Secret and Client ID values shown, and record them in your text file as the ALTR Service Principal OAuth Secret and ALTR Service Principal ID.

8. Go to Roles and enable Account Admin.

Set the Metastore Admin Group

The altr-service-group must be a Metastore admin to see and operate on all objects in Unity Catalog. Since a Metastore can have only one Metastore admin, this step combines the ALTR service group and your existing Metastore admin into the Metastore-admins group created earlier, then sets that group as the Metastore admin.

To record your existing Metastore admin:

1. From the Databricks account portal, select Catalog > (your Metastore).
2. Record the value shown for Metastore Admin in your text file as the Existing Metastore Admin Name.

To add the ALTR service principal to the ALTR service group:

1. Select User management > Groups.
2. Click altr-service-group.
3. Click Add members and add the ALTR service principal you created.

To add the ALTR service group and your existing Metastore admin to the Metastore-admins group:

1. Return to User management > Groups.
2. Click the Metastore-admins group you created.
3. Click Add members.
4. Add altr-service-group and the existing Metastore admin you recorded.

To set Metastore-admins as the Metastore admin:

1. Select Catalog and click the Metastore you want ALTR to connect to.
2. Under Metastore Admin, click Edit.
3. Set the Metastore-admins group as the Metastore admin.

Configure the Workspace

To grant the ALTR service group access to a workspace:

1. From the Databricks account portal, click Workspaces.
2. Create or select a workspace for ALTR to connect to — it must be attached to the Metastore you want ALTR to connect to.
3. Click the workspace name.
4. Record the workspace URL (or hostname) in your text file as the Databricks Workspace Hostname.
5. Click Permissions > Add permissions.
6. Add altr-service-group as a User and click Save.

Configure the Workspace Cluster

ALTR uses the ALTR service principal to run a job on workspace compute that sets column masks and creates the catalog, tables, and user-defined functions (UDFs) ALTR needs. This job runs whenever you apply a tag-based masking policy to your Unity Catalog.

To configure the workspace compute ALTR uses:

1. Log in to the workspace portal (using the hostname you recorded) as a user with admin privilege on that workspace.
2. Go to Compute.
3. Create or select an all-purpose compute cluster that runs Python 3.10 or newer and has Unity Catalog enabled.
4. Click the cluster’s name.
5. In the Configuration tab, scroll to Tags and expand Automatically added tags.
6. Record the value shown for ClusterId in your text file as the Databricks Workspace Cluster ID.
7. Click Permissions.
8. Add altr-service-group as Can Restart and click Save.

Connect Databricks to ALTR

With the values recorded in your text file — the service principal ID and OAuth secret, the workspace hostname, and the cluster ID — you’re ready to connect the data source in ALTR. See Locate Your Databricks Connection Details if you need help finding any of these values again, and Manage Databricks Data Sources to connect the data source in the ALTR portal.