Authorization

Basic concepts

Authorization in YDB is based on the following concepts:

Regardless of the authentication method, authorization is always performed on the server side of YDB based on the information about objects and access rights stored there. Access rights define the set of operations that can be performed.

Authorization is performed for every user action: their rights are not cached, as they may be revoked or granted at any time.

User

Users in YDB can be created from different sources:

  • Local users in YDB databases.
  • External users from third-party directory access services.

To create, modify, and delete local users, YDB provides the following commands:

Note

The scope of the commands CREATE USER, ALTER USER, and DROP USER does not extend to external user directories. Keep this in mind if users with third-party authentication (e.g., LDAP) are connecting to YDB. For example, the CREATE USER command does not create a user in the LDAP directory. Learn more about YDB's interaction with the LDAP directory.

Note

A user root with maximum rights is distinguished separately. It is created during the initial cluster deployment, during which a password must be set immediately. Further use of this account is not recommended; you should create users with limited rights.

For more information about initial deployment:

SID

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

The suffix @<auth-domain> identifies the “user source”, within which the uniqueness of all user logins or identifiers is guaranteed. For example, in the case of LDAP authentication, user SIDs will be user1@ldap and user2@ldap.

Local users have an empty auth-domain. If a user SID does not contain a suffix, it refers to a local user created and existing directly in the YDB cluster.

Group

Any user can be added to or removed from an access group. As soon as a user is added to a group, they receive all rights to database objects that were granted to the access group.
Using access groups, YDB allows you to implement business roles for user applications by pre-configuring the required access rights to the necessary objects.

Note

An access group can be empty, meaning it contains no users.

Access groups can be nested.

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

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

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

By default, rights are inherited from parents to descendants along the access object tree.

The following types of YQL queries are used to manage rights:

The following CLI commands are used to manage rights:

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

Object owner

Each access object has an owner. By default, the owner is the access subject that created the access object.

Note

For the owner, access control lists are not checked for the given access object.

The owner has the full set of rights on the object.

The cluster as a whole and each database also have an object owner.

You can change the owner using the CLI command chown.

You can view the object owner using the CLI command describe.

Access level lists

In addition to access control lists that manage access to specific schema 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 mechanisms are applied together: the action is available only if both checks allow it, and unavailable if at least one check fails. For other operations, only the corresponding check mechanism is applied.

Access level hierarchy

Access level lists form a hierarchy used in YDB UI, viewer, and many other cluster-wide actions (ordered from least to most privileges):

  • database_allowed_sids (Database) - access to operations in the context of a specific database.
  • viewer_allowed_sids (Viewer) - access to viewing cluster-wide state.
  • monitoring_allowed_sids (Monitoring) - access to operational actions in YDB UI.
  • administration_allowed_sids (Administration) - administrative actions on the cluster and databases.

A higher level automatically includes all lower ones, so a subject only needs to be present in one list. For example, being in administration_allowed_sids automatically grants privileges monitoring, viewer, and database.
Details on each level are in the section Access level description.

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

  • bootstrap_allowed_sids — allows cluster initialization operations.
  • register_dynamic_node_allowed_sids — allows node registration in the cluster.

Description of access levels

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

  • Database (included in database_allowed_sids) — access only in the context of a specific database. You can open YDB UI and work with the data of this database, but you cannot run cluster-wide queries (for example, view the list of cluster nodes). Queries without specifying a database are prohibited.
  • Viewer (included in viewer_allowed_sids) — read-only access to the cluster-wide state: you can view YDB UI pages and diagnostic information, but you cannot run actions that change the system state.
  • Monitoring (included in monitoring_allowed_sids) — access to operational actions in YDB UI, including actions that can change the system state. For example, starting a backup, restoring a database, or running YQL queries through YDB UI.
  • Administration (included in administration_allowed_sids) — grants the right to perform administrative actions on databases or the cluster. Full administrative access to the cluster and its databases. Also used for changing configuration, schema operations that require administrative rights, and other administrative checks.
  • Register node (included in register_dynamic_node_allowed_sids) — a separate (non-hierarchical) level for registering dynamic nodes in the cluster. It does not automatically grant database/viewer/monitoring/administration rights. For technical reasons, if the list is specified (not empty), it must include root@builtin.
  • Bootstrap (included in bootstrap_allowed_sids) — a separate (non-hierarchical) level only for cluster initialization operations. Used in an uninitialized state when the authentication subsystem is not yet functioning. Initialization is allowed if the subject is in bootstrap_allowed_sids or administration_allowed_sids, while bootstrap itself does not grant full administrative privileges.
Previous
Caching authentication results
Next
Initial security configuration