In this integration, Immuta policies are translated into Starburst rules and permissions and applied directly to tables within users’ existing catalogs.

This guide outlines how to integrate Starburst with Immuta.

How-to guides

• Register a Trino connection

• Starburst (Trino) integration configuration guide: Configure the integration in Immuta.

• : Configure how read and write access subscription policies translate to Starburst (Trino) privileges and apply to Starburst (Trino) data sources.

• : This guide describes the design and components of the integration when registered with a connection.

• : This guide describes the design and components of the integration.

Authentication

Registering the connection

The Trino integration supports the following authentication methods to register a connection. The credentials provided must be for an account with the permissions listed in the Register a Trino connection guide.

• Username and password: You can authenticate with your Trino username and password.

• OAuth 2.0: You can authenticate with OAuth 2.0. Immuta's OAuth authentication method uses the Client Credentials Flow; when you register a connection, Immuta reaches out to your OAuth server to generate a JSON web token (JWT) and then passes that token to the Trino cluster. Therefore, when using OAuth authentication to register a connection in Immuta, configure your Trino cluster to use JWT authentication, not OpenID Connect or OAuth.

The built-in Immuta IAM can be used as a complete solution for authentication and user entitlement. However, you can connect your existing identity management provider to Immuta to use that system for authentication and user entitlement instead.

Each of the supported identity providers includes a specific set of configuration options that enable Immuta to communicate with the IAM system and map the users, permissions, groups, and attributes into Immuta.

See the for a list of supported providers and details.

See the for details about user provisioning and mapping user accounts to Immuta.

Multiple system access control providers can be configured in the Trino integration. This approach allows Immuta to work with existing Trino installations that already have an access control provider configured.

Immuta does not manage all permissions in Trino, so it will default to allowing access to anything Immuta does not manage. This ensures that the Trino integration complements existing controls.

For example, if the Trino integration is configured to allow users write access to tables that are not protected by Immuta, you can still lock down write access for specific non-Immuta tables using an additional access control provider.

If you have multiple access control providers configured, those providers interact in the following ways:

• For a user to have access to a resource (catalog, schema, or a table), that user must have access in all of the configured access control providers.

• In catalog, schema, or table filtering (such as show catalogs, show schemas, or show tables), the user will see the intersection of all access control providers. For example, if a Trino environment includes the catalogs public, demo, and restricted

See the for details on configuring multiple access control providers.

Immuta provides auditing features and governance reports so that data owners and governors can monitor users' access to data and detect anomalies in behavior.

You can view the information in these audit logs on or export the full audit logs to S3 and ADLS for long-term backup and processing with log data processors and tools. This capability fosters convenient integrations with log monitoring services and data pipelines.

See the for details about these capabilities and how they work with the Trino integration.

Immuta captures queries in Trino, making audit records more useful in assessing what users are doing. To audit Trino queries, Immuta uses the Trino event listener to translate events in comprehensive audit logs. Immuta will only audit queries from Immuta users on objects registered as Immuta data sources.

Query audit is enabled by default on all Trino integrations, but you can disable it when by changing the following properties in the : immuta.audit.legacy.enabled and immuta.audit.uam.enabled.

See the for audit log contents and an example of the resulting audit record.

Immuta governance reports allow users with the GOVERNANCE Immuta permission to use a natural language builder to instantly create reports that delineate user activity across Immuta. These reports can be based on various entity types, including users, groups, projects, data sources, purposes, policy types, or connection types.

See the page for a list of report types and guidance.

In the Trino integration, the Trino Immuta plugin enforces policies on data registered in Immuta at query time. The sequence diagram below outlines the events that occur when an Immuta user who is subscribed to a data source queries it in Trino.

Registering a connection

Trino is configured and data is registered through connections, an Immuta feature that allows administrators to register data objects in a technology through a single connection to make data registration more scalable for your organization.

Once the Trino connection is registered, you can author subscription and data policies in Immuta to enforce access controls.

See the Trino integration reference guide for more details about registering a connection.

Protecting data

After data objects are registered in Immuta, you can author data and subscription policies in Immuta to enforce access controls.

Subscription policies

When a subscription policy is applied to a data source, users who meet the conditions of the policy will be automatically subscribed to the data source. Then, the Trino Immuta plugin will allow the user to query that object.

See the for guidance on applying a subscription policy to a data source. See the for details about the subscription policy types supported and Trino privileges Immuta grants on objects registered as Immuta data sources.

When a data policy is applied to a data source and a user subscribed to that data source queries it, the Immuta Trino plugin will request the policy definitions from the Immuta API. The Immuta API returns a SQL view definition to represent data policies. After that, the user's query result will be returned with the policy-protected data.

