Immuta access control support#

Starburst Enterprise platform (SEP) provides support for using an existing Immuta attribute-based access control system.


To use the Immuta access control system with Starburst Enterprise, you need:

  • A current Immuta account and API key.

  • A valid Starburst Enterprise license.

  • A policy covering all users that provides read access to system.metadata, system.jdbc, and system.runtime.

Immuta support overview#

The following steps provide an overview of the Immuta support in SEP.

  1. Configure catalogs as usual for your cluster’s data sources.

  2. Configure a catalog for an Immuta connector.

  3. In the Immuta web dashboard, create one entry for each schema to be managed by Immuta. Immuta creates a view under its control to represent the schema.

  4. Configure an Immuta event listener for your cluster.

  5. Configure SEP file-based access control.

These steps redirect all SEP queries to pass through Immuta access control for validation. On acceptance, Immuta passes the query back to SEP for analysis and execution.

User authentication#

Immuta manages access control for existing user and group names. Those names are independently authorized to access the SEP cluster by the authentication types currently configured and active on the cluster. Immuta works with any authentication type supported by SEP.

Query behavior changes#

When you add schemas to Immuta in the Immuta web UI, specify a prefix or suffix for Immuta schema names to distinguish them from their underlying names. If you have the same table name in more than one SEP catalog, specify unique names for each so that they can be distinguished when under Immuta’s control.

With Immuta configured, run all SQL queries the same as without Immuta, with two exceptions: you must use the single catalog name immuta and must use the names of schemas as known to Immuta.

As before, standard users can use any client, such as the query editor in the Starburst Enterprise web UI, to browse through the immuta catalog to locate a schema and table of interest. SEP’s catalog.schema.table hierarchy remains the same. Standard users might use the following query for the customers table:

select * from immuta.orcl_accounting.customers limit 100;

With system access control configured as recommended, admin users are able to see the underlying schema names as known to SEP. For troubleshooting and administrative purposes, admin users can reach the same customers table as follows:

select * from oracle.accounting.customers limit 100;


In the following sections, the etc folder refers to the location of your cluster’s configuration files and catalog folder. Depending on your cluster’s installation method, the etc folder might be in /etc/starburst, /opt/starburst/etc, or another location.

Configure Immuta connector#

The necessary Immuta plugin and drivers are shipped with SEP 369-e and later. Activate the plugin by creating a configuration file in your cluster’s etc/catalog folder whose basename matches the connector-name value. Use the following pattern:

For example, in a file named

Configure Immuta event listener#

In order for Immuta to audit queries in your SEP cluster, configure an Immuta audit event listener in a file named The immuta.catalogs value must match the connector-name value previously specified. For example:

Manage system access control#

Two remaining considerations are not under Immuta’s control:

  • For standard users, block catalogs from direct access, which would bypass Immuta.

  • Protect Immuta-managed tables from inadvertent secrets disclosure.

Configure these tasks with SEP’s file system access control and a JSON rules file. These rules take effect when SEP starts, before Immuta is engaged.

To use this system, add a configuration file named to the etc folder with two required lines, as in the following example:

The path to the rules file is relative to SEP’s’ start-up directory, which is usually one level above etc.

The following example shows a starting point for an access-rules.json file:

"catalogs": [
    "user": "super_admin",
    "catalog": "immuta|postgres|redshift|mysql|oracle|system",
    "allow": "all"
    "user": "IT",
    "catalog": "immuta",
    "allow": "all"
    "user": "query_user",
    "catalog": "immuta",
    "allow": "read-only"
    "catalog": "postgres|redshift|mysql|oracle|system",
    "allow": "none"

This rules file:

  • Allows super_admin full access to all catalogs, Immuta-managed and not.

  • Allows IT full access to Immuta-managed objects but not the SEP-defined base catalogs.

  • Allows query_user read-only access to Immuta managed schemas and tables. This allows all queries but prevents users from running DESCRIBE on Immuta views, which in turn prevents disclosure of any secrets involved in some masking policies.

  • Sets the default access to non-Immuta catalogs to none. In this set of rules, only super_admin has any access to those catalogs.

If you are setting up a new cluster, you can also use file-based rules to protect access to catalogs before Immuta is installed and configured. If you do this, be sure to remove or adjust those rules before Immuta takes over full access control.