# Register a Trino Connection ## Requirements **For Trino connections** * Trino cluster **For Starburst connections** * A valid [Starburst Enterprise license](https://docs.starburst.io/latest/license-requirements.html). * The Starburst Cluster must be publicly accessible or have [private connectivity](https://documentation.immuta.com/saas/configuration/application-configuration/how-to-guides/private-networking-support/data-connection-private-networking/index-2) configured. ## Permissions The user registering the connection must have the permissions below. * `APPLICATION_ADMIN` Immuta permission * The Trino user must have the ability to * Create a new file in the Trino `etc` directory * Create a new Trino user and grant that new user permissions ## Create the system account user In Trino, create a new system account user with the privileges listed below. Immuta uses this system account continuously to crawl the connection, maintain state between Immuta and Trino, and run identification. * `SELECT` on all securables you want registered in Immuta as data sources ## Register a Trino connection 1. In Immuta, click :database: **Data** and select **Connections** in the navigation menu. 2. Click the **+ Add Connection** button. 3. Select the **Trino** tile. 4. Enter the cluster 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**: URL of your Trino cluster. 3. **Port**: Port configured for Trino. 4. **SSL Mode**: Use the dropdown to select the SSL mode to connect to the host. 1. **Enabled**: Use this mode if you have `http-server.https.enabled=true` set in your Trino cluster's `config.properties` file. 2. **Disabled**: Use this mode for plain, unencrypted connections (e.g., your URL starts with `http://`). 5. **Certificate Validation**: Use the dropdown to select whether to require certificate validation to connect to the host. 1. **Enabled**: Use this to ensure Immuta verifies that the server's certificate was issued by a trusted Certificate Authority (CA). 2. **Disabled**: Use this setting if you are using a self-signed certificate to skip certificate validation for the connection. 5. Select the authentication method from the dropdown and enter the credentials of the [Trino user you created above](#create-the-system-account-user). 1. **Username and Password**: Enter the username and password for the system account user. 2. **OAuth 2.0 with Client Secret**: * Fill out the **Token Endpoint** with the full URL of the identity provider. This is where the generated token is sent. * Fill out the **Client ID**. This is a combination of letters, numbers, or symbols, used as a public identifier. This is the subject of the generated token. * Enter the **Scope** (string). The scope limits the operations allowed in Trino by the access token. See the [OAuth 2.0 documentation](https://oauth.net/2/scope/) for details about scopes. * Enter the **Client Secret**. Immuta uses this secret to authenticate with the authorization server when it requests a token. 3. **OAuth 2.0 with Client Certificate**: 1. Fill out the **Token Endpoint** with the full URL of the identity provider. This is where the generated token is sent. 2. Fill out the **Client ID**. This is a combination of letters, numbers, or symbols, used as a public identifier. This is the subject of the generated token. 3. Enter the **Scope** (string). The scope limits the operations allowed in Trino by the access token. See the [OAuth 2.0 documentation](https://oauth.net/2/scope/) for details about scopes. 4. Opt to fill out the **Resource** field with a URI of the resource where the requested token will be used. 5. Enter the **x509 Certificate Thumbprint**. This identifies the corresponding key to the token and is often abbreviated as `x5t` or is called `sub` (Subject). 6. Upload the **Client Certificate**, which is used to sign the authorization request. 6. Click **Save connection**. 1. If you are using **Starburst**, move on to the next step. 2. If you are using open-source **Trino**, you must download the Immuta Trino plugin and add it to your Trino cluster. 1. The Immuta Trino plugin version matches the version of [the corresponding Trino releases](#user-content-fn-2)[^2]. Navigate to the [Immuta GitHub repository](https://github.com/immuta/trino-artifacts/releases) for a list of supported Trino versions. Immuta follows [Starburst's release cycle](https://docs.starburst.io/latest/versions.html), but you can contact your Immuta representative for a specific Trino OSS release. 2. Download the assets for the release that corresponds to your Trino version. 3. Enable Immuta on your cluster: 1. **Docker installations** 1. Follow [Trino's documentation](https://trino.io/docs/current/installation/plugins.html#plugins-installation) to install the plugin archive on all nodes in your cluster. 2. Create the Immuta access control configuration file in the Trino configuration directory: **`/etc/trino/immuta-access-control.properties`**. 2. **Standalone installations** 1. Follow [Trino's documentation](https://trino.io/docs/current/installation/plugins.html#plugins-installation) to install the plugin archive on all nodes in your cluster. 2. Create the Immuta access control configuration file in the Trino configuration directory: **`/etc/immuta-access-control.properties`**. 7. On the **Next Steps** page, copy the provided `immuta-access-control.properties` file. It is pre-populated with the required fields: 1. `access-control.name`: Leave this as `immuta`. 2. `immuta.endpoint`: This is your tenant URL. Use the value provided in the file. 3. `immuta.apikey`: This is how Immuta applies policy to your users' queries. Use the value provided in the file. 4. `immuta.user.admin`: This is your Trino system account user. To ensure tables can be properly ingested into Immuta, no Immuta policies will ever apply to this user. Use the value pre-populated in the file to match the username you initially used to create the connection. 8. Customize any other properties in the file. See the [Customize the Immuta Trino plugin page](https://documentation.immuta.com/saas/configuration/integrations/starburst-trino/how-to-guides/register-a-trino-connection/customize-the-immuta-trino-plugin) for detailed descriptions of all the properties. 9. Once your file is customized, add it to your Trino cluster's `etc` folder. 10. Enable the Immuta access control plugin in your Trino cluster's **`config.properties`** file: 
access-control.config-files=/etc/trino/immuta-access-control.properties
11. Ensure you have completed all the connection steps, and click **Finish**. ### Add Trino users to Immuta 1. [Configure your external IAM](https://documentation.immuta.com/saas/configuration/people/section-contents/reference-guides/index) to add users to Immuta. 2. [Map their Trino usernames](https://documentation.immuta.com/saas/configuration/people/users-index/how-to-guides/external-user-mapping) when configuring your IAM (or map usernames manually) to Immuta. * All Trino users must map to Immuta users or match the `immuta.user.admin` regex configured on the cluster, and their Trino username must be mapped to Immuta so they can query policy-enforced data. * A user impersonating a different user in Trino requires the `IMPERSONATE_USER` permission in Immuta. Both users must be mapped to an Immuta user, or the querying user must match the configured `immuta.user.admin` regex. [^1]: Your display name cannot be any of the following words: `data`, `connection`, `object`, `crawl`, `search`, `settings`, `metadata`, `permission`, `sync`, `bulk`, and `upgrade`. [^2]: For example, the Immuta plugin version supporting Trino version 403 is simply version `403`. [^3]: If needed, update to `starburst`.