See the for guidance on authoring data policies in Immuta and the for the Trino integration.

Once data is registered through the Trino connection, you will access your data through your Trino cluster as you normally would. If you are subscribed to the data source, Immuta grants you access to the data in Trino.

When you submit a query, the Trino Immuta plugin reaches out to Immuta and then provides policy decisions to the Trino execution engine. Then, the Trino execution engine applies policies to the backing catalogs and processes the query. You then get back the policy-enforced data.

The diagram below illustrates how Immuta, the Trino Immuta plugin, and the Trino execution engine interact when you access data.

User impersonation

User impersonation allows Trino users to query data as another Immuta user. The Trino integration supports native Trino impersonation approaches:

• JDBC method: In your JDBC connection driver properties, set the sessionUser property to the Immuta user you want to impersonate. See the for details.

• Trino CLI method: Set the --session-user property to specify the session user as the Immuta user you want to impersonate when invoking the . See the for details.

User impersonation is automatically enabled with your Trino integration, but the authenticated user must be or match the Trino .

When you register the Trino connection, Immuta generates an API key for you to add to your Immuta access control properties file for API authentication between Starburst (Trino) and Immuta. You can rotate this shared secret to mitigate potential security risks and comply with your organizational policies.

1. Disable your Starburst (Trino) cluster.

2. Copy the request example below and replace these values:

   • Replace the Immuta URL with your own and the with your own user API key.

   • Replace the following parameters:

     • name parameter with the unique name of the Trino API key you want to regenerate.

     • connectionKey parameter of the Trino connection associated with the API key.

   Once you make this request, your old Immuta API key will be deleted and will no longer be valid.

3. The response includes your new Immuta API key. with this new key.

4. .

• 400: Connection key not found, scopes invalid, or a key with the same name exists for a different connection or scope.

Requirements

For Trino connections

• Trino cluster

For Starburst connections

• A valid Starburst Enterprise license.

• The Starburst Cluster must be publicly accessible or have configured.

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

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

1. In Immuta, click Data and select Connections in the navigation menu.

2. Click the + Add Connection button.

3. Select the Trino tile.

1. to add users to Immuta.

2. 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.

The how-to guides linked on this page illustrate how to integrate Starburst (Trino) with Immuta. See the reference guide for information about the Starburst (Trino) integration.

When you register a connection, there is a provided immuta-access-control.properties file pre-populated with the required properties. You can also add these additional properties to further customize your connection.

immuta-access-control.properties

The example configuration snippet below uses the default configuration settings for immuta.allowed.immuta.datasource.operations and immuta.allowed.non.immuta.datasource.operations, which allow read access for data registered as Immuta data sources and read and write access on data that is not registered in Immuta. See the for details about customizing and enforcing read and write access controls in Starburst.

The plugin comes pre-installed with Starburst Enterprise, so this page provides separate sets of guidelines for configuration:

• Starburst Cluster Configuration: These instructions are specific to Starburst Enterprise clusters.

• Trino Cluster Configuration: These instructions are specific to open-source Trino clusters.

Starburst Cluster Configuration

Requirements

• A valid .

• The Starburst Cluster must be publicly accessible or have configured.

1. Click the App Settings icon in the navigation menu.

2. Click the Integrations tab.

3. Click Add Integration and select Trino from the Integration Type dropdown menu.

1. Create the Immuta access control configuration file in the Starburst configuration directory (/etc/starburst/immuta-access-control.properties for Docker installations or <starburst_install_directory>/etc/immuta-access-control.properties for standalone installations).

   The table below describes the properties that can be set during configuration.

   Property

   Starburst version

   Required or optional

The example configuration snippet below uses the default configuration settings for immuta.allowed.immuta.datasource.operations and immuta.allowed.non.immuta.datasource.operations, which allow read access for data registered as Immuta data sources and read and write access on data that is not registered in Immuta. See the for details about customizing and enforcing read and write access controls in Starburst.

1. to add users to Immuta.

2. when configuring your IAM (or map usernames manually) to Immuta.

   • All Starburst users must map to Immuta users or match the immuta.user.admin regex configured on the cluster, and their Starburst username must be mapped to Immuta so they can query policy-enforced data.

.

1. Click the App Settings icon in the navigation menu.

2. Click the Integrations tab.

3. Click Add Integration and select Trino from the dropdown menu.

1. The Immuta Trino plugin version matches the version of the corresponding Trino releases. For example, the Immuta plugin version supporting Trino version 403 is simply version 403. Navigate to the for a list of supported Trino versions. Immuta follows , 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. Select the tab below that corresponds to your installation method for instructions:

