markhoerth commented on code in PR #12247:
URL: https://github.com/apache/gravitino/pull/12247#discussion_r3672430944
##########
docs/security/access-control.md:
##########
@@ -7,1399 +7,585 @@ license: "This software is licensed under the Apache
License version 2."
## Overview
-Apache Gravitino provides unified access control across multiple data sources,
enabling you to manage permissions from a single interface regardless of
whether your data resides in databases, message queues, or object storage
systems.
+Apache Gravitino federates the catalogs of many systems under a single
metalake, so permissions are
+defined once there rather than separately in each system. When authorization
is enabled, the server
+checks every request before the operation runs and rejects it if the caller is
not entitled to it.
-### The Challenge
+Two things decide the answer:
-Managing access control across heterogeneous data sources presents significant
challenges:
-- Each data source has its own access control system with unique permissions
models
-- Querying multiple data sources simultaneously requires managing multiple
authorization systems
-- Data governance practitioners must ensure compliance across diverse systems
+- **Ownership** comes with creation. Whoever creates an object owns it, and
owning it carries the
+ right to alter it, drop it, and hand it to someone else. Ownership reaches
down, so owning a
+ catalog means administrative control over the schemas and tables inside it.
+- **Privileges** are named permissions, each authorizing one kind of
operation: `SELECT_TABLE` reads
+ a table, `CREATE_SCHEMA` creates a schema in a catalog. A privilege is never
given to a person
+ directly. Privileges are collected into a role, and the role is granted to
users and to groups.
-### The Solution
+Three rules govern how those apply:
-Gravitino addresses these challenges by implementing a universal privilege
model that:
-- **Unifies access control**: Manage all data source permissions through a
single interface
-- **Supports multiple engines**: Works seamlessly with Spark, Trino, Flink,
and Python clients
-- **Simplifies governance**: Enforce consistent access policies across all
data sources
-- **Reduces complexity**: Eliminate the need to manage individual access
control systems
+- **Grants reach downward.** A grant covers everything beneath the object it
is made on, both what
+ exists now and what is created later. `SELECT_TABLE` on a schema covers
every table in it.
+- **Nothing is permitted unless granted.** A user added to a metalake and
given nothing can see the
+ metalake and nothing else.
+- **An explicit deny overrides everything.** Each privilege in a role carries
an `ALLOW` or a `DENY`
+ condition, and a `DENY` beats an `ALLOW` held in any other role and at any
other level of the
+ hierarchy. A denial cannot be undone by granting something elsewhere, which
makes `DENY` the way to
+ carve one object out of a broad grant.
-### Gravitino Privilege Model
+## Quick Start
-Gravitino provides a unified authorization model that works across all
connected data sources while respecting each source's unique characteristics.
-
-**Architecture:**
-
-When users or data engines access data through Gravitino, the privilege model:
-- Evaluates permissions at the Gravitino layer first
-- Translates Gravitino privileges to data source-specific permissions when
needed
-- Maintains consistency across different data sources while preventing
permission conflicts
-
-**Access Control Models:**
-
-Gravitino adopts two complementary access control models:
-
-- **Role-Based Access Control (RBAC)**: Access privileges are assigned to
roles, which are in turn assigned to users or groups
-- **Discretionary Access Control (DAC)**: Each metadata object has an owner
who can grant access to that object
-
-:::info
-
-Gravitino only supports authorization for securable objects, when Gravitino
supports to pass the privileges to underlying authorization plugin.
-Gravitino doesn't support metadata authentication. It means that Gravitino
won't check the privileges when Gravitino receives the requests.
-
-:::
-
-## Core Concepts
-
-### Authorization
-
-Gravitino provides two types of authorization mechanisms:
-
-#### Built-in Authorization
-
-Gravitino includes built-in metadata authorization that you can enable with
the following configuration:
+Authorization is off by default. Turn it on in
`${GRAVITINO_HOME}/conf/gravitino.conf`, name at least
+one service administrator, and restart the server:
```properties
gravitino.authorization.enable = true
+gravitino.authorization.serviceAdmins = {admin_user}
```
-To disable built-in authorization and pass through all requests without
authorization checks:
-
-```properties
-gravitino.authorization.impl =
org.apache.gravitino.server.authorization.PassThroughAuthorizer
-```
-
-:::info
-**Prerequisites for Built-in Authorization:**
-- Authorization must be enabled
-- Users must be granted appropriate privileges
-- See [API Required Conditions](#api-required-conditions) for privilege
requirements for each REST API
-:::
-
-#### Authorization Pushdown
-
-In addition to built-in authorization, Gravitino can push down authorization
to underlying data sources. This allows integration with:
-- Data source native access control (e.g., MySQL privileges)
-- Enterprise authorization systems (e.g., Apache Ranger)
-
-The pushdown mechanism translates Gravitino's authorization model to data
source-specific permissions while maintaining consistency.
-
-For more information, see [Authorization Pushdown](authorization-pushdown.md).
-
-### Authentication
-
-Gravitino uses a combined approach for access control:
-
-- **Ownership**: Controls management operations (create, drop, alter) on
securable objects
-- **Roles**: Controls access to securable objects (read, write, use)
-
-When a user performs an operation on a resource, Gravitino evaluates both
ownership and role-based permissions. If a user has multiple roles, Gravitino
evaluates all of them to determine the final permission set.
-
-### Role
-
-A role is a named collection of privileges on securable objects. Roles
simplify access management by allowing you to:
-
-- **Group privileges**: Bundle related permissions together
-- **Assign to multiple users**: Grant the same set of permissions to multiple
users or groups
-- **Quick onboarding**: New users can start working immediately by receiving
pre-configured roles
-
-**Ownership of Roles:**
-- The creator of a role is automatically the owner
-- Owners have full control over the role, including the ability to drop it
-- Only the owner can modify the role's permissions
-
-### Privilege
-
-Privilege is a specific operation method for securable object, if you need to
control fine-grained privileges on a securable object in the system,
-then you need to design many different Privileges, however, too many
Privileges will cause too complicated settings in the authorization.
-
-If you only need to carry out coarse-grained privilege control on the
securable object in the system, then you only need to design a small number of
Privileges,
-but it will result in too weak control ability when the authentication.
Therefore, the design of Privilege is an important trade-off in the access
control system.
-We know that Privilege is generally divided into two types, one is the
management category of Privilege, such as the `CREATE`, `DELETE` resource
privilege,
-and the other is the operation category of Privilege, such as the `READ` and
`WRITE` resource privilege.
-
-In most organizations, the number of data managers is much smaller than the
number of data users.
-Because it is the data users who need fine-grained privilege control,
-we must provide more Privileges related to usage and more tightly gatekeeper
the administrative Privileges.
-To enforce this, we’ll introduce the concept of Ownership as a complete
replacement for the administrative category of Privilege.
-
-### Ownership
+Service administrators are the only users who can create metalakes, and
everything after that is done
+through the API. The [Walkthrough](#walkthrough) runs a full sequence end to
end, from an empty server
+to a user with read access to one schema. [Server
Configuration](#server-configuration) covers the
+remaining settings, including how a caller's identity reaches the server.
-Every securable object in Gravitino has an owner - the user with
administrative control over that object.
+## Authorization Model
-**Key Characteristics:**
+### Principals and Objects
-- **Automatic assignment**: The creator of an object automatically becomes its
owner
-- **Administrative privileges**: Owners have implicit management privileges
(e.g., drop, alter)
-- **Exclusive control**: Only the owner can fully manage the object
-- **Group ownership**: Ownership can be assigned to a group, granting all
members of that group owner privileges
+#### Users and Groups
-**Supported Objects:**
+A user must be added to a metalake before it can do anything there. A group is
a set of users, and a
+role granted to a group applies to every member, which is how access is
usually managed for a team.
-The following metadata objects support ownership:
+Both carry an optional `externalId` correlating them with an external identity
provider. Users also
+have an `enabled` flag, which suspends access without removing the user and
defaults to `true` when
+the user is created with an `externalId`.
-| Metadata Object Type |
-|----------------------|
-| Metalake |
-| Catalog |
-| Schema |
-| Table |
-| View |
-| Topic |
-| Fileset |
-| Role |
-| Model |
-| Function |
-| Tag |
-| JobTemplate |
-| Job |
+#### Service Administrators
-### User
+A service administrator is an ordinary user whose name appears in
+`gravitino.authorization.serviceAdmins`. They are added to metalakes, granted
roles, and made owners
+like anyone else. The list adds exactly one ability, creating a metalake, and
being server
+configuration rather than a role it cannot be granted or revoked through the
API. The check reads the
+list alone, which is what lets the first metalake be created before any
membership exists.
-A user represents an individual identity in Gravitino. Users can be:
-- Granted one or more roles
-- Given different operating privileges based on their assigned roles
-- Made owners of securable objects
-- Correlated with an external identity provider through an optional
`externalId`
-- Enabled or disabled through the optional `enabled` flag (`true` by default
when creating with `externalId`)
+#### Objects
-### Group
+Everything Gravitino manages is an object with a type and a name. The name is
the dotted path to it
+below the metalake, so a table is `{catalog}.{schema}.{table}`, and requests
identify an object by
+both type and name, since the same name can exist at more than one type.
-A group is a collection of users that simplifies permission management by
allowing you to:
-- Grant permissions to multiple users at once
-- Manage access control for teams or departments
-- Assign roles that all group members will inherit
-- Correlated with an external identity provider through an optional
`externalId`
+Access to an object is controlled by privileges, granted through roles, and by
ownership. Ownership
+behaves like a privilege that arrives with the object rather than one you
grant, and it carries the
+administrative rights, altering, dropping, and transferring, that no privilege
name covers.
-All users in a group inherit the roles and privileges granted to that group.
-
-### Metadata Objects
-
-Metadata objects are entities managed by Gravitino, such as catalogs, schemas,
tables, filesets, topics, models, functions, roles, and metalakes.
-
-**Naming Convention:**
-- Each metadata object has a **type** and a **name**
-- Names use dot notation to represent hierarchy
-
-**Examples:**
-- `METALAKE`: "metalake1"
-- `CATALOG`: "catalog1" (under a metalake)
-- `SCHEMA`: "catalog1.schema1" (under a catalog)
-- `TABLE`: "catalog1.schema1.table1" (under a schema)
-
-### Securable Objects
-
-A securable object is any metadata object to which access can be granted. The
default policy is **deny-by-default**: unless explicitly granted, access is
denied.
-
-**Hierarchy:**
-
-Securable objects exist in a hierarchical container structure:
+Everything sits under a metalake, but only the data objects nest below a
catalog:
```
Metalake (top level)
-└── Catalog (represents a data source)
- └── Schema
- ├── Table
- ├── View
- ├── Topic
- ├── Fileset
- ├── Model
- └── Function
-```
-
-
-
-**Relationships:**
-
-The following diagrams illustrate the relationships between users, groups,
roles, and securable objects:
-
-
-
-
-## Role Types
-
-### Service Admin
-
-Service administrators are responsible for creating metalakes. This role is
typically assigned to system maintainers or operators who bootstrap the initial
metadata organization.
-
-**Privileges:**
-- Create metalakes
-
-**Ownership:**
-- When a service admin creates a metalake, they automatically become the owner
of that metalake
-- As the owner, they have full control over the metalake, including the
ability to drop it
-- Ownership can be transferred to another user if needed
-
-**Limitations:**
-- Cannot configure system-wide settings (handled through server configuration
files)
-- Cannot manage service-level permissions
-
-:::info
-Service admins automatically become the owner of metalakes they create.
However, ownership can be changed by setting a new owner for the metalake.
-:::
-
-### Custom Roles
-
-Create custom roles tailored to your business needs using the API or client
libraries. Custom roles allow you to:
-- Define specific permission sets
-- Align access control with your organization's structure
-- Implement least-privilege access policies
-
-## Privilege Types
-
-Gravitino provides a comprehensive set of privileges organized by the type of
operation and securable object. The following sections detail all available
privileges.
-
-### User Privileges
-
-| Name | Supports Securable Object | Operation |
-|--------------|---------------------------|---------------------|
-| MANAGE_USERS | Metalake | Add or remove users |
-
-### Group Privileges
-
-| Name | Supports Securable Object | Operation |
-|---------------|---------------------------|----------------------|
-| MANAGE_GROUPS | Metalake | Add or remove groups |
-
-### Role Privileges
-
-| Name | Supports Securable Object | Operation |
-|-------------|---------------------------|---------------|
-| CREATE_ROLE | Metalake | Create a role |
-
-### Permission Privileges
-
-| Name | Supports Securable Object | Operation
|
-|---------------|---------------------------|---------------------------------------------------------------------------------------------------------------|
-| MANAGE_GRANTS | Metalake, Catalog, Schema, Table, View, Topic, Fileset,
Model, Function | Grants the ability to manage privileges on securable objects.
When bound to a **Metalake**, also allows assigning and revoking roles for
users and groups across the entire metalake. When bound to a **Catalog, Schema,
Table, View, Topic, Fileset, Model, or Function**, privilege management is
scoped to that object and its descendants only. |
-
-### Catalog Privileges
-
-| Name | Supports Securable Object | Operation |
-|----------------|---------------------------|------------------|
-| CREATE_CATALOG | Metalake | Create a catalog |
-| USE_CATALOG | Metalake, Catalog | Use a catalog |
-
-:::info
-
-`USE_CATALOG` is needed for a user to interact with any object within the
catalog.
-
-For example, to select data from a table, users need to have the
`SELECT_TABLE` privilege on that table and
-`USE_CATALOG` privileges on its parent catalog as well as `USE_SCHEMA`
privileges on its parent schema.
-
-:::
-
-### Schema Privileges
-
-| Name | Supports Securable Object | Operation |
-|---------------|---------------------------|-----------------|
-| CREATE_SCHEMA | Metalake, Catalog | Create a schema |
-| USE_SCHEMA | Metalake, Catalog, Schema | Use a schema |
-
-:::info
-
-`USE_SCHEMA`is needed for a user to interact with any object within the
schema.
-
-For example, to select data from a table, users need to have the
`SELECT_TABLE` privilege on that table
-and `USE_SCHEMA` privileges on its parent schema.
-
-:::
-
-### Table Privileges
-
-| Name | Supports Securable Object | Operation
|
-|--------------|-----------------------------------|---------------------------------------------------------------------------|
-| CREATE_TABLE | Metalake, Catalog, Schema | Create a table
|
-| MODIFY_TABLE | Metalake, Catalog, Schema, Table | Select data from a data,
write data to a table or modify the table schema |
-| SELECT_TABLE | Metalake, Catalog, Schema, Table | Select data from a table
|
-
-DENY `MODIFY_TABLE` won't deny the `SELECT_TABLE` operation if the user has
the privilege to `ALLOW SELECT_TABLE` on the table.
-DENY `SELECT_TABLE` won't deny the `MODIFY_TABLE` operation if the user has
the privilege `ALLOW MODIFY_TABLE` on the table.
-
-### View Privileges
-
-| Name | Supports Securable Object | Operation |
-|-------------|---------------------------------|--------------------------|
-| CREATE_VIEW | Metalake, Catalog, Schema | Create a view |
-| SELECT_VIEW | Metalake, Catalog, Schema, View | Select data from a view |
-
-### Topic Privileges
-
-| Name | Supports Securable Object | Operation
|
-|---------------|----------------------------------|-------------------------------------------------------|
-| CREATE_TOPIC | Metalake, Catalog, Schema | Create a topic
|
-| PRODUCE_TOPIC | Metalake, Catalog, Schema, Topic | Consume and produce a
topic (including alter a topic) |
-| CONSUME_TOPIC | Metalake, Catalog, Schema, Topic | Consume a topic
|
-
-DENY `PRODUCE_TOPIC` won't deny the `COMSUME_TOPIC` operation if the user has
the privilege to `ALLOW CONSUME_TOPIC` on the topic.
-DENY `CONSUME_TOPIC` won‘t deny the `PRODUCE_TOPIC` operation if the user has
the privilege `ALLOW PRODUCE_TOPIC` on the topic.
-
-### Fileset Privileges
-
-| Name | Supports Securable Object | Operation
|
-|----------------|------------------------------------|------------------------------------------------------|
-| CREATE_FILESET | Metalake, Catalog, Schema | Create a fileset
|
-| WRITE_FILESET | Metalake, Catalog, Schema, Fileset | Read and write a
fileset (including alter a fileset) |
-| READ_FILESET | Metalake, Catalog, Schema, Fileset | Read a fileset
|
-
-DENY `READ_FILESET` won't deny the `WRITE_FILESET` operation if the user has
the privilege to `ALLOW WRITE_FILESET` on the fileset.
-DENY `WRITE_FILESET` won‘t deny the `READ_FILESET` operation if the user has
the privilege `ALLOW READ_FILESET` on the fileset.
-
-### Model Privileges
-
-:::caution Deprecated Privileges
-The privileges `CREATE_MODEL` and `CREATE_MODEL_VERSION` are deprecated and
will be removed in a future release. Please use `REGISTER_MODEL` and
`LINK_MODEL_VERSION` instead. The deprecated privileges still work for backward
compatibility.
-:::
-
-| Name | Supports Securable Object | Operation
|
-|----------------------|----------------------------------|------------------------------------------------------------------------------------|
-| REGISTER_MODEL | Metalake, Catalog, Schema | Register a model
|
-| LINK_MODEL_VERSION | Metalake, Catalog, Schema, Model | Link a model
version |
-| USE_MODEL | Metalake, Catalog, Schema, Model | View the metadata
of the model and download all the model versions |
-| CREATE_MODEL | Metalake, Catalog, Schema | Register a model,
this is deprecated. Please use `REGISTER_MODEL` instead. |
-| CREATE_MODEL_VERSION | Metalake, Catalog, Schema, Model | Link a model
version, this is deprecated. Please use `LINK_MODEL_VERSION` instead. |
-
-### Function Privileges
-
-| Name | Supports Securable Object | Operation
|
-|-------------------|-------------------------------------|---------------------------------------------------------------------------------------|
-| REGISTER_FUNCTION | Metalake, Catalog, Schema | Register a
function |
-| EXECUTE_FUNCTION | Metalake, Catalog, Schema, Function | View the metadata
of the function and execute the function |
-| MODIFY_FUNCTION | Metalake, Catalog, Schema, Function | Alter or drop the
function |
-
-### Tag Privileges
-
-| Name | Supports Securable Object | Operation
|
-|------------|---------------------------|---------------------------------------|
-| CREATE_TAG | Metalake | Create a tag
|
-| APPLY_TAG | Metalake, Tag | Associate tags with metadata
objects. |
-
-### Policy Privileges
-
-| Name | Supports Securable Object | Operation
|
-|---------------|---------------------------|-------------------------------------------|
-| CREATE_POLICY | Metalake | Create a policy
|
-| APPLY_POLICY | Metalake, Policy | Associate policies with metadata
objects. |
-
-### Job Template Privileges
-
-| Name | Supports Securable Object | Operation
|
-|-----------------------|---------------------------|-----------------------------------------|
-| REGISTER_JOB_TEMPLATE | Metalake | Register a job template
|
-| USE_JOB_TEMPLATE | Metalake, JobTemplate | Use a job template when
running the job |
-
-### Job Privileges
-
-| Name | Supports Securable Object | Operation |
-|---------|---------------------------|-----------|
-| RUN_JOB | Metalake | Run a job |
-
-
-## Privilege Inheritance
-
-Gravitino implements hierarchical privilege inheritance, where privileges
granted at higher levels automatically apply to all objects at lower levels.
-
-**How It Works:**
-- Granting a privilege on a **metalake** applies it to all catalogs, schemas,
and objects within that metalake
-- Granting a privilege on a **catalog** applies it to all schemas and objects
within that catalog
-- Granting a privilege on a **schema** applies it to all tables, topics, and
filesets within that schema
-
-**Example:**
-
-If you grant a user `SELECT_TABLE` privilege on a catalog:
-- The user can read **all tables** in that catalog
-- This includes tables in all schemas within the catalog
-- The privilege applies to both existing and future tables
-
-This inheritance model simplifies permission management for large datasets
while maintaining fine-grained control when needed.
-
-## Privilege Conditions
-
-Each privilege can have one of two conditions:
-
-- **`ALLOW`**: Grants permission to perform the operation
-- **`DENY`**: Explicitly denies permission to perform the operation
-
-### Priority Rules
-
-**`DENY` takes precedence over `ALLOW`:**
-- If a user has both `ALLOW` and `DENY` for the same privilege, the operation
is denied
-- This applies regardless of whether the conditions come from different roles
-
-### Inheritance and Conditions
-
-Privilege conditions do **not override** parent object conditions. Both parent
and child conditions are evaluated:
-
-**Example 1: Parent ALLOW, Child DENY**
-- Metalake: `USE_CATALOG` → ALLOW
-- Catalog: `USE_CATALOG` → DENY
-- **Result**: User **cannot** use the catalog (DENY wins)
-
-**Example 2: Parent DENY, Child ALLOW**
-- Metalake: `USE_CATALOG` → DENY
-- Catalog: `USE_CATALOG` → ALLOW
-- **Result**: User **cannot** use the catalog (DENY wins)
-
-
-
-This model ensures that denials cannot be circumvented by grants at lower
levels in the hierarchy.
-
-## Configuration
-
-To enable access control in Gravitino, configure the following settings in
your server configuration file:
-
-| Configuration Item | Description
| Default Value |
Required | Since Version |
-|---------------------------------------------------------|---------------------------------------------------------------------------|---------------|---------------------------------------------|---------------|
-| `gravitino.authorization.enable` | Enable or disable
authorization in Gravitino | `false` | No
| 0.5.0 |
-| `gravitino.authorization.serviceAdmins` | Comma-separated
list of service administrator usernames | (none) | Yes
(when authorization is enabled) | 0.5.0 |
-| `gravitino.authorization.jcasbin.cacheExpirationSecs` | The expiration
time in seconds for authorization cache entries | `3600` | No
| 1.1.1 |
-| `gravitino.authorization.jcasbin.roleCacheSize` | The maximum size
of the role cache for authorization | `10000` | No
| 1.1.1 |
-| `gravitino.authorization.jcasbin.ownerCacheSize` | The maximum size
of the owner cache for authorization | `100000` | No
| 1.1.1 |
-| `gravitino.authorization.jcasbin.metadataIdCacheSize` | The maximum size
of the metadata ID cache for authorization | `100000` | No
| 1.3.0 |
-| `gravitino.authorization.jcasbin.changePollIntervalSecs` | The interval in
seconds for polling entity and owner changes | `3` | No
| 1.3.0 |
-
-### Authorization Cache
-
-Gravitino uses Caffeine caches to improve authorization performance by caching
role and owner information. The cache configuration options allow you to tune
the cache behavior:
-
-- **`cacheExpirationSecs`**: Controls how long cache entries remain valid.
After this time, entries are automatically evicted and reloaded from the
backend on the next access. Lower values provide more up-to-date authorization
decisions but may increase load on the backend.
-
-- **`roleCacheSize`**: Controls the maximum number of role entries that can be
cached. When the cache reaches this size, the least recently used entries are
evicted.
-
-- **`ownerCacheSize`**: Controls the maximum number of owner relationship
entries that can be cached. This cache maps metadata object IDs to their owner
IDs.
-
-- **`metadataIdCacheSize`**: Controls the maximum number of metadata
name-to-ID mapping entries that can be cached. This cache maps metadata object
names to internal metadata IDs used by JCasbin authorization checks.
-
-- **`changePollIntervalSecs`**: Controls how often a Gravitino server polls
persisted entity and owner changes to invalidate local JCasbin authorization
caches in multi-node deployments.
-
-:::info
-When role privileges or ownership are changed through the Gravitino API, the
corresponding cache entries are automatically invalidated to ensure
authorization decisions reflect the latest state.
-:::
-
-### Important Notes
-
-:::info
-**Authorization Requirements:**
-1. **Add users first**: Users must be added to a metalake before creating
metadata objects
-2. **Default user**: If no user is specified, operations use the `anonymous`
user
-3. **Automatic membership**: When creating a metalake with authorization
enabled, the creator is automatically added to that metalake
-:::
-
-**Example Configuration:**
+├── Catalog (represents a data source)
+│ └── Schema
+│ ├── Table
+│ ├── View
+│ ├── Topic
+│ ├── Fileset
+│ ├── Model
+│ └── Function
+├── Tag
+├── Policy
+├── Job Template
+├── Role
+└── Job
+```
+
+Three things about that tree are worth noting:
+
+- Roles and jobs are controlled by ownership alone, since no privilege binds
to them, though
+ `CREATE_ROLE` and `RUN_JOB` on the metalake gate creating them.
+- Columns do not appear at all. They are reached through their table and carry
no controls of their
+ own, so there is no column-level grant in this model.
+- Users and groups are not objects. They are the principals that privileges
and ownership are
+ assigned to.
+
+### Grants
+
+#### Privileges
+
+A privilege authorizes a specific operation on an object, for example
`SELECT_TABLE` or
+`CREATE_SCHEMA`. Privileges are added to roles, and roles are granted to users
and groups. Privileges
+are never granted directly to a user.
+
+#### Roles
+
+A role is a named set of privileges, granted to users and groups. Privileges
are never granted
+directly to a user.
+
+A role holds objects, and for each one a list of privileges, each carrying an
`ALLOW` or `DENY`
+condition. A privilege binds only to object types it supports, so
`CREATE_TABLE` binds to a metalake,
+catalog, or schema, never to a table. Whoever creates a role owns it, and can
alter or delete it.
+
+#### Ownership
+
+Ownership can be held by a group as well as a user, in which case every member
of that group holds
+it, and it can be transferred at any time. It applies to metalakes, catalogs,
schemas, tables, views,
+topics, filesets, models, functions, roles, tags, policies, job templates, and
jobs.
+
+### Resolution
+
+#### Evaluating a Request
+
+Every authorized endpoint declares the conditions under which a caller may
invoke it, and the check
+passes if any one of them holds. Loading a table, for example, succeeds when:
+
+- The caller owns the metalake or the catalog.
+- The caller owns the schema and holds `USE_CATALOG`.
+- The caller holds both `USE_CATALOG` and `USE_SCHEMA`, and additionally owns
the table or holds
+ `SELECT_TABLE` or `MODIFY_TABLE`.
+
+Note the third case. Granting `SELECT_TABLE` on a schema covers every table in
that schema, but on
+its own it authorizes nothing, because the traversal privileges are still
missing.
+
+A failed check returns `403 Forbidden`. Some read paths return `404 Not Found`
instead, so that a
+caller cannot infer the existence of an object they are not entitled to see.
List operations do not
+fail; they return only the entries the caller is entitled to see.
+
+#### Allow and Deny
+
+`DENY` always wins. It beats an `ALLOW` in the same role, an `ALLOW` from any
other role the user
+holds, and an `ALLOW` at any other level of the hierarchy, in either
direction: a `DENY` on a catalog
+survives an `ALLOW` on its metalake, and a `DENY` on a metalake survives an
`ALLOW` on its catalog.
+So a denial cannot be circumvented by granting something elsewhere.
+
+Sibling privileges are independent of each other. `DENY MODIFY_TABLE` leaves
`ALLOW SELECT_TABLE`
+intact, and the same holds for `PRODUCE_TOPIC` and `CONSUME_TOPIC`, and for
`READ_FILESET` and
+`WRITE_FILESET`. To withhold both read and write, deny both.
+
+## Privileges and What They Allow
+
+**Grantable On** lists the object types a privilege can be bound to, and the
object it is bound to
+sets the scope of the grant. Binding a privilege to a type not listed for it
is rejected.
+
+### Data Object Privileges
+
+| Privilege | Grantable On | What It Allows
|
+|----------------------|-------------------------------------|--------------------------------------------------------------------|
+| `CREATE_CATALOG` | Metalake | Create catalogs
|
+| `USE_CATALOG` | Metalake, Catalog | Use any catalog
in scope, and reach the objects inside it |
+| `CREATE_SCHEMA` | Metalake, Catalog, Schema | Create schemas
or nested schemas in any catalog in scope |
Review Comment:
```suggestion
| `CREATE_SCHEMA` | Metalake, Catalog, Schema | Create
schemas or nested schemas in scope |
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
