Databricks

Trustle reads users, service principals, groups, account admins, and, through a SQL warehouse, Unity Catalog grants and usage from Databricks. Trustle can create, deactivate, and delete users, change group members and the account admin role, and grant and revoke Unity Catalog privileges.

Prerequisites

• A Databricks account with the Account admin role. Only an account admin can create an account-level service principal and assign its roles.
• An identity provider connected in Trustle, for example Okta or Microsoft Entra ID. Trustle hides SaaS Applications until one is connected.
• For Unity Catalog grants and usage data: a workspace attached to a Unity Catalog metastore, and a SQL warehouse in that workspace.
• For audit events, table lineage, and query history: the Premium plan or higher, with the access and query system schemas enabled on the metastore.

Configure Databricks

Step 1: Create a service principal

Note

These steps use a Databricks-managed service principal. A Microsoft Entra ID service principal uses a different flow.

1. In Databricks, open the Workspace menu and click Manage account. The account console opens.

   

2. Go to User management.

   

3. Select the Service principals tab. Click Add service principal.

   

4. Enter a name, for example Trustle. Click Add.

Step 2: Generate an OAuth secret

1. Open the service principal. Go to Credentials & secrets → OAuth secrets.

2. Click Generate secret.

3. Enter a Lifetime (days), from 1 to 730. Click Generate.

   

4. Copy the Secret and the Client ID. Databricks shows the secret once.

Caution

When the secret expires, the sync stops. Generate a new secret before that date.

Step 3: Grant permissions

The service principal needs these roles and grants:

Permission	Required	What Trustle does with it
Account admin role	Yes	Imports users, service principals, groups, and account admins. Creates, deactivates, and deletes users. Changes group members and the account admin role. Test Connection checks it.
Metastore admin (Step 4)	Optional	Reads every Unity Catalog grant, and grants and revokes Unity Catalog privileges. Without it, Trustle sees only the grants of the service principal itself.
Workspace access and Can use on a SQL warehouse (Step 5)	Optional	Runs the Unity Catalog queries. Without it, Trustle skips Unity Catalog grants, audit events, lineage, last-used dates, and workspace admins.
SELECT on system.access (Step 5)	Optional	Reads audit events and table lineage, which give the last-used date of each grant. Without it, every grant shows as unused.
SELECT on system.query (Step 5)	Optional	Reads query history for usage data. Without it, Trustle has less usage data.

Assign the account admin role:

1. Open the service principal. Select the Roles tab.

2. Turn on Account admin.

   

Note

Account admin does not show Unity Catalog grants. Only a metastore admin sees every grant. Do Step 4 to give the service principal both.

Step 4: Make the service principal a metastore admin

A metastore has one admin. Make a group the admin, so the service principal and your own admins share the role.

1. In the account console, go to User management → Groups. Create a group, for example metastore-admins. If such a group exists, use it.

   

2. Add the Trustle service principal to the group.

3. Go to Catalog. Open the metastore that your workspaces use.

   

4. Set Metastore admin to the group.

   

One Trustle connection covers one metastore. A metastore covers one cloud region. For workspaces in another region, create one more Trustle connection, and do this step for that metastore too.

Step 5: Give access to a SQL warehouse

Skip this step if you do not want Unity Catalog grants or usage data. Trustle then imports only users, service principals, groups, and account admins.

1. In the account console, go to Workspaces. Open a workspace that is attached to the metastore from Step 4.

2. Select the Permissions tab. Click Add permissions. Add the service principal with the User permission.

3. In that workspace, go to Compute → SQL warehouses. Open the warehouse. A serverless warehouse is best: it starts for each query and stops when idle.

4. Click Permissions. Give the service principal Can use.

5. In the SQL editor, give the service principal access to the system tables. In SQL, Databricks names a service principal by its application ID, which is the Client ID from Step 2:

   GRANT USE CATALOG ON CATALOG system TO `<client-id>`;
   GRANT USE SCHEMA, SELECT ON SCHEMA system.access TO `<client-id>`;
   GRANT USE SCHEMA, SELECT ON SCHEMA system.query TO `<client-id>`;

