Policies#
Attribute-based access control (ABAC) policies control access to data. This page describes how to create and manage them in the Control Plane UI. You can also manage policies with the Control Plane API.
A policy is granted to a role, and it applies to users whose active role set includes that role. A policy has the following parts:
Scope: The catalogs, schemas, and tables that the policy covers, such as all tables in the
icebergcatalog.Matching expression: An optional condition that selects data in the scope, such as data with a specific tag. Without one, the policy covers all data in its scope.
Privileges, row filters, and column masks: What the policy does with the data that it selects. A policy can allow or deny privileges, filter rows, mask columns, or any combination of these.
Policies apply only to governed catalogs. Delegated catalogs keep their existing access control.
Create a policy#
In the Control Plane UI, go to Access > Roles and privileges, and select the role to grant the policy to.
Open the Policies tab and click Create Policy.
Enter a name and, optionally, a description. The name can contain only lowercase letters, numbers, and underscores.
Optionally, to set an expiration date for the policy, turn on Apply an expiration date to this policy? and select the date and time. Click Next.
In Catalogs, Schemas, and Tables, select the data that the policy covers.
*is a wildcard. For example,*in Catalogs covers all catalogs, and the scopeiceberg.*.*covers all schemas and tables in theicebergcatalog.Under Limit the scope, select Match everything in scope, or select Match using expression and enter a matching expression. Click Next.
Add at least one privilege, column mask, or row filter:
To add privileges, select ALLOW or DENY in Grant, and select the privileges in Privileges. To add more, click Add privilege.
To add column masks and row filters, see Row filters and column masks.
Click Create policy.
A DENY policy blocks access even when the role holds the privilege through another grant. An ALLOW policy grants the privileges that you add to it on the data that it selects, so the role doesn’t need a separate grant.
A row filter or column mask doesn’t grant access. A policy that has only a row filter or column mask grants no privileges.
Matching expressions#
A matching expression is a Boolean expression that determines whether a policy applies to an entity. To cover all data in the policy’s scope instead, select Match everything in scope.
You can use parentheses to build complex expressions. The following example
matches an entity if its tags include sales_department, or include both
marketing_department and sales_liaison:
HAS_TAG(sales_department) OR (HAS_TAG(marketing_department) AND HAS_TAG(sales_liaison))
A policy that matches by tag has no effect on data until you apply the tag to that data. If an expression has a syntax error, the UI shows an error and you can’t continue to the next step.
Base expressions#
Base expressions evaluate one piece of data, such as the tags or the name of an entity, and don’t depend on other expressions.
Expression |
Description |
|---|---|
|
Booleans are valid expressions. |
|
Tests whether the tag is applied to an entity. You can apply tags to catalogs, schemas, tables, views, materialized views, and columns. To create and apply tags, see Tags. |
|
Tests whether a tag nested under the parent tag, such as |
|
Tests whether the catalog name matches the pattern. The policy’s scope must be one or more catalogs, or all catalogs. See Name patterns. |
|
Tests whether the schema name matches the pattern. The policy’s scope must be one or more catalogs or schemas, or all catalogs. See Name patterns. |
|
Tests whether the table name matches the pattern. The policy’s scope must be at or above the level of a table, or all catalogs. See Name patterns. |
Compound expressions#
Compound expressions combine base expressions. You can replace expression
with any base expression.
Expression |
Description |
Example |
|---|---|---|
|
True if the expression is false. |
|
|
True if both expressions are true. |
|
|
True if either expression is true. |
|
Use parentheses for clarity and to avoid mistakes with precedence. For example,
the following two expressions are equivalent, because AND has a higher
precedence than OR:
HAS_TAG(pii.email) OR HAS_TAG(pii.phone) AND HAS_TAG(pii.address)
HAS_TAG(pii.email) OR (HAS_TAG(pii.phone) AND HAS_TAG(pii.address))
Name patterns#
The catalog_name_matches, schema_name_matches, and table_name_matches
expressions match the name of an entity against a pattern, where * is a
wildcard:
catalog_name_matches('foo*')matches catalogs whose name starts with or equalsfoo.schema_name_matches('*foo')matches schemas whose name ends with or equalsfoo.table_name_matches('foo*')matches tables whose name starts with or equalsfoo.
A pattern can contain only one *.
When Starburst access control checks whether a catalog or schema is visible, an
ALLOW policy with a name pattern below that level makes the catalog or
schema visible, unless a DENY on the same privilege applies. For example, a
policy on all catalogs with table_name_matches('foo*') that allows Select
makes every catalog visible in SHOW CATALOGS, even catalogs with no tables
that match foo*. SHOW SCHEMAS works the same way. This applies only to
ALLOW. DENY, row filters, and column masks don’t affect visibility.
View, edit, or delete a policy#
To view a policy’s scope, matching expression, privileges, column masks, and row filters, click its name on the Policies tab of the role.
On the Policies tab of the role, open the policy’s menu to edit or delete the policy. When you edit a policy, click Update policy in the last step to save your changes. You can’t delete a role while it has policies.