# Register a Databricks Lakebase Connection

{% hint style="info" %}
**Public preview**: This integration is available to all accounts that request to enable it for their tenant. Contact your Immuta representative to enable it.
{% endhint %}

## Requirements

* [Databricks Lakebase database](https://docs.databricks.com/aws/en/oltp/instances/about)

## Permissions

The user registering the connection must have the permissions below.

* `APPLICATION_ADMIN` Immuta permission
* The account credentials you provide to register the connection should be a [Databricks service principal](https://docs.databricks.com/aws/en/oltp/instances/manage-privileges#grant-instance-permissions-to-databricks-identities). [Create a PostgreSQL role for the Databricks service principal](https://docs.databricks.com/aws/en/oltp/projects/external-apps-connect#2-create-postgres-role-for-the-service-principal) and [grant it the following permissions](https://docs.databricks.com/aws/en/oltp/projects/manage-roles-permissions) in your Databricks Lakebase database:

  * `databricks_superuser`
  * `CREATEROLE`

  For descriptions and explanations of privileges Immuta needs to enforce policies and maintain state in Databricks Lakebase, see the [Databricks Lakebase connection reference guide](https://documentation.immuta.com/saas/configuration/integrations/databricks/reference-guides/databricks-lakebase-integration#required-databricks-lakebase-privileges).

## Register a Databricks Lakebase connection

1. In Immuta, click **Data** and select **Connections** in the navigation menu.
2. Click the **+ Add Connection** button.
3. Select the **Databricks Lakebase** tile.
4. Enter the host connection information:
   1. **Display Name:** This is the name of your new connection. This name will be used in the API (`connectionKey`), in data source names from the host, and on the connections page. Avoid the use of periods (`.`) or [restricted words](#user-content-fn-1)[^1] in your connection name.
   2. **Hostname**: The host can be found by clicking **Connect** in your Databricks Lakebase console. See the [Databricks Lakebase docs](https://docs.databricks.com/aws/en/oltp/projects/connection-strings#connection-string-format) for additional details.
   3. **Port**: The default PostgreSQL port used for Databricks Lakebase is `5432`.
   4. **Database**: The database can be found by clicking **Connect** in your Databricks Lakebase console. The default is `databricks_postgres`.
5. Enter privileged credentials to register the connection using OAuth M2M:
   1. Follow Databricks documentation to create an OAuth token for machine-to-machine authentication for the Immuta service principal and assign this service principal the [privileges listed above](#permissions) for the Databricks Lakebase database.
   2. Fill out the **Workspace URL** (e.g., `https://<your workspace name>.cloud.databricks.com`).
   3. Fill out the **Client ID**. This is a combination of letters, numbers, or symbols, used as a public identifier and is the [client ID displayed in Databricks when creating the client secret for the service principal](https://docs.databricks.com/en/dev-tools/auth/oauth-m2m.html#step-3-create-an-oauth-secret-for-a-service-principal).
   4. Enter the **Client Secret** you created above. Immuta uses this secret to authenticate with the authorization server when it requests a token.
6. Click **Save Connection**.

## Map users

**Requirement**: `USER_ADMIN` Immuta permission

Map PostgreSQL usernames to each Immuta user account to ensure Immuta properly enforces policies when the user queries the Databricks Lakebase objects in PostgreSQL.

The instructions below illustrate how to do this for individual users, but you can also configure user mapping in your [IAM connection on the app settings page](https://documentation.immuta.com/saas/people/users-index/how-to-guides/external-user-mapping#configure-external-user-id-mapping-on-app-settings-page).

1. Click **People** and select **Users** in the navigation menu.
2. Click the user's **name** to navigate to their page and scroll to the **External User Mapping** section.
3. Click **Edit** in the **PostgreSQL** row.
4. Select one of the following options from the dropdown:
   1. Select **PostgreSQL Username** to map the PostgreSQL username to the Immuta user and enter the PostgreSQL username in the field. Username mapping is case insensitive.
   2. Select **Unset (fallback to Immuta username)** to use the Immuta username as the assumed PostgreSQL username. Use this option if the user's PostgreSQL username exactly matches the user's Immuta username. Username mapping is case insensitive.
   3. Select **None (user does not exist in PostgreSQL)** if this is an Immuta-only user. This option will improve performance for Immuta users who do not have a mapping to PostgreSQL users and will be automatically selected by Immuta if an Immuta user is not found in PostgreSQL. To ensure your PostgreSQL users have policies correctly applied, manually map their usernames using the first option above.
5. Click **Save.**

[^1]: Your display name cannot be any of the following words: `data`, `connection`, `object`, `crawl`, `search`, `settings`, `metadata`, `permission`, `sync`, `bulk`, and `upgrade`.