1. Configure the properties described in the table below.

   Property

   Trino version

   Required or optional

   Description

The example configuration snippet below uses the default configuration settings for immuta.allowed.immuta.datasource.operations and immuta.allowed.non.immuta.datasource.operations, which allow read access for data registered as Immuta data sources and read and write access on data that is not registered in Immuta. See the for details about customizing and enforcing read and write access controls in Starburst.

1. to add users to Immuta.

2. 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.

.

Requirements

• Starburst (Trino) version 438 or newer

• Write policies for Starburst (Trino) enabled. Contact your Immuta representative to get this feature enabled on your account.

Configuration options

In its default setting, the Starburst (Trino) integration's write access value controls the authorization of SQL operations that perform data modification (such as INSERT, UPDATE, DELETE, MERGE, and TRUNCATE). However, administrators can allow table modification operations (such as ALTER and DROP tables) to be authorized as write operations. Two locations allow administrators to specify how are applied to data in Starburst (Trino). Select one or both of the options below to customize these settings. If the access-control.properties file is used, it may override the policies configured in the Immuta web service.

• Immuta web service: Configure write policies in the Immuta web service to allow all Starburst (Trino) clusters targeting that Immuta tenant to receive the same write policy configuration for data sources. This configuration will only affect tables or views registered as Immuta data sources.

• Starburst (Trino) cluster: Configure write policies using the access-control.properties file in or to broadly customize access for Immuta users on a specific cluster. This configuration file takes precedence over write policies passed from the Immuta web service. Use this option if all Immuta users should have the same level of access to tables regardless of the write policy setting in the Immuta web service.

Contact your Immuta representative to configure read and write access in the Immuta web service if all Starburst (Trino) data source operations should be affected identically across Starburst (Trino) clusters connected to your Immuta tenant. A configuration example is provided below.

The following example maps WRITE to READ, WRITE and OWN permissions and READ to just READ. Both READ and WRITE permissions should always include READ:

Given the above configuration, when a user gets write access to a Starburst (Trino) data source, they will have both data and table modification permissions on that data source. See the Starburst (Trino) privileges section of the for details about these operations.

Modify one or both properties below in the immuta-access-control.properties file in your Trino or Starburst cluster to customize the behavior of read or write access policies for all users:

• immuta.allowed.immuta.datasource.operations: This property governs objects (catalogs, schemas, tables, etc.) that are registered as data sources in Immuta. These permissions apply to all querying users except for administrators defined in immuta.user.admin (who get all permissions).

  • READ: Grants SELECT on tables or views; grants SHOW on tables, views, or columns

For example, the following configuration allows READ, WRITE, and OWN operations to be authorized on data sources registered in Immuta and all operations are permitted on data that is not registered in Immuta:

Using the Trino connection, you can register a Trino integration for your open-source Trino or Starburst Enterprise cluster.

The sequence diagram below outlines the events that occur when an Immuta user wants to query a Trino table that has been registered as an Immuta data source.

What does Immuta do in my Trino cluster?

Registering a connection

Immuta utilizes connections to register and manage data from your entire Trino cluster all at once. This approach simplifies data registration and allows Immuta to automatically monitor your Trino platform for changes. Data sources are then added or removed to reflect the current state of your data platform.

When a connection is first registered, Immuta will complete or ask your application admin to complete a few actions:

• The application admin must provide credentials that Immuta will use to initially register all of your Trino tables as data objects. Immuta will also continue to use those credentials for scheduled and .

• The application admin will also install the Immuta Trino plugin on your Trino cluster and update your Trino cluster's config.properties file to use the Immuta Trino plugin for access control. Immuta will use the Immuta Trino plugin to to user queries and provide events.

• Immuta ingests and stores connection metadata in the Immuta metadata database.

Immuta presents a hierarchical view of your data that reflects the hierarchy of objects in Trino after registration is complete:

• Cluster

• Catalog

• Schema

• Tables

Beyond making the registration of your data more intuitive, connections provide more control. Instead of performing operations on individual schemas or tables, you can perform operations (such as object sync) at the connection level.

See the for details about connections and how to manage them. To configure your Trino connection, see the .

By default, the Trino integration is designed to be minimally invasive: if a catalog is not registered as an Immuta data source, users will still have access to it in Trino.

However, this limited enforcement can be changed in the provided by Immuta. Additionally, you can continue to use Trino's file-based access control provider or on catalogs that are not protected or controlled by Immuta.

Immuta enforces read and write on Trino tables by checking the user's access at query time and resulting in the appropriate access.

