Eng docs: authorization (#13428)

Co-authored-by: anton-bobkov <anton-bobkov@ydb.tech>
Co-authored-by: Ivan Blinkov <ivan@ydb.tech>

ydb/docs/en/core/_includes/do-not-create-users-in-ldap.md

@@ -0,0 +1,5 @@
+{% 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-short-name }}. For example, the `CREATE USER` command does not create a user in the LDAP directory. Learn more about [{{ ydb-short-name }}'s interaction with the LDAP directory](../security/authentication.md#ldap-auth-provider).
+
+{% endnote %}

ydb/docs/en/core/changelog-server.md

@@ -131,7 +131,7 @@ Release date: July 31, 2024.
 
 * The [Knn UDF](./yql/reference/udf/list/knn.md) function for precise nearest vector search has been implemented.
 * The gRPC Query service has been developed, enabling the execution of all types of queries (DML, DDL) and retrieval of unlimited amounts of data.
-* [Integration with the LDAP protocol](./concepts/auth.md) has been implemented, allowing the retrieval of a list of groups from external LDAP directories.
+* [Integration with the LDAP protocol](./security/authentication.md) has been implemented, allowing the retrieval of a list of groups from external LDAP directories.
 
 ### Embedded UI
 

ydb/docs/en/core/concepts/datamodel/_includes/dir.md

@@ -1,3 +1,4 @@
 # Directory
 
-For convenience, {{ ydb-short-name }} supports creating directories like in a filesystem, meaning the entire database consists of a directory tree, while tables and other entities are in the leaves of this tree (similar to files in the filesystem). A directory can host multiple subdirectories and tables. The names of the entities they contain are unique.
+For convenience, {{ ydb-short-name }} supports creating [directories](../../glossary.md#folder) similar to a filesystem, meaning the entire database consists of a directory tree, and [scheme objects](../../glossary.md#scheme-object), such as tables, are located in the leaves of this tree. A directory can host multiple subdirectories and several scheme objects. The names of scheme objects within a single directory are unique.
+

ydb/docs/en/core/concepts/federated_query/ydb.md

@@ -4,7 +4,7 @@
 
 To connect to an external {{ ydb-short-name }} database from another {{ ydb-short-name }} database acting as the federated query engine, the following steps need to be performed on the latter:
 
-1. Prepare authentication data to access the remote {{ ydb-short-name }} database. Currently, in federated queries to {{ ydb-short-name }}, the only available authentication method  is [login and password](../../concepts/auth.md#static-credentials) (other methods are not supported). The password to the external database is stored as a [secret](../datamodel/secrets.md):
+1. Prepare authentication data to access the remote {{ ydb-short-name }} database. Currently, in federated queries to {{ ydb-short-name }}, the only available authentication method  is [login and password](../../security/authentication.md#static-credentials) (other methods are not supported). The password to the external database is stored as a [secret](../datamodel/secrets.md):
 
     ```yql
     CREATE OBJECT ydb_datasource_user_password (TYPE SECRET) WITH (value = "<password>");
@@ -92,4 +92,4 @@ When working with tables located in the external {{ ydb-short-name }} database,
 |`Datetime`|`Datetime`|
 |`Timestamp`|`Timestamp`|
 |`Json`|`Json`|
-|`JsonDocument`|`Json`|
+|`JsonDocument`|`Json`|

ydb/docs/en/core/concepts/glossary.md

@@ -253,9 +253,52 @@ An **external table** is a piece of metadata that describes a particular dataset
 
 A **secret** is a sensitive piece of metadata that requires special handling. For example, secrets can be used in [external data source](#external-data-source) definitions and represent things like passwords and tokens.
 
+### Scheme object {#scheme-object}
+
+A database schema consists of **scheme objects**, which can be databases, [tables](#table) (including [external tables](#external-table)), [topics](#topic), [folders](#folder), and so on.
+
+For organizational convenience, scheme objects form a hierarchy using [folders](#folder).
+
 ### Folder {#folder}
 
-Like in filesystems, a **folder** or **directory** is a container for other entities. In the case of {{ ydb-short-name }}, these entities can be [tables](#table) (including [external tables](#external-table)), [topics](#topic), other folders, etc.
+As in file systems, a **folder** or **directory** is a container for [scheme objects](#scheme-object).
+
+Folders can contain subfolders, and this nesting can have arbitrary depth.
+
+### Access object {#access-object}
+
+An **access object** in the context of [authorization](../security/authorization.md) is an entity for which access rights and restrictions are configured. In {{ ydb-short-name }}, access objects are [scheme objects](#scheme-object).
+Each access object has an [owner](#access-owner) and an [access control list](#access-control-list).
+
+### Access subject {#access-subject}
+
+An **access subject** is an entity that can interact with [access objects](#access-object) or perform specific actions within the system. Access to these interactions and actions depends on configured [access control lists](#access-control-list).
+
+An access subject can be a [user](#access-user) or a [group](#access-group).
+
+### Access right {#access-right}
+
+An **[access right](../security/authorization.md#right)** is an entity that represents permission for an [access subject](#access-subject) to perform a specific set of operations in a cluster or database on a specific [access object](#access-object).
+
+### Access control list {#access-control-list}
+
+An **access control list** or **ACL** is a list of all [rights](#access-right) granted to [access subjects](#access-subject) (users and groups) for a specific [access object](#access-object).
+
+### Owner {#access-owner}
+
+An **[owner](../security/authorization.md#owner)** is an [access subject](#access-subject) ([user](#access-user) or [group](#access-group)) having full rights over a specific [access object](#access-object).
+
+### User {#access-user}
+
+A **[user](../security/authorization.md#user)** is an individual utilizing {{ ydb-short-name }} to perform a specific function.
+
+### Group {#access-group}
+
+A **[group](../security/authorization.md#group)** or **access group** is a named collection of [users](#access-user) with identical [access rights](#access-right) to certain [access objects](#access-object).
+
+### SID {#access-sid}
+
+**SID** (**Security Identifier**) is a string in the format `<login>[@<subsystem>]`, identifying an [access subject](../concepts/glossary.md#access-subject) in [access control lists](#access-control-list).
 
 ### Query optimizer {#optimizer}
 

ydb/docs/en/core/concepts/toc_i.yaml

@@ -3,8 +3,6 @@ items:
   href: glossary.md
 - name: Connecting to a database
   href: connect.md
-- name: Authentication
-  href: auth.md
 - name: Data model and schema
   href: datamodel/index.md
   include:

ydb/docs/en/core/dev/example-app/go/_includes/run_custom.md

@@ -1,6 +1,6 @@
 To run the example against any available {{ ydb-short-name }} database, the [endpoint](../../../../concepts/connect.md#endpoint) and the [database path](../../../../concepts/connect.md#database) need to be provide.
 
-If authentication is enabled for the database, the [authentication mode](../../../../concepts/auth.md) needs to be chosen and credentials (a token or a username/password pair) need to be provided.
+If authentication is enabled for the database, the [authentication mode](../../../../security/authentication.md) needs to be chosen and credentials (a token or a username/password pair) need to be provided.
 
 Run the command as follows:
 

ydb/docs/en/core/dev/example-app/java/_includes/run_custom.md

@@ -1,6 +1,6 @@
 To run the example against any available {{ ydb-short-name }} database, the [endpoint](../../../../concepts/connect.md#endpoint) and the [database path](../../../../concepts/connect.md#database) need to be provide.
 
-If authentication is enabled for the database, the [authentication mode](../../../../concepts/auth.md) needs to be chosen and credentials (a token or a username/password pair) need to be provided.
+If authentication is enabled for the database, the [authentication mode](../../../../security/authentication.md) needs to be chosen and credentials (a token or a username/password pair) need to be provided.
 
 Run the command as follows:
 

ydb/docs/en/core/dev/example-app/java/index.md

@@ -29,7 +29,7 @@ Next, from the same working directory, run the following command to start the te
 Main driver initialization parameters
 
 * A connection string containing details about an [endpoint](../../../concepts/connect.md#endpoint) and [database](../../../concepts/connect.md#database). This is the only parameter that is required.
-* [Authentication](../../../recipes/ydb-sdk/auth.md#auth-provider) provider. Unless explicitly specified, an [anonymous connection](../../../concepts/auth.md) is used.
+* [Authentication](../../../recipes/ydb-sdk/auth.md#auth-provider) provider. Unless explicitly specified, an [anonymous connection](../../../security/authentication.md) is used.
 * [Session pool](../../../recipes/ydb-sdk/session-pool-limit.md) settings
 
 App code snippet for driver initialization:

ydb/docs/en/core/dev/example-app/python/_includes/run_custom.md

@@ -1,6 +1,6 @@
 To run the example against any available {{ ydb-short-name }} database, the [endpoint](../../../../concepts/connect.md#endpoint) and the [database path](../../../../concepts/connect.md#database) need to be provide.
 
-If authentication is enabled for the database, the [authentication mode](../../../../concepts/auth.md) needs to be chosen and credentials (a token or a username/password pair) need to be provided.
+If authentication is enabled for the database, the [authentication mode](../../../../security/authentication.md) needs to be chosen and credentials (a token or a username/password pair) need to be provided.
 
 Run the command as follows:
 

ydb/docs/en/core/dev/terraform.md

@@ -62,9 +62,9 @@ The provider will be installed in the Terraform plugins folder - `~/.terraform.d
 
 Where:
 
-* `token` - specifies the access token to the database if authentication is used, for example, using a third-party [IAM](../concepts/auth.md#iam) provider.
-* `user` - the username for accessing the database in case of using authentication by [username and password](../concepts/auth.md#static-credentials)
-* `password` - the password for accessing the database in case of using authentication by [username and password](../concepts/auth.md#static-credentials)
+* `token` - specifies the access token to the database if authentication is used, for example, using a third-party [IAM](../security/authentication.md#iam) provider.
+* `user` - the username for accessing the database in case of using authentication by [username and password](../security/authentication.md#static-credentials)
+* `password` - the password for accessing the database in case of using authentication by [username and password](../security/authentication.md#static-credentials)
 
 ## Using the Terraform provider {{ ydb-short-name }} {#work-with-tf}
 

ydb/docs/en/core/devops/manual/initial-deployment.md

@@ -484,7 +484,7 @@ Run additional dynamic nodes on other servers to ensure database scalability and
 
 If authentication mode is enabled in the cluster configuration file, initial account setup must be done before working with the {{ ydb-short-name }} cluster.
 
-The initial installation of the {{ ydb-short-name }} cluster automatically creates a `root` account with a blank password, as well as a standard set of user groups described in the [Access management](../../security/access-management.md) section.
+The initial installation of the {{ ydb-short-name }} cluster automatically creates a `root` account with a blank password, as well as a standard set of user groups described in the [{#T}](../../yql/reference/syntax/alter-group.md#builtin) section.
 
 To perform initial account setup in the created {{ ydb-short-name }} cluster, run the following operations:
 

ydb/docs/en/core/integrations/ingestion/logstash.md

@@ -34,7 +34,7 @@ The command will return a list of all installed plugins, which contain the plugi
 
 ## Configure {{ ydb-short-name }} connection
 
-All plugins use the same set of parameters to configure the connection to {{ ydb-short-name }}. This set contains only one required parameter, `connection_string`. Other parameters are optional and allow configuring [an authentication mode](../../concepts/auth.md). An anonymous mode will be used if the configuration doesn't contain any of these parameters.
+All plugins use the same set of parameters to configure the connection to {{ ydb-short-name }}. This set contains only one required parameter, `connection_string`. Other parameters are optional and allow configuring [an authentication mode](../../security/authentication.md). An anonymous mode will be used if the configuration doesn't contain any of these parameters.
 
 ```ruby
 # This example demonstrates configuration for ydb_storage plugin.

ydb/docs/en/core/integrations/migration/liquibase.md

@@ -555,4 +555,4 @@ List of different authentication options through URL parameters:
 
 Also, if your cluster is configured using username and password, authentication is done through Liquibase parameters.
 
-For more info about different authentication settings, refer to the [section](../../concepts/auth.md).
+For more info about different authentication settings, refer to the [section](../../security/authentication.md).

ydb/docs/en/core/integrations/visualization/grafana.md

@@ -12,7 +12,7 @@ Follow the Grafana's [plugin installation docs](https://grafana.com/docs/grafana
 
 ### {{ ydb-short-name }} user for the data source
 
-Set up an {{ ydb-short-name }} user account with **read-only** permissions [(more about permissions)](../../security/access-management.md) and access to databases and tables you want to query.
+Set up an {{ ydb-short-name }} user account with **read-only** permissions [(more about permissions)](../../security/authorization.md#right) and access to databases and tables you want to query.
 
 {% note warning %}
 

ydb/docs/en/core/reference/configuration/index.md

@@ -209,7 +209,7 @@ Odd numbers must be used for `nto_select` because using even numbers does not im
 
 ## Authentication configuration {#auth}
 
-The [authentication mode](../../concepts/auth.md) in the {{ ydb-short-name }} cluster is created in the `domains_config.security_config` section.
+The [authentication mode](../../security/authentication.md) in the {{ ydb-short-name }} cluster is created in the `domains_config.security_config` section.
 
 ### Syntax
 
@@ -607,7 +607,7 @@ For a configuration located in 3 availability zones, specify 3 rings. For a conf
 
 ### Configuring LDAP authentication {#ldap-auth-config}
 
-One of the user authentication methods in {{ ydb-short-name }} is with an LDAP directory. More details about this type of authentication can be found in the section on [interacting with the LDAP directory](../../concepts/auth.md#ldap-auth-provider). To configure LDAP authentication, the `ldap_authentication` section must be defined.
+One of the user authentication methods in {{ ydb-short-name }} is with an LDAP directory. More details about this type of authentication can be found in the section on [interacting with the LDAP directory](../../security/authentication.md#ldap-auth-provider). To configure LDAP authentication, the `ldap_authentication` section must be defined.
 
 Example of the `ldap_authentication` section:
 
@@ -647,11 +647,11 @@ auth_config:
 | `bind_password` | The password for the service account used to search for the user entry. |
 | `search_filter` | A filter for searching the user entry in the LDAP directory. The filter string can include the sequence *$username*, which is replaced with the username requested for authentication in the database. |
 | `use_tls` | Configuration settings for the TLS connection between {{ ydb-short-name }} and the LDAP server. |
-| `enable` | Determines if a TLS connection [using the `StartTls` request](../../concepts/auth.md#starttls) will be attempted. When set to `true`, the `ldaps` connection scheme should be disabled by setting `ldap_authentication.scheme` to `ldap`. |
+| `enable` | Determines if a TLS connection [using the `StartTls` request](../../security/authentication.md#starttls) will be attempted. When set to `true`, the `ldaps` connection scheme should be disabled by setting `ldap_authentication.scheme` to `ldap`. |
 | `ca_cert_file` | The path to the certification authority's certificate file. |
 | `cert_require` | Specifies the certificate requirement level for the LDAP server.<br>Possible values:<ul><li>`NEVER` - {{ ydb-short-name }} does not request a certificate or accepts any presented certificate.</li><li>`ALLOW` - {{ ydb-short-name }} requests a certificate from the LDAP server but will establish the TLS session even if the certificate is not trusted.</li><li>`TRY` - {{ ydb-short-name }} requires a certificate from the LDAP server and terminates the connection if it is not trusted.</li><li>`DEMAND`/`HARD` - These are equivalent to `TRY` and are the default setting, with the value set to `DEMAND`.</li></ul> |
 | `ldap_authentication_domain` | An identifier appended to the username to distinguish LDAP directory users from those authenticated using other providers. The default value is `ldap`. |
-| `scheme` | The connection scheme to the LDAP server.<br>Possible values:<ul><li>`ldap` - Connects without encryption, sending passwords in plain text. This is the default value.</li><li>`ldaps` - Connects using TLS encryption from the first request. To use `ldaps`, disable the [`StartTls` request](../../concepts/auth.md#starttls) by setting `ldap_authentication.use_tls.enable` to `false`, and provide certificate details in `ldap_authentication.use_tls.ca_cert_file` and set the certificate requirement level in `ldap_authentication.use_tls.cert_require`.</li><li>Any other value defaults to `ldap`.</li></ul> |
+| `scheme` | The connection scheme to the LDAP server.<br>Possible values:<ul><li>`ldap` - Connects without encryption, sending passwords in plain text. This is the default value.</li><li>`ldaps` - Connects using TLS encryption from the first request. To use `ldaps`, disable the [`StartTls` request](../../security/authentication.md#starttls) by setting `ldap_authentication.use_tls.enable` to `false`, and provide certificate details in `ldap_authentication.use_tls.ca_cert_file` and set the certificate requirement level in `ldap_authentication.use_tls.cert_require`.</li><li>Any other value defaults to `ldap`.</li></ul> |
 | `requested_group_attribute` | The attribute used for reverse group membership. The default is `memberOf`. |
 | `extended_settings.enable_nested_groups_search` | A flag indicating whether to perform a request to retrieve the full hierarchy of groups to which the user's direct groups belong. |
 | `host` | The hostname of the LDAP server. This parameter is deprecated and should be replaced with the `hosts` parameter. |

ydb/docs/en/core/reference/configuration/tls.md

@@ -77,7 +77,7 @@ monitoring_config:
 
 ### LDAP
 
-{{ ydb-short-name }} supports [LDAP](../../concepts/auth.md#ldap) for user authentication. The LDAP protocol has two options for enabling TLS.
+{{ ydb-short-name }} supports [LDAP](../../security/authentication.md#ldap) for user authentication. The LDAP protocol has two options for enabling TLS.
 
 Example of enabling TLS for LDAP via the `StartTls` protocol extension:
 
@@ -123,4 +123,4 @@ tracing_config:
 
 ## Asynchronous replication
 
-[Asynchronous replication](../../concepts/async-replication.md) synchronizes data between two {{ ydb-short-name }} databases, where one serves as a client to the other. Whether this communication uses TLS-encrypted connections is controlled by the `CONNECTION_STRING` setting of [CREATE ASYNC REPLICATION](../../yql/reference/syntax/create-async-replication.md) queries. Use the `grpcs://` protocol for TLS connections. No changes to the server-side configuration are required.
+[Asynchronous replication](../../concepts/async-replication.md) synchronizes data between two {{ ydb-short-name }} databases, where one serves as a client to the other. Whether this communication uses TLS-encrypted connections is controlled by the `CONNECTION_STRING` setting of [CREATE ASYNC REPLICATION](../../yql/reference/syntax/create-async-replication.md) queries. Use the `grpcs://` protocol for TLS connections. No changes to the server-side configuration are required.