Trino Integration Reference Guide

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 object syncs and identification.

• 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 apply policies to user queries and provide query audit 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 Connections reference guide for details about connections and how to manage them. To configure your Trino connection, see the Register a Trino connection guide.

Applying policies

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 configuration file provided by Immuta. Additionally, you can continue to use Trino's file-based access control provider or Trino's built-in access control system on catalogs that are not protected or controlled by Immuta.

Subscription policies

Immuta enforces read and write subscription policies 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.

4. The query results are returned to the data consumer. If the user is not subscribed to the data source, it will result in ACCESS_DENIED.

Data policies

You can author data policies 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, queries the corresponding table 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.

   1. For each column, the Immuta Trino plugin requests a SQL view expression. If there are no masking policies on the column, nothing is returned.

   2. For each table, the Immuta Trino plugin requests the rows the user is allowed to see. If there is a row-level policy on the table, the Immuta API returns a corresponding view expression as a WHERE clause. If there are no row-level policies on the table, nothing is returned.

4. The Immuta Trino plugin provides the returned SQL view expression (for masked columns) or WHERE clause SQL view expression (for row filtering) to the Trino execution engine.

5. The Trino execution engine constructs and executes the SQL statement on the backing catalogs and retrieves the data with appropriate policy enforcement.

6. Data consumer sees policy-enforced data in their query result.

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

Trino privileges granted by Immuta

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

Trino query passthrough blocked

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 Customize the Immuta Trino plugin page for details.

Required Trino privileges

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.

Trino privilege	User requiring the privilege	Explanation
SELECT on all tables	Immuta system account	This privilege provides access to all the Trino tables that you want registered in Immuta.

Maintaining state with Trino

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.

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

Supported object types

Object type	Subscription policy support	Data policy support	Request app support
Table	✅	✅	✅
View	✅	✅	✅
Materialized view	✅	✅	✅

Trino-created logical view support

Immuta policies can be applied to Trino-created logical views.

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

• DEFINER security mode

• INVOKER security mode

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

Views created in the DEFINER security mode

For views created using the DEFINER security mode, follow the recommendations below:

• Ensure the user who created the view is configured as the admin user in the Immuta plugin so that policies are never applied to the underlying tables.

• Create Immuta data sources and apply policies to logical views exposing those tables.

• Lock down access to the underlying tables in Trino so that all end user access is provided through the views.

Views created in the INVOKER security mode

Avoid creating data policies for both a logical view and its underlying tables. Instead, apply policies to the logical view or the underlying tables.

For views created using the INVOKER security mode, the querying user needs access to the logical view and underlying tables.

• If non-Immuta table reads are disabled, provide access to the views and tables through Immuta. To do so, create Immuta data sources for the view and underlying tables, and grant access to the querying user in Immuta. If creating data policies, apply the policies to either the view or underlying tables, not both.

• If non-Immuta table reads are enabled, the user already has access to the table and view. Create Immuta data sources and apply policies to the underlying table; this approach will enforce access controls for both the table and view in Trino.

Object sync

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 Connections reference guide.

Supported policies

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:

• Subscription policy access types

• Data policy types

Security and compliance

Authentication methods

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

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

Rotating the Immuta API key

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 Rotate the system API key guide.

User registration and ID mapping

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 IAM protocols 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:

• Automatically: 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.

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

For guidance on connecting your IAM to Immuta, see the how-to guide for your protocol.

Limitations and caveats

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