Once the connection is registered, this is what happens when a user makes a query in Trino:

1. User runs a query for a Trino table registered in Immuta.

2. Trino checks with the Immuta Trino plugin in charge of access control to see if the user should see the table.

3. The Immuta Trino plugin reaches out to the Immuta API to confirm table access.

You can author in Immuta to enforce fine-grained access controls on Trino data objects registered as Immuta data sources.

Once a data policy is applied to a Trino data source in Immuta,

1. A Trino user, who is subscribed to the data source in Immuta, directly in their Trino catalog.

2. The Trino execution engine calls various methods on the interface to ask the Immuta Trino plugin where the policies should be applied. The masking and row-level security methods apply the actual policy expressions.

3. The Immuta Trino plugin calls the Immuta API to retrieve policy information for that data source for the querying user, using the querying user's project, purpose, and entitlements.

See the for a matrix on the data policies supported for this integration.

See the for details about the Trino privileges granted to users when they are subscribed to a data source protected by a subscription policy.

Trino's query passthrough is available in most connectors using the query table function or raw_query in the Elasticsearch connector. Consequently, Immuta blocks functions named raw_query or query, as those table functions would completely bypass Immuta’s access controls.

For example, without blocking those functions, this query would access the public.customer table directly:

select * from table(postgres.system.query(query => 'select * from public.customer limit 10'));

You can add or remove functions that are blocked by Immuta in the Trino configuration file. See the for details.

The privileges that the Trino connection requires align to the least privilege security principle. The table below describes the privilege required by the IMMUTA_SYSTEM_ACCOUNT user.

The following user actions spur various processes in the Trino connection so that Immuta data remains synchronous with data in Trino. The list below provides an overview of each process:

• Data source created or updated: Immuta registers data source metadata and stores that metadata in the Immuta metadata database.

• Data source deleted: Immuta deletes the data source metadata from the metadata database.

• : When a user account is mapped to Immuta, their metadata is stored in the metadata database.

Immuta policies can be applied to .

The descriptions below provide guidance for applying policies to Trino-created logical views in two modes:

However, there are other approaches you can use to apply policies to Trino-created logical views. The examples below are the simplest approaches.

Supported object types are found by object sync and automatically kept up to date. The performance of object sync is dependent on how quickly Trino can pull information from the underlying systems. This can impact the time object sync takes to complete.

For more details about object sync, see the .

The Trino integration allows users to author subscription and data policies to enforce access controls. See the corresponding pages for details about specific types of policies supported:

The Trino integration supports the following authentication methods to register a connection. The credentials provided must be for an account with the permissions listed in the .

• Username and password: You can authenticate with your Starburst (Trino) username and password.

• OAuth 2.0: You can authenticate with OAuth 2.0. Immuta's OAuth authentication method uses the ; when you register a connection, Immuta reaches out to your OAuth server to generate a JSON web token (JWT) and then passes that token to the Trino cluster. Therefore, when using OAuth authentication to register a connection in Immuta, configure your Trino cluster to use JWT authentication, not OpenID Connect or OAuth.

When you register the connection, Immuta generates an API key for you to add to your Immuta access control properties file for API authentication between Starburst (Trino) and Immuta. You can rotate this shared secret to mitigate potential security risks and comply with your organizational policies.

To rotate this API key, see the .

The built-in Immuta IAM can be used as a complete solution for authentication and user entitlement. However, you can connect your existing identity management provider to Immuta to use that system for authentication and user entitlement instead. Each of the includes a set of configuration options that enable Immuta to communicate with the IAM system and map the users, permissions, groups, and attributes into Immuta.

For policies to impact the right users, the user account in Immuta must be mapped to the user account in Trino. You can ensure these accounts are mapped correctly in the following ways:

• : If usernames in Trino align with usernames in the external IAM and those accounts align with an IAM attribute, you can enter that IAM attribute on the app settings page to automatically map user IDs in Immuta to Trino.

• : You can manually map user IDs for individual users.

For guidance on connecting your IAM to Immuta, see the .

• Tag ingestion is not supported.

• Object sync may be delayed due to delays in Trino and the underlying data platforms.

• Limit your masked joins to columns with matching column types: Trino truncates the result of the masking expression to conform to the column type when performing the join, so joining two masked columns with different data types produces invalid results when one of the columns' lengths is less than the length of the masked value.

  For example, if the value of a hashed column is 64 characters, joining a hashed varchar(50) and a hashed varchar(255) column will not be joined correctly, since the varchar(50) value is truncated and doesn’t match the varchar(255) value.