Privileges #

A privilege granted to a role conveys the right to perform specific operations.

The grantor of a privilege is not recorded as part of grant, it is only stored in the audit log.

Entity privileges grant rights to a single entity or a collection of entities of the same kind, for example, the right to SELECT rows from a specific table, the entity in this case.

Account privileges are not associated with a specific entity. Account privileges include rights to create new top-level entities, such as clusters, catalogs and users, and rights to manage security for all entities.

Grant a privilege #

One role can be used to grant a privilege for a specific entity to any other role under the following circumstances:

  • Role includes the grant WITH ADMIN OPTION
  • Role is the owner of the entity.
  • Role has the Manage security role.

Account privileges #

  Account privilege selected

Use the following privileges to control allowed actions on the Account entity. Adding privileges to the Account entity determines the access rights of your Starburst Galaxy account:

Privilege Grants ability to
Create catalog Create a new catalog. Does not convey the right to use, modify or delete any catalog.
Create cluster Create a new cluster. Does not convey the right to modify, stop or start any cluster.
Create role Create a new role. Does not convey the right to grant, modify or delete any role.
Create user Create a new user. Does not convey the right to modify or delete any user, nor to grant or revoke roles to the user.
Manage billing View usage and billing and update account profile.
Manage security This is the most powerful privilege for security management. A role with this privilege can:
  • Grant or revoke any privilege on any entity to any role.
  • Grant any role to any user, including themselves, or revoke any role grant.
  • Create, update, or delete any user or any role.
By itself, manage security does not grant full administrative access to all privileges, all entities and therefore also to all connected data sources. However a user with this privilege can grant themselves full access to everything. Only grant this privilege to a minimal list of trusted roles. Note that the accountadmin role is granted this privilege.
Manage service account Create and manage a service account that allows a non-human user to authenticate and access cluster data.
Manage single sign on Add, edit, or replace the configuration of this account's relationship with an external identity provider that supports single sign-on.
View all query history View the query history and query details of queries initiated by all users.
View audit log View the history of privilege grants and major transactions. If single sign-on is enabled, view the grants and transactions with an identity provider.

Cluster privileges #

You can use the following privileges to control allowed actions on the cluster entities:

Privilege Grants ability to
Start/stop cluster Start or stop the cluster.
Use cluster View a cluster and run queries on the cluster. Does not convey the right to modify, stop, or start the cluster, or to access any data in the catalogs attached to the cluster.

Catalog privileges #

Catalogs are identified by catalog name, and catalog names must be unique within your Starburst Galaxy account. The only privilege on a catalog is Create schema, which allows a role with that privilege to create new schemas in the catalog.

A catalog is visible to a role in any of the following situations:

  • The role has the Create schema privilege on the catalog.
  • The role has some privilege on a schema or table contained in the catalog.
  • The role is the catalog owner.
  • The role has the Manage security privilege.

When a catalog is created, the creating user is prompted to specify roles that can read from and/or write to the catalog. These roles are granted wildcard permissions on schemas and tables in the catalog.

Privilege Grants ability to
Create schema Allows creation of new schemas inside the catalog. To rename a schema, a role must own the schema in addition to having the Create schema privilege on the catalog.

Schema privileges #

Schemas have names and are contained in a catalog. By default, the role that owns the catalog containing the schema also owns the schema, but you can change the schema owner in the UI and in Trino.

In SQL, you can set the owner of a schema monthly_sales in catalog prod_data to role sysadmin this way:

ALTER SCHEMA prod_data.monthly_sales
SET AUTHORIZATION ROLE sysadmin

You can see the current owner of a schema from the SHOW CREATE statement:

SHOW CREATE SCHEMA prod_data.monthly_sales

A schema can contain one or more tables and/or views.

Privilege Grants ability to
Create table Allows creation of new table entities inside a schema within a catalog. To rename a table, a role must own the table in addition to having the Create table privilege on the schema.

Table and view privileges #

Tables and views have names, and are contained in a schema, which in turn is contained in a catalog. By default, the role that owns the schema containing the table owns the table. If there is no explicitly specified role owning the schema, then the role owning the table is the one that owns the catalog.

In SQL, you can set the owner of a table june_sales in schema monthly_sales in catalog prod_data to role sysadmin this way:

ALTER TABLE prod_data.monthly_sales.june_sales
SET AUTHORIZATION ROLE sysadmin

Tables have the following privileges that can be granted either with SQL commands or in the Starburst Galaxy UI:

SQL privilege UI privilege Grants ability to
SELECT Select from table Allows selection of columns from the table.
INSERT Insert into table Allows insertion of new rows in the table.
UPDATE Update table rows Allows update of rows in the table.
DELETE Delete from table Allows deletion of rows in the table.

