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 iceberg catalog.

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

  1. In the Control Plane UI, go to Access > Roles and privileges, and select the role to grant the policy to.

  2. Open the Policies tab and click Create Policy.

  3. Enter a name and, optionally, a description. The name can contain only lowercase letters, numbers, and underscores.

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

  5. In Catalogs, Schemas, and Tables, select the data that the policy covers. * is a wildcard. For example, * in Catalogs covers all catalogs, and the scope iceberg.*.* covers all schemas and tables in the iceberg catalog.

  6. Under Limit the scope, select Match everything in scope, or select Match using expression and enter a matching expression. Click Next.

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

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

true or false

Booleans are valid expressions.

HAS_TAG(tag)

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.

HAS_TAG(tag.*)

Tests whether a tag nested under the parent tag, such as pii.email under pii, is applied to an entity. It doesn’t match the parent tag. To match both, use HAS_TAG(pii) OR HAS_TAG(pii.*).

catalog_name_matches('pattern')

Tests whether the catalog name matches the pattern. The policy’s scope must be one or more catalogs, or all catalogs. See Name patterns.

schema_name_matches('pattern')

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.

table_name_matches('pattern')

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

NOT expression

True if the expression is false. NOT has a higher precedence than AND and OR.

NOT HAS_TAG(pii)

expression AND expression

True if both expressions are true. AND has a higher precedence than OR.

HAS_TAG(pii) AND table_name_matches('foo*')

expression OR expression

True if either expression is true.

HAS_TAG(pii) OR table_name_matches('foo*')

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 equals foo.

  • schema_name_matches('*foo') matches schemas whose name ends with or equals foo.

  • table_name_matches('foo*') matches tables whose name starts with or equals foo.

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.