Authorization

Basic concepts

Authorization in YDB is based on the concepts of:

• Access object
• Access subject
• Access right
• Access control list
• Owner
• User
• Group

Regardless of the authentication method, authorization is always performed on the server side of YDB based on the stored information about access objects and rights. Access rights determine the set of operations available to perform.

Authorization is performed for each user action: the rights are not cached, as they can be revoked or granted at any time.

User

To create, alter, and delete users in YDB, the following commands are available:

• CREATE USER
• ALTER USER
• DROP USER

YDB allows working with users from different directories and systems, and they differ by SID using a suffix.

The suffix @<subsystem> identifies the "user source" or "auth domain", within which the uniqueness of all login is guaranteed. For example, in the case of LDAP authentication, user names will be user1@ldap and user2@ldap.
If a login without a suffix is specified, it implies users directly created in the YDB cluster.

Group

Any user can be included in or excluded from a certain access group. Once a user is included in a group, they receive all the rights to database objects that were provided to the access group.
With access groups in YDB, business roles for user applications can be implemented by pre-configuring the required access rights to the necessary objects.

To create, alter, and delete groups, the following types of YQL queries are available:

• CREATE GROUP
• ALTER GROUP
• DROP GROUP

Right

Rights in YDB are tied not to the subject, but to the access object.

Each access object has a list of permissions — ACL (Access Control List) — it stores all the rights provided to access subjects (users and groups) for the object.

By default, rights are inherited from parents to descendants in the access objects tree.

The following types of YQL queries are used for managing rights:

• GRANT.
• REVOKE.

The following CLI commands are used for managing rights:

• chown
• grant
• revoke
• set
• clear
• clear-inheritance
• set-inheritance

The following CLI commands are used to view the ACL of an access object:

• describe
• list

Object Owner

Each access object has an owner. By default, it becomes the access subject who created the access object.

An object owner exists for the entire cluster and each database.

The owner can be changed using the CLI command chown.

The owner of an object can be viewed using the CLI command describe.

Access level lists

In addition to access control lists that control access to specific scheme objects, YDB uses access level lists to define hierarchical access levels for cluster-wide operations.

For operations where both access control lists and access level lists are checked, both checks are applied together: an action is allowed only if both checks allow it, and denied if either check fails. For other operations, only the corresponding check mechanism is used.

Hierarchy of access levels

Access level lists form a hierarchy (used by the Embedded UI, viewer, and many other cluster-wide actions; ordered from lower to higher privileges):

• database_allowed_sids (Database) - access to operations within a specific database scope
• viewer_allowed_sids (Viewer) - read-only access to cluster-wide state
• monitoring_allowed_sids (Monitoring) - access to operational actions in Embedded UI
• administration_allowed_sids (Administration) - administrative actions on the cluster and databases

Higher levels automatically include all lower level privileges, so a subject only needs to appear in one list. For example, presence in administration_allowed_sids automatically grants monitoring, viewer, and database privileges.
See Access level descriptions for details.

Additionally, there are two separate access level lists for specific operations:

• bootstrap_allowed_sids — allows cluster bootstrap operations
• register_dynamic_node_allowed_sids — allows node registration in the cluster

Access level descriptions

Access level lists are configured in the security configuration and determine privileges for:

• Database (presence in database_allowed_sids) — access only within a specific database scope. Subjects can open Embedded UI and work with that database data, but cannot run cluster-wide requests (for example, listing cluster nodes). Requests without a specified database are forbidden.
• Viewer (presence in viewer_allowed_sids) — read-only access to cluster-wide state: subjects can open Embedded UI pages and diagnostics, but cannot run actions that change system state.
• Monitoring (presence in monitoring_allowed_sids) — access to operational actions in Embedded UI, including actions that can change system state. For example, backup, database restore, or executing YQL statements from Embedded UI.
• Administration (presence in administration_allowed_sids) — Full administrative access to the cluster and its databases. Also used for config changes, scheme operations requiring admin privileges, and other administrative checks.
• Register node (presence in register_dynamic_node_allowed_sids) — a separate (non-hierarchical) level for dynamic node registration in the cluster. It does not automatically grant database/viewer/monitoring/administration privileges. For technical reasons, if this list is configured (non-empty), it must include root@builtin.
• Bootstrap (presence in bootstrap_allowed_sids) — a separate (non-hierarchical) level only for cluster bootstrap operations. It is used in an uninitialized state, when the authentication subsystem is not yet functional. Bootstrap is allowed if the subject is in bootstrap_allowed_sids or administration_allowed_sids; bootstrap by itself does not grant full administrative privileges.