Doc changes related to security features (#17532)

Author: anton-bobkov

ydb/docs/en/core/concepts/datamodel/index.md

@@ -4,7 +4,7 @@ This section describes the {{ ydb-short-name }} cluster scheme entities.
 
 ## {{ ydb-short-name }} cluster scheme {#cluster-scheme}
 
-{{ ydb-short-name }} cluster scheme is a hierarchical namespace of a {{ ydb-short-name }} cluster. The only root element of this namespace is a **cluster scheme root**. [Databases](../../concepts/glossary.md#database) are children elements of the cluster scheme root. It is also possible to create other [scheme objects](../../concepts/glossary.md#scheme-object) in the cluster scheme root. These objects exist at the cluster level and do not belong to tenant databases. Scheme objects inside a database can use nested directories to form a hierarchy.
+{{ ydb-short-name }} cluster scheme is a hierarchical namespace of a {{ ydb-short-name }} cluster. The top-level element of the namespace is the **cluster scheme root** that contains [databases](../../concepts/glossary.md#database) as its children. Scheme objects inside a database can use nested directories to form a hierarchy.
 
 ![cluster scheme diagram](_assets/cluster-scheme.png =500x)
 

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

@@ -18,21 +18,6 @@ Like in most database management systems, a **database** in {{ ydb-short-name }}
 
 Another essential characteristic of {{ ydb-short-name }} databases is that they typically have dedicated compute resources allocated to them. Hence, creating a database requires additional operations from [DevOps engineers](../devops/index.md).
 
-{{ ydb-short-name }} has the following database types:
-
-- [tenant databases](#tenant-database)
-- [root databases](#root-database)
-
-#### Tenant database {#tenant-database}
-
-A **tenant database** is a logical container with an independent namespace for user-defined objects within the database.
-
-Tenant databases are completely isolated from each other — they are processed by separate [database nodes](#database-node), they have separate [storage groups](#storage-group), and they can have separate [users](#access-user) with different [access rights](#access-right) and [access levels](#access-level).
-
-#### Root database {#root-database}
-
-A **root database** is a system database created for {{ ydb-short-name }}'s internal purposes at the [root of the cluster scheme](#scheme-root). This database contains service data such as [users](#access-user), [access levels](#access-level) and [access rights](#access-right), [tenant databases](#tenant-database), and more.
-
 ### Node {#node}
 
 A {{ ydb-short-name }} **node** is a server process running an executable called `ydbd`. A physical server or virtual machine can run multiple {{ ydb-short-name }} nodes, which is common. Thus, in the context of {{ ydb-short-name }}, nodes are **not** synonymous with hosts.
@@ -283,13 +268,9 @@ An **authentication token** or **auth token** is a token that {{ ydb-short-name
 
 {{ ydb-short-name }} supports various [authentication modes](../security/authentication.md) and token types.
 
-### User token {#user-token}
-
-When a {{ ydb-short-name }} node gets a request from a [user](#access-user), it requests the service where the user was created to validate the user's authentication token. Upon successful validation, the node creates and caches a **user token** for validating subsequent requests from that user instead of re-validating the authentication token.
-
 ### Cluster scheme {#scheme}
 
-A **{{ ydb-short-name }} cluster scheme** is a hierarchical namespace of a {{ ydb-short-name }} cluster. The only root element of this namespace is a [cluster scheme root](#scheme-root). A root of the cluster scheme can be a [directory](#folder) or a [root database](#root-database). Children elements of the cluster scheme root can be [databases](#database) or other [scheme objects](#scheme-object). Scheme objects can use nested directories to form a hierarchy.
+A **{{ ydb-short-name }} cluster scheme** is a hierarchical namespace of a {{ ydb-short-name }} cluster. The top-level element of the namespace is the [cluster scheme root](#scheme-root) that contains [databases](#database) as its children. Scheme objects inside databases can use nested directories to form a hierarchy.
 
 ### Database scheme {#scheme-database}
 
@@ -366,7 +347,7 @@ A **[user](../security/authorization.md#user)** is an individual utilizing {{ yd
 
 {{ ydb-short-name }} has the following types of users depending on their source:
 
-- internal users in {{ ydb-short-name }} databases
+- local users in {{ ydb-short-name }} databases
 - external users from third-party directory services
 
 {{ ydb-short-name }} users are identified by their [SIDs](#access-sid).

ydb/docs/en/core/dev/system-views.md

@@ -372,7 +372,7 @@ ORDER BY IntervalEnd desc, LocksBroken desc
 
 ### Auth users {#users}
 
-The `auth_users` view lists internal {{ ydb-short-name }} [users](../concepts/glossary.md#access-user). It does not include users authenticated through external systems such as LDAP.
+The `auth_users` view lists local {{ ydb-short-name }} [users](../concepts/glossary.md#access-user). It does not include users authenticated through external systems such as LDAP.
 
 This view can be fully accessed by administrators, while regular users can only view their own details.
 

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

@@ -2,39 +2,35 @@
 
 {{ ydb-short-name }} supports various user authentication methods. The configuration for authentication providers is specified in the `auth_config` section.
 
-## Configuring internal {{ ydb-short-name }} user authentication {#internal-auth-config}
+## Configuring local {{ ydb-short-name }} user authentication {#local-auth-config}
 
-For more information about the authentication of [internal {{ ydb-short-name }} users](../../concepts/glossary.md#access-user), see [{#T}](../../security/authentication.md#static-credentials). To configure authentication by username and password, define the following parameters in the `auth_config` section:
+For more information about the authentication of [local {{ ydb-short-name }} users](../../concepts/glossary.md#access-user), see [{#T}](../../security/authentication.md#static-credentials). To configure authentication by username and password, define the following parameters in the `auth_config` section:
 
 #|
 || Parameter | Description ||
 || use_login_provider
-| Indicates whether to allow the authentication of internal users with an [authentication token](../../concepts/glossary.md#auth-token) that is obtained after entering a username and password.
+| Indicates whether to allow the authentication of local users with an [authentication token](../../concepts/glossary.md#auth-token) that is obtained after entering a username and password.
 
 Default value: `true`
     ||
 || enable_login_authentication
-| Indicates whether to allow adding internal users to {{ ydb-short-name }} databases and generating authentication tokens after an internal user enters a username and password.
+| Indicates whether to allow adding local users to {{ ydb-short-name }} databases and generating authentication tokens after an local user enters a username and password.
 
 Default value: `true`
     ||
 || domain_login_only
-| Determines the scope of internal user access rights in a {{ ydb-short-name }} cluster.
+| Determines the scope of local user access rights in a {{ ydb-short-name }} cluster.
 
 Valid values:
 
-- `true` — internal users exist in a {{ ydb-short-name }} cluster and can be granted rights to access multiple [tenant databases](../../concepts/glossary.md#tenant-database).
+- `true` — local users exist in a {{ ydb-short-name }} cluster and can be granted rights to access multiple [databases](../../concepts/glossary.md#database).
 
-    In this scenario, users are added only to the [root database](../../concepts/glossary.md#root-database).
-
-- `false` — internal users can exist either in a {{ ydb-short-name }} cluster or in tenant databases. The scope of access rights for internal users in tenant databases is limited to the database, in which they are created.
-
-    In this scenario, users are added either to the root database or to tenant databases.
+- `false` — local users can exist either at the cluster or database level. The scope of access rights for local users created at the database level is limited to the database, in which they are created.
 
 Default value: `true`
     ||
 || login_token_expire_time
-| Specifies the expiration time of the authentication token created when an internal user logs in to {{ ydb-short-name }}.
+| Specifies the expiration time of the authentication token created when an local user logs in to {{ ydb-short-name }}.
 
 Default value: `12h`
     ||
@@ -75,7 +71,7 @@ Default value: `1h`
 
 ### Configuring password complexity requirements {#password-complexity}
 
-{{ ydb-short-name }} allows internal users to authenticate using a login and password. For more information, see [authentication by login and password](../../security/authentication.md#static-credentials). To enhance security in {{ ydb-short-name }}, configure complexity requirements for the passwords of [internal users](../../concepts/glossary.md#access-user) in the `password_complexity` subsection inside the `auth_config` section.
+{{ ydb-short-name }} allows local users to authenticate using a login and password. For more information, see [authentication by login and password](../../security/authentication.md#static-credentials). To enhance security in {{ ydb-short-name }}, configure complexity requirements for the passwords of [local users](../../concepts/glossary.md#access-user) in the `password_complexity` subsection inside the `auth_config` section.
 
 Example of the `password_complexity` section:
 
@@ -288,9 +284,11 @@ Default value: `false`
     ||
 |#
 
-## Configuring user token life cycle
+## Configuring caching for authentication results
+
+During the authentication process, a user session receives an authentication token, which is transmitted along with each request to the cluster {{ydb-short-name }}. Since {{ydb-short-name }} is a distributed system, user requests will eventually be processed on one or more {{ydb-short-name }} nodes. After receiving a request from the user, a {{ydb-short-name }} node verifies the authentication token. If successful, the node generates a **user token**, which is valid only inside the current node and is used to authorize the actions requested by the user. Subsequent requests with the same authentication token to the same node do not require verification of the authentication token.
 
-Parameters for configuring the [user token](../../concepts/glossary.md#user-token) life cycle are applicable to all authentication methods.
+To configure the life cycle and other important aspects of managing user tokens, define the following parameters:
 
 #|
 || refresh_period

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

@@ -149,7 +149,7 @@ The list includes groups and their members.
 
 {% note warning %}
 
-These groups are created in the [root database](../../concepts/glossary.md#root-database) for the entire {{ ydb-short-name }} cluster.
+These groups are created for the entire {{ ydb-short-name }} cluster.
 
 {% endnote %}
 

ydb/docs/en/core/security/authentication.md

@@ -31,7 +31,7 @@ To enable anonymous authentication, use `false` in the `enforce_user_token_requi
 
 ## Authenticating by username and password {#static-credentials}
 
-Authentication by username and password using the YDB server is available only to [internal users](../concepts/glossary.md#access-user). Authentication of external users involves third-party servers.
+Authentication by username and password using the YDB server is available only to [local users](../concepts/glossary.md#access-user). Authentication of external users involves third-party servers.
 
 This access type implies that each database user has a username and password.
 Only digits and lowercase Latin letters can be used in usernames. [Password complexity requirements](#password-complexity) can be configured.
@@ -46,7 +46,7 @@ Authentication by username and password includes the following steps:
 1. The service validates authentication data. If the data matches, it generates a token and returns it to the authentication service.
 1. The client accesses the database, presenting their token as authentication data.
 
-To enable username/password authentication, use `true` in the `enforce_user_token_requirement` key of the cluster's [configuration file](../reference/configuration/index.md#auth).
+To enable authentication by username and password, ensure that the `use_login_provider` and `enable_login_authentication` parameters are set to the default value of `true` in the [configuration file](../reference/configuration/auth_config.md). Besides, to disable anonymous authentication, set the [`enforce_user_token_requirement` parameter](../reference/configuration/security_config.md) to `true`.
 
 To learn how to manage roles and users, see [{#T}](../security/authorization.md).
 

ydb/docs/en/core/security/builtin-security.md

@@ -1,12 +1,19 @@
-# Built-in security configuration
+# Initial security configuration
 
-Built-in security is configured automatically when the {{ ydb-short-name }} cluster starts for the first time, if the [`security_config`](../reference/configuration/index.md#security) section in the cluster configuration file does not define the `default_users`, `default_groups`, or `default_access` parameters.
+Initial security is configured automatically when the {{ ydb-short-name }} cluster starts for the first time.
 
-Built-in security configuration can be disabled by setting the [`domains_config.disable_builtin_security`](../reference/configuration/index.md#domains-config) parameter to `true`.
+During this process {{ ydb-short-name }} adds a [superuser](#superuser) and a set of [roles](#roles) for user access management.
 
-Built-in security configuration adds a superuser and a set of roles for user access management.
+{% note info %}
 
-## Roles
+For information about overriding and skipping initial security configuration, see the following sections:
+
+- [{#T}](#skip-initial-security)
+- [{#T}](#override-initial-security)
+
+{% endnote %}
+
+## Roles {#roles}
 
 | Role              | Description |
 |------------------|-------------|
@@ -19,7 +26,7 @@ Built-in security configuration adds a superuser and a set of roles for user acc
 | `METADATA-READERS` | Provides access rights for scheme objects. No data access. |
 | `USERS`         | Provides access rights for databases. This is a common group for all users. |
 
-## Groups
+## Groups {#groups}
 
 Roles in {{ ydb-short-name }} are implemented as a hierarchy of [user](../concepts/glossary.md#access-user) [groups](./authorization.md#group) and a set of [access rights](./authorization.md#right) for these groups. Access rights for the groups are granted on the cluster scheme root.
 
@@ -40,14 +47,24 @@ Users in the `DDL-ADMINS` group are allowed to:
 
 Users in the `ADMINS` group are allowed to perform all operations on the scheme and data.
 
-## Superuser
+## Superuser {#superuser}
 
 A superuser belongs to the `ADMINS` and `USERS` groups and has full access rights to the cluster scheme.
 
 By default, a superuser is the `root` user with an empty password.
 
-## A group for all users
+## A group for all users {#all-users-group}
+
+The `USERS` group is a common [group](../concepts/glossary.md#access-group) for all local [users](../concepts/glossary.md#access-user). When you [add new users](./authorization.md#user), they are automatically added to the `USERS` group.
+
+For more information about managing groups and users, see [{#T}](../security/authorization.md).
+
+## Overriding initial security configuration {#override-initial-security}
+
+You can override the initial security configuration with a custom set of users, groups, and access rights.
+
+To specify custom users, groups, and access rights to be created during the initial security configuration, define the `default_users`, `default_groups`, or `default_access` parameters in the [`security_config`](../reference/configuration/security_config.md#security-bootstrap) section in the cluster configuration file.
 
-The `USERS` group is a common [group](../concepts/glossary.md#access-group) for all internal [users](../concepts/glossary.md#access-user). When you [add new users](./authorization.md#user), they are automatically added to the `USERS` group.
+## Skipping initial security configuration {#skip-initial-security}
 
-For more information about managing groups and users, see [{#T}](../security/authorization.md).
+You can skip initial security configuration by setting the [`security_config.disable_builtin_security`](../reference/configuration/index.md#domains-config) parameter to `true`.