Governed and delegated catalogs#
Every catalog on Starburst control plane is either governed or delegated. The setting says which access control authorizes the catalog.
Governed. Starburst access control alone controls the catalog. Starburst access control records its grants and its ownership.
Delegated. The access control of the cluster controls the catalog, for example built-in access control (BIAC).
Both kinds of catalogs live in control plane. The setting changes who authorizes access to the data, and not where the catalog is.
Starburst access control and the access control of the cluster are separate
security domains. A role in one system has no rights in the other. For example,
the accountadmin role of Starburst access control has no rights on a delegated
catalog, and the sysadmin role of BIAC has no rights on a governed catalog.
Choose governed or delegated#
Use a delegated catalog if the catalog needs one of the following:
User impersonation, such as the user impersonation of the PostgreSQL connector.
An access control system that Starburst access control doesn’t support for governed catalogs, such as Apache Ranger or AWS Lake Formation.
Control plane doesn’t check this when you create or switch a catalog. A governed catalog that uses one of these features doesn’t work as expected. Credential pass-through isn’t supported for any catalog yet. For more information, see Starburst Access Control overview.
Defaults#
A new catalog is governed. This is true if you create it with SQL, or through the API.
The built-in catalog
starburstis governed, and you cannot switch it.
What Starburst access control decides for every catalog#
Whatever the authorization of a catalog is, Starburst access control checks everything that is not scoped to the data of an individual catalog. For example:
Roles and the role statements.
Query management, system information, and system session properties.
Session user impersonation, which Starburst access control always rejects.
CREATE CATALOG.Catalogs that the cluster does not know, including
system.
GRANT ... ON CATALOG statements, and the grants and ownership of functions,
also go to Starburst access control, even when the catalog is delegated. GRANT,
REVOKE, DENY, and SHOW GRANTS on a table or a view go to the access
control of the catalog. A grantee in Starburst access control must be a role.
Set roles when you query both kinds of catalogs#
A query that reads both kinds of catalogs needs access in both systems. To set
your Starburst access control role, use the X-Trino-Role header, for example
X-Trino-Role: system=ROLE{analyst}. To set your BIAC role, use the
$biac-role extra credential, for example the JDBC parameter
extraCredentials=$biac-role:ROLE{analyst}.
If you do not set the extra credential, all of your BIAC roles are active in delegated catalogs. For more information, see Select a built-in access control role.
Governed catalogs and connector access control#
Starburst access control records the grants and the owners of a governed catalog.
It can do this only if the connector has no access control of its own. For the
Hive, Iceberg, and Delta Lake connectors, set hive.security,
iceberg.security, or delta.security to system in a governed catalog.
Control plane rejects a governed catalog whose connector still has its own
access control. The API returns HTTP status 400, and SQL returns the error
INVALID_CATALOG_PROPERTY. Without the setting, a governed catalog has no
owner, and queries fail with the error “Entity … has no owners”.
Limitations#
A
SECURITY DEFINERview that reads a catalog of the other authorization fails, in both directions.Objects that users created while the catalog was delegated have no owner in Starburst access control. Starburst access control uses the owner of the schema, and then the owner of the catalog, so the owner of the catalog can drop them. A
SECURITY DEFINERview on such an object fails until you give it an owner in Starburst access control withALTER … SET AUTHORIZATION ROLE.BIAC keys its grants by the name of the catalog. If you create a catalog again with the name of a dropped delegated catalog, it inherits the grants. If you rename a delegated catalog, the grants stay with the old name.
A statement that reads catalogs of both authorizations needs the privileges of both.
For the steps to move from built-in access control to Starburst access control, see Migrate to Starburst access control.