The following details apply for views.

  • Views are stored in the metastore.
  • Views without explicit owners are disabled.
  • Views configured with SECURITY DEFINER are disabled. The run-as identity for views with SECURITY DEFINER is the explicitly defined owner of the view.
  • The catalog owner is not set as the run-as identity for views, and can therefore not execute them.
  • The catalog owner can drop and alter views.

This behavior prevents a privilege escalation. You can not declare a view in an external system with limited privileges, and then execution the view in Starburst Galaxy with the catalog owner’s privileges.

Column privileges #

The Column privilege grants SELECT or UPDATE privileges to a column within a table. This privilege is commonly used to deny access to a column, specifically a column containing sensitive financial or personal identifying information.

If a query is run on a table that has columns on which SELECT is denied, those columns are omitted from the result set.

To grant a SELECT or UPDATE privilege, a role in the active role set must have a table-level grant of the same privilege with grant option.

Location privileges #

  Location privilege selected

The location privilege applies only to object storage catalogs. Use this privilege to restrict creating or altering objects in unexpected object storage locations outside the configured default location of the current catalog.

Your cloud provider credentials, such as an IAM role or AWS key for S3 catalogs, may have broad access rights to multiple locations. If you provide these credentials when creating a catalog for a narrow location, users connecting to that catalog may have the inadvertently granted right to make changes outside that narrow location.

Let’s say you create a catalog to access the S3 location s3://bucket-name/folder-name/, but you create the catalog with an AWS key that has write rights throughout all of s3://bucket-name/*. This allows anyone connecting to this catalog to create, for example, s3://bucket-name/different-folder.

If you set the location privilege for a role to s3://bucket-name/folder-name/*, you restrict creation or alteration of schemas or tables to the folder-name location only for that role.

The location privilege is only verified for CREATE or ALTER operations of a table or schema, because these are the only operations capable of creating objects outside the default location of the catalog. If that operation is within the configured location of the catalog, the catalog privileges and schema privileges are also considered.

The location privilege is not checked for SELECT, INSERT, UPDATE, or DELETE operations on object storage tables, where table privileges manage access instead.

A single location privilege is available to grant to any role:

Privilege Grants ability to
Create SQL Restricts creation or alteration of schemas or tables to only within the specified location.

The location privilege can only be set with the Starburst Galaxy UI, and not with a SQL command. The Create SQL privilege does not correspond to any SQL statement.

When you select the Location button, Galaxy prompts you to enter an object storage URI. Use a format similar to the following examples, and adapted to your object storage URI pattern and naming:

s3://*
s3://bucket-name/abc/xyz/*
gs://*
gs://bucket-name/abc/xyz/*
abfs://file-system@storage-account.dfs.core.windows.net/*
abfs://file-system@storage-account.dfs.core.windows.net/abc/xyz/*

