---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://ydb.tech/docs/en/security/authorization.md?version=main
  - https://ydb.tech/docs/ru/security/authorization.md?version=main
sourcePath: en/core/security/authorization.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/en/llms.txt

# Authorization

## Basic concepts

Authorization in YDB is based on the concepts of:

* [Access object](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-object)
* [Access subject](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-subject)
* [Access right](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-right)
* [Access control list](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-acl)
* [Owner](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-owner)
* [User](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-user)
* [Group](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-group)

Regardless of the [authentication](https://en.wikipedia.org/wiki/Authentication) method, [authorization](https://en.wikipedia.org/wiki/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 {#user}

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

* [CREATE USER](https://ydb.tech/docs/en/yql/reference/syntax/create-user.md?version=main)
* [ALTER USER](https://ydb.tech/docs/en/yql/reference/syntax/alter-user.md?version=main)
* [DROP USER](https://ydb.tech/docs/en/yql/reference/syntax/drop-user.md?version=main)

<!-- source: en/_includes/do-not-create-users-in-ldap.md -->
{% note info %}

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](https://ydb.tech/docs/en/security/authentication.md?version=main#ldap-auth-provider).

{% endnote %}
<!-- endsource: en/_includes/do-not-create-users-in-ldap.md -->

{% note info %}

There is a separate user `root` with maximum rights. It is created during the initial deployment of the cluster, during which a password must be set immediately. It is not recommended to use this account long-term; instead, users with limited rights should be created.

More about initial deployment:

* [Ansible](https://ydb.tech/docs/en/devops/deployment-options/ansible/initial-deployment/index.md?version=main)
* [Kubernetes](https://ydb.tech/docs/en/devops/deployment-options/kubernetes/initial-deployment.md?version=main)
* [Manually](https://ydb.tech/docs/en/devops/deployment-options/manual/initial-deployment/index.md?version=main)

{% endnote %}

YDB allows working with [users](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-user) from different directories and systems, and they differ by [SID](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-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](https://ydb.tech/docs/en/security/authentication.md?version=main#ldap-auth-provider), 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 {#group}

Any [user](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-user) can be included in or excluded from a certain [access group](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-group). Once a user is included in a group, they receive all the rights to [database objects](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-object) 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.

{% note info %}

An access group can be empty when it does not include any users.

Access groups can be nested.

{% endnote %}

To create, alter, and delete [groups](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-group), the following types of YQL queries are available:

* [CREATE GROUP](https://ydb.tech/docs/en/yql/reference/syntax/create-group.md?version=main)
* [ALTER GROUP](https://ydb.tech/docs/en/yql/reference/syntax/alter-group.md?version=main)
* [DROP GROUP](https://ydb.tech/docs/en/yql/reference/syntax/drop-group.md?version=main)

## Right {#right}

[Rights](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-right) in YDB are tied not to the [subject](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-subject), but to the [access object](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-object).

Each access object has a list of permissions — [ACL](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-acl) (Access Control List) — it stores all the rights provided to [access subjects](https://ydb.tech/docs/en/concepts/glossary.md?version=main#subject) (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](https://ydb.tech/docs/en/yql/reference/syntax/grant.md?version=main).
* [REVOKE](https://ydb.tech/docs/en/yql/reference/syntax/revoke.md?version=main).

The following CLI commands are used for managing rights:

* [chown](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-permissions.md?version=main#chown)
* [grant](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-permissions.md?version=main#grant-revoke)
* [revoke](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-permissions.md?version=main#grant-revoke)
* [set](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-permissions.md?version=main#set)
* [clear](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-permissions.md?version=main#clear)
* [clear-inheritance](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-permissions.md?version=main#clear-inheritance)
* [set-inheritance](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-permissions.md?version=main#set-inheritance)

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

* [describe](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-describe.md?version=main)
* [list](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-permissions.md?version=main#list)

## Object Owner {#owner}

Each access object has an [owner](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-owner). By default, it becomes the [access subject](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-subject) who created the [access object](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-object).

{% note info %}

For the owner, [permission lists](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-control-list) on this [access object](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-object) are not checked.

They have a full set of rights on the object.

{% endnote %}

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

The owner can be changed using the CLI command [`chown`](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-permissions.md?version=main#chown).

The owner of an object can be viewed using the CLI command [`describe`](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-describe.md?version=main).

## Access level lists {#access-level-lists}

In addition to [access control lists](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-control-list) that control access to specific [scheme objects](https://ydb.tech/docs/en/concepts/glossary.md?version=main#scheme-object), YDB uses [access level lists](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-level-list) to define hierarchical access levels for cluster-wide operations.

For operations where both [access control lists](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-control-list) and [access level lists](https://ydb.tech/docs/en/concepts/glossary.md?version=main#access-level-list) 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](https://ydb.tech/docs/en/reference/embedded-ui/ydb-monitoring.md?version=main), 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](#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-descriptions}

Access level lists are configured in the [security configuration](https://ydb.tech/docs/en/reference/configuration/security_config.md?version=main#security-access-levels) 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](https://ydb.tech/docs/en/reference/embedded-ui/ydb-monitoring.md?version=main) 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.