Step 6: Collect the values for Trustle

1. Account ID: in the account console, open the user menu in the top-right corner. Click Copy account ID. You can also copy it from the account console URL.
2. SQL Warehouse ID: open the warehouse from Step 5. The ID is on the Overview tab, and in the URL after /sql/warehouses/.

Trustle field	Where to find it in Databricks	Example
Account Host	The account console address for your cloud. AWS: https://accounts.cloud.databricks.com. GCP: https://accounts.gcp.databricks.com. Azure: https://accounts.azuredatabricks.net.	https://accounts.cloud.databricks.com
Account ID	User menu → Copy account ID	00000000-0000-0000-0000-000000000000
Client ID	Service principal → OAuth secrets (Step 2)	<client-id>
Client Secret	The Secret from Step 2	<client-secret>
Workspace URL (Optional)	The address of the workspace from Step 5	https://dbc-xxxxxxxx-xxxx.cloud.databricks.com
SQL Warehouse ID (Optional)	Warehouse → Overview	<warehouse-id>

Enter Workspace URL and SQL Warehouse ID together, or leave both empty.

Connect in Trustle

1. In Trustle, go to Connections.
2. Under SaaS Applications, find Databricks and click Connect.
3. Enter a Connection Name, for example Databricks production. Description is optional.
4. Enter the values from Step 6.
5. Click Test Connection.
6. After the test passes, click Save Connection.

Note

Test Connection checks that the service principal is an account admin. When you enter Workspace URL and SQL Warehouse ID, it also checks that the service principal can open that warehouse. It does not check the metastore admin role or the system tables. Do the steps in Verify after the first sync.

Verify

1. On the Connections page, open the Databricks connection.
2. Wait for the first sync to finish.
3. Check that the user count and the group count match User management in the account console.
4. If you did Step 5, check that the connection shows Unity Catalog grants.

If something is missing, see Troubleshooting.

Security notes

Note

• Use a dedicated service principal for Trustle only.
• Store the client secret in a secret manager. Never commit it to a repository.
• A service principal can have more than one OAuth secret. To rotate, generate a new secret, paste it into the Trustle connection, then delete the old one.
• Each sync runs queries on the SQL warehouse. Databricks bills you for that compute.

Troubleshooting

Test Connection fails

Read the error message:

• “Invalid credentials: authentication failed”: the Client ID or Client Secret is wrong, or the secret expired. Also check that Account Host matches your cloud and that Account ID is correct.
• “Insufficient permissions: the service principal must be a Databricks account admin”: do Step 3.
• “Invalid credentials format”: Account Host must be one of the three addresses in Step 6. Workspace URL must start with https://. Enter Workspace URL and SQL Warehouse ID together, or leave both empty.
• “Failed to reach the Databricks workspace”: check the Workspace URL. Copy it from the browser address bar while the workspace is open.
• “Could not authenticate against the workspace URL”: add the service principal to the workspace. See Step 5.
• “SQL warehouse … was not found in the workspace”: check the SQL Warehouse ID. The warehouse must be in the workspace from Workspace URL.
• “The service principal cannot access the SQL warehouse”: give it Can use on the warehouse.

The sync shows few or no Unity Catalog grants

• Metastore admin: without it, Trustle sees only the grants of the service principal itself. Do Step 4.
• Wrong metastore: the workspace in Workspace URL must use the metastore you expect. One connection covers one metastore.
• No warehouse: without Workspace URL and SQL Warehouse ID, Trustle skips Unity Catalog. Do Step 5.

Trustle shows the data after the next sync.

Every Unity Catalog grant shows as unused

Trustle cannot read usage. Check each item:

• The account is on the Premium plan or higher.
• The access and query system schemas are enabled on the metastore.
• The service principal has the SELECT grants from Step 5.

Trustle shows the data after the next sync.

Workspaces in another region are missing

One connection covers one metastore, and a metastore covers one region. Create one more Trustle connection with a workspace and a warehouse in that region. Make the service principal a metastore admin there too.

None of these fixes work

Email support@trustle.com. Include the error message, the connection name, and the Account ID and the service principal’s Client ID. Never send a secret, key, or token.