The Create SQL checkbox and Add privileges button do not activate until you enter a URI with a valid format ending with /*. However, Galaxy does not check the specified URI’s location for validity.

Location privilege placeholder roles

Function privileges #

Function privileges allow you to control access to table functions in specific catalogs.

Query pass-through table function #

The query or raw_query query pass-through table functions are available in the following catalogs:

By default, access to these functions is disabled. Use the function privilege to grant access to the table functions in specific catalogs to specific roles.

Query pass-through allows you to use the native query language of the underlying data source to compose a query string, and pass it directly to the data source as argument for a table function. This query needs to return a table as result set of at least one column with one value:

SELECT * FROM TABLE(
    example.system.query(query =>
       'query_string'
    )
)

The invocation references the catalog name example and accesses the query or raw_query in the system schema. The query and raw_query table functions are always located in the system schema. The supplied query_string in the native query language must be valid in the data source. It is typically the SQL dialect of the database, but can also be another query language such as the Elasticsearch Query DL in the case of an Elasticsearch data source. The native query returns a table, which in turn can be used in the containing SQL query like any other table reference. In the preceding example, all columns and rows of the table are returned as provided by the table function, due to the SELECT * FROM.

Wildcard privileges #

Wildcard permissions are useful for catalogs managed outside of Starburst Galaxy, as they define privileges on tables and schemas that do not exist yet.

Many catalogs have large numbers of schemas and tables, and it is not practical to grant privileges on each one individually. Instead, wildcard privilege grants can be used to grant privileges on every table in a specific schema or catalog. Wildcard privileges are supported only for schema and table entities.

Table wildcard privilege grants #

Tables are identified by the name of a catalog, the name of a schema contained in the catalog, and the name of a table within the schema. Table june_sales in schema monthly_sales in catalog prod_data is represented as prod_sales.monthly_sales.june_sales.

Tables support privileges to SELECT, INSERT, DELETE and UPDATE the table. A table wildcard represents either all tables in a catalog regardless of the schema name, or all tables in a specific schema inside a catalog. A grant of SELECT on any table contained in any schema in the catalog prod_data is denoted as prod_data.*.*. Similarly, a grant of SELECT on any table in schema monthly_sales in catalog prod_data is denoted by prod_data.monthly_sales.*.

You can grant wildcard table privileges using the UI Add privileges dialog. Alternatively, you can grant wildcard table privileges using SQL. A grant of SELECT on all tables in all schemas in catalog prod_data to role read_only_users looks like:

GRANT SELECT ON "prod_data"."*"."*" TO ROLE read_only_users

The schema and table wildcards must be in double quotes because * has special meaning in SQL.

Similarly, a grant of SELECT on all tables in schema monthly_sales in catalog prod_data to role read_only_users looks like:

GRANT SELECT ON "prod_data.monthly_sales"."*" to ROLE read_only_users

You can create exceptions to wildcard table grants using deny table grants. Suppose a role has received a wildcard grant of SELECT on prod_data.*.*, allowing SELECT on any table in any schema in catalog prod_data. If the role is denied the SELECT for wildcard prod_data.monthly_sales.*, all tables in schema monthly_sales will be inaccessible to that role no matter what other grants the role has received.

Schema wildcard privilege grants #

Schemas support just one privilege – Create table. A schema wildcard consists of a catalog name and a schema name of *. If the name of the catalog is prod_data, a grant of CREATE_TABLE to schema prod_data.* grants the privilege CREATE_TABLE on all schemas in catalog prod_data to a role. This is done in the UI in the Add privileges dialog.

You can grant Create table to a role in Trino:

GRANT CREATE ON SCHEMA "prod_data.*" TO ROLE prod_maintainer_role

You can create exceptions to a wildcard schema privilege grant by creating deny privilege grants in both the UI and in SQL. Given a grant of CREATE_TABLE to all schemas in catalog prod_data, denoted by prod_data.*, granting a deny privilege for schema prod_data.monthly_sales to the role creates an exception that denies the schema privilege CREATE_TABLE on schema monthly_sales to the role.

Read only access with wildcard privileges #

Catalog creation includes an optional step to assign read only access for a catalog. You can achieve the same behavior by creating a wildcard privilege for all schemas and tables in a catalog mycatalog.*.* that grants the SELECT privilege.

Full read and write access with wildcard privileges #

Catalog creation includes an optional step to assign full read and write access for a catalog. You can achieve the same behavior with the following setup:

  • Grant the Create schema privilege on the catalog.
  • Grant a wildcard privilege of CREATE_TABLE to any schema in the catalog mycatalog.*.
  • Grant a wildcard privilege of SELECT to any table in any schema in the catalog mycatalog.*.*.
  • Grant a wildcard privilege of INSERT to any table in any schema in the catalog mycatalog.*.*.
  • Grant a wildcard privilege of UPDATE to any table in any schema in the catalog mycatalog.*.*.
  • Grant a wildcard privilege of DELETE to any table in any schema in the catalog mycatalog.*.*.

Deny a privilege #

The effect of a privilege grant on an entity to a role can be reversed by granting a deny privilege to that role. This is most useful for table privileges, but any inherited privilege on any entity can be denied. Learn more details in wildcard privileges.

A deny privilege grant can create an exception to a wildcard privilege grant, preventing the access that the privilege grant previously allowed.

Deny privilege grants always override grants that allow access, including any inherited from roles and wildcards. Deny privilege grants should therefore be rarely used, and are typically used only to override a wildcard grant.

Deny privileges are most useful for schemas and tables, to create exceptions to wildcard privilege grants. However, any privilege grant to a role or inherited from a child role on any entity can be reversed with a deny privilege grant to the role. For example, “upper_role” might inherit privilege Create user from “lower_role”. That privilege can be reversed by granting a deny privilege for Create user to “upper_role”.

You can create deny privileges in the UI using the privileges dialogs. The following examples of using the SQL statement DENY correspond to the examples from the wildcard privileges section:

You can deny table privileges to a role with SQL:

DENY SELECT ON "prod_data.monthly_sales"."*" TO read_only_users

You can deny a CREATE_TABLE privilege on the schema monthly_sales this way:

DENY CREATE ON SCHEMA prod_data.monthly_sales

SQL does not provide a mechanism to grant or deny privileges on clusters, users, or catalogs.