## Set up Starburst Enterprise

URL: https://docs.atlan.com/apps/connectors/database/starburst-enterprise/how-tos/set-up-starburst-enterprise

> Configure authentication and permissions for Starburst Enterprise to enable Atlan to crawl metadata from your instance.

Setting up Starburst Enterprise authentication enables Atlan to securely connect to your instance and extract metadata. This process configures the necessary credentials and permissions for Atlan to discover and catalog your SQL assets (catalogs, schemas, tables, views) and data product assets (domains, data products, datasets).

## Prerequisites

Before you begin, make sure you have:

* Administrative access to your Starburst Enterprise instance or contact with your Starburst administrator
* HTTPS enabled on the Starburst Enterprise instance (port 443 by default)
* [Built-in access control](https://docs.starburst.io/latest/security/biac-overview.html) or [file-based access control](https://docs.starburst.io/latest/security/file-system-access-control.html) configured on your cluster
* [Dynamic Catalogs](https://docs.starburst.io/latest/admin/properties-catalog.html#migration-to-dynamic-catalogs) enabled on the cluster (`catalog.management=dynamic`). Atlan's catalog discovery reads the `state` column on `system.metadata.catalogs`, which is exposed only when Dynamic Catalogs is enabled. On clusters running with the default `catalog.management=static`, preflight fails with `Catalog discovery failed (TrinoUserError) - Column 'state' cannot be resolved`.

## Set up authentication

Atlan supports two authentication methods for Starburst Enterprise. Choose the method that matches your organization's security requirements:

### Basic authentication

Use Starburst Enterprise [password file authentication](https://docs.starburst.io/latest/security/password-file.html) with username and password credentials.

1. Create a dedicated user for Atlan in your Starburst Enterprise password file by following the [password file authentication documentation](https://docs.starburst.io/latest/security/password-file.html). For example, create a user named `atlan`.

2. [Configure access control permissions](#configure-access-control) for the user (see below).

3. Click **Test Authentication** in the Atlan setup wizard to verify the credentials.

### LDAP authentication

Use [LDAP authentication](https://docs.starburst.io/latest/security/ldap.html) when your Starburst Enterprise instance authenticates users with an LDAP directory.

1. Create or identify an LDAP user account for Atlan in your LDAP directory.

2. Verify the LDAP user can authenticate with your Starburst Enterprise instance by logging in directly.

3. [Configure access control permissions](#configure-access-control) for the user (see below).

4. Click **Test Authentication** in the Atlan setup wizard to verify the credentials.

## Configure access control

Atlan extracts metadata exclusively from `INFORMATION_SCHEMA` tables and the `system.metadata` catalog. It never queries or accesses actual user data in your tables. The permissions below reflect this least-privilege approach.

### Built-in access control (BIAC)

If your cluster uses [built-in access control](https://docs.starburst.io/latest/security/biac-overview.html), create a dedicated role for the Atlan user and grant the minimum required privileges.

### Create role

Create a custom role for the Atlan user:

```sql
CREATE ROLE atlan_metadata_reader;
```

Grant the role to the Atlan user:

```sql
GRANT atlan_metadata_reader TO USER atlan;
```

### Grant query execution privilege

The connector runs SQL queries on `INFORMATION_SCHEMA` and `system.metadata` tables to extract metadata. In BIAC, the [`EXECUTE` privilege on Queries](https://docs.starburst.io/latest/security/biac-privileges.html) is required for a user to run any SQL query on the cluster.

By default, new SEP clusters grant `EXECUTE` on Queries to the `public` role, which means all authenticated users can execute queries. However, if your cluster's `sysadmin` has removed this default as part of security hardening, you must explicitly grant `EXECUTE` on Queries to the Atlan user's role.

To verify or grant this privilege:

1. Open the **Built-in access control** page in the Starburst Enterprise UI.
2. Navigate to the `atlan_metadata_reader` role's privileges.
3. Under **Queries**, verify that **EXECUTE** is set to **Allow**.

:::info EXECUTE doesn't grant data access

The `EXECUTE` privilege on Queries only permits *running* queries—it doesn't grant access to any data on its own. The Atlan user still needs separate `SHOW` and `SELECT` privileges (documented below) to access specific metadata. This follows the [principle of least privilege](https://docs.starburst.io/latest/security/biac-privileges.html).

:::

### Grant table visibility

The connector queries `INFORMATION_SCHEMA` tables (`.information_schema.schemata`, `.information_schema.tables`, `.information_schema.columns`, `.information_schema.views`) to discover metadata. In BIAC, `INFORMATION_SCHEMA` only returns rows for objects the user has at least one privilege on. The `SHOW` privilege is the minimum privilege that makes objects visible in `INFORMATION_SCHEMA` without granting access to actual table data.

The grant pattern follows the format `catalog.schema.table_or_view`, where `*` is a wildcard matching all objects at that level.

To grant access to **all catalogs** at once:

```sql
GRANT SHOW ON TABLE *.*.* TO ROLE atlan_metadata_reader;
```

To grant access to **specific catalogs** only:

```sql
GRANT SHOW ON TABLE your_catalog.*.* TO ROLE atlan_metadata_reader;
GRANT SHOW ON TABLE another_catalog.*.* TO ROLE atlan_metadata_reader;
```

For details on the `GRANT` syntax, see the [GRANT privilege documentation](https://docs.starburst.io/latest/sql/grant.html).

:::info Least privilege principle enforcement

Atlan only reads metadata from `INFORMATION_SCHEMA`. It never runs `SELECT` on your data tables. The [`SHOW` privilege](https://docs.starburst.io/latest/security/biac-privileges.html) makes tables visible in `INFORMATION_SCHEMA` and enables `SHOW TABLES` and `SHOW CREATE TABLE`, which is all the connector needs. Combined with `EXECUTE` on Queries (which only permits running queries, not accessing data), this follows the principle of least privilege by not granting read access to actual data.

:::

### Grant system catalog access

The connector queries two tables in the `system` catalog:

* `system.metadata.catalogs`: discovers available catalogs and their connector types
* `system.metadata.materialized_views`: detects materialized views (which `INFORMATION_SCHEMA` misclassifies as `BASE TABLE`)

Grant `SELECT` on these specific tables:

```sql
GRANT SELECT ON TABLE system.metadata.catalogs TO ROLE atlan_metadata_reader;
GRANT SELECT ON TABLE system.metadata.materialized_views TO ROLE atlan_metadata_reader;
```

:::info Third-party access control

If your cluster uses third-party access control (Apache Ranger, Immuta) instead of or alongside BIAC, you must [explicitly create a policy](https://docs.starburst.io/latest/security/overview.html) granting access to `system.metadata`, `system.jdbc`, and `system.runtime`.

:::

### Grant domain and data product privileges

The connector calls the [data products API](https://docs.starburst.io/latest/data-products/) to discover domains, data products, datasets, and dataset columns. In BIAC, domains and data products share a single set of [entity privileges](https://docs.starburst.io/latest/security/biac-privileges.html#biac-entity-data-products): `SHOW`, `ALTER`, `CREATE`, `DROP`, and `PUBLISH`. The connector only needs `SHOW`.

Grant `SHOW` on **all domains and data products**:

```sql
GRANT SHOW ON DATA PRODUCTS TO ROLE atlan_metadata_reader;
```

Or grant `SHOW` on a **specific domain** and all its data products:

```sql
GRANT SHOW ON DOMAIN your_domain TO ROLE atlan_metadata_reader;
```

No `ALTER`, `CREATE`, `DROP`, or `PUBLISH` privileges are needed—Atlan only reads domain and data product metadata.

For the full list of data product privileges, see the [BIAC privileges documentation](https://docs.starburst.io/latest/security/biac-privileges.html#biac-entity-data-products).

### File-based access control

If your cluster uses [file-based access control](https://docs.starburst.io/latest/security/file-system-access-control.html), update your `etc/rules.json` file to grant the Atlan user access to the `system` catalog.

### Configure catalog rules

With file-based access control, `INFORMATION_SCHEMA` tables are [exempt from access rules](https://docs.starburst.io/latest/security/file-system-access-control.html) and are always accessible to any authenticated user. This means the connector can query `INFORMATION_SCHEMA` in any catalog without explicit grants.

However, the `system` catalog requires an explicit rule for catalog discovery and materialized view detection. Add the following to your `rules.json` file:

```json
{
 "catalogs": [
 {
 "user": "atlan",
 "catalog": "system",
 "allow": "read-only"
 }
 ]
}
```

Replace `atlan` with your Atlan user's username.

:::info No catalog grants needed for metadata

Because `INFORMATION_SCHEMA` is exempt from file-based access control rules, you **don't** need to add `read-only` rules for each catalog you want Atlan to crawl. The connector only queries `INFORMATION_SCHEMA` tables—never actual data tables—so no catalog-level grant is required. However, `INFORMATION_SCHEMA` results are still filtered by the user's privileges: the connector only sees metadata for objects the user has at least one permission on. If your catalogs have no file-based table rules for the Atlan user, `INFORMATION_SCHEMA` returns all objects.

:::

### Configure data products access

File-based access control doesn't directly govern data products API access. If your cluster also uses [built-in access control](https://docs.starburst.io/latest/security/biac-overview.html) for data products, grant the `SHOW` privilege on data products to the Atlan user's role as described in the BIAC tab.

If built-in access control isn't enabled, any authenticated user can access the data products API.

## Verify permissions

After configuring access control, verify the Atlan user has the required permissions by running the following queries as the Atlan user. If any query fails with "Access Denied," verify that `EXECUTE` on Queries is granted to the user's role in BIAC (see [Grant query execution privilege](#grant-query-execution-privilege)).

```sql
-- Verify catalog discovery (the `state` column confirms Dynamic Catalogs is enabled)
SELECT catalog_name, connector_name, state FROM system.metadata.catalogs;

-- Verify INFORMATION_SCHEMA access (for each target catalog)
SELECT table_schema, table_name, table_type
FROM your_catalog.information_schema.tables
WHERE table_schema != 'information_schema'
LIMIT 10;

-- Verify column metadata access (for each target catalog)
SELECT table_schema, table_name, column_name, data_type
FROM your_catalog.information_schema.columns
WHERE table_schema != 'information_schema'
LIMIT 10;

-- Verify materialized view detection
SELECT catalog_name, schema_name, name
FROM system.metadata.materialized_views
LIMIT 10;
```

To verify data products access, test the following endpoint with the Atlan user's credentials:

```
curl -u atlan:password https://<your-starburst-host>/api/v1/dataProduct/domains \
 -H "X-Trino-Role: system=ROLE{atlan_metadata_reader}"
```

## Create Atlan API token

The connector requires an [Atlan API token](https://docs.atlan.com/llms/platform/get-started/api-access/llms.txt) to interact with the Atlan platform during workflow execution. Enter this token in the **Atlan API Token** field of the credential form when [configuring the crawler](https://docs.atlan.com/llms/connectors/starburst-enterprise/crawl-starburst-enterprise/llms.txt).

### Why is API token needed?

The connector uses the Atlan API to publish extracted metadata back into your Atlan tenant. Specifically, the token is used to:

* **Run Asset Import workflows**: Submit and monitor the import of Data Domains and Data Products into Atlan.
* **Search existing assets**: Look up Data Domain and Data Product qualified names to establish parent-child relationships.
* **Update Data Products**: Link Data Products to their parent Data Domains after import.
* **Manage Custom Metadata**: Check for and autocreate the "Starburst Data Product Ratings" Custom Metadata set and its color-coded badges on first run.

### Required permissions

The token must be created by a user with the **Admin** role in Atlan. By default, [API tokens inherit admin-level API privileges](https://docs.atlan.com/llms/platform/get-started/api-access/llms.txt) (excluding connection admin), which covers all operations the connector performs:

| Operation | Atlan capability |
| --- | --- |
| Submit and monitor Asset Import workflows | Workflow execution |
| Search Data Domains and Data Products by name | Asset read |
| Update Data Products with parent domain links | Asset write |
| Check and create Custom Metadata type definitions | Typedef read and write |
| Create Badge assets for source rating indicators | Asset write (global governance) |

:::warning Admin role required

A token created by a non-Admin user won't have sufficient privileges to run Asset Import workflows or create Custom Metadata definitions. See the [FAQ](https://docs.atlan.com/llms/connectors/starburst-enterprise/starburst-enterprise-connector-limitations/llms.txt) for details on what happens when the token lacks the required permissions.

:::

### Create token

Follow the steps in [API tokens](https://docs.atlan.com/llms/platform/get-started/api-access/llms.txt) to create a token. When configuring the token:

1. Use a descriptive name, for example `starburst-enterprise-connector`.
2. No personas are required. The connector only needs the default admin-level API privileges that every token inherits.
3. Copy the token immediately after creation and store it securely. You can't retrieve it later.

## Next steps

* [Crawl Starburst Enterprise](https://docs.atlan.com/llms/connectors/starburst-enterprise/crawl-starburst-enterprise/llms.txt): Configure and run the crawler to import metadata into Atlan.

---