Docs feature security

ydb/docs/en/core/_includes/builtin-groups-graph.md

@@ -0,0 +1,56 @@
+```mermaid
+---
+config:
+  layout: elk
+  elk:
+    mergeEdges: true
+    nodePlacementStrategy: NETWORK_SIMPLEX
+---
+graph BT
+
+DATA-WRITERS & DATABASE-ADMINS --> ADMINS
+DDL-ADMINS & ACCESS-ADMINS --> DATABASE-ADMINS
+DATA-READERS --> DATA-WRITERS
+METADATA-READERS --> DATA-READERS & DDL-ADMINS
+%%USERS --> METADATA-READERS & DATA-READERS & DATA-WRITERS & DDL-ADMINS & ACCESS-ADMINS & DATABASE-ADMINS & ADMINS
+USERS --> METADATA-READERS & DDL-ADMINS & ACCESS-ADMINS
+
+    DATA-READERS["<b>DATA-READERS</b>
+    +SelectRow"
+    ]
+
+    DATA-WRITERS["<b>DATA-WRITERS</b>
+    +UpdateRow
+    +EraseRow"
+    ]
+
+    METADATA-READERS["<b>METADATA-READERS</b>
+    +DescribeSchema
+    +ReadAttributes"
+    ]
+
+    DATABASE-ADMINS["<b>DATABASE-ADMINS</b>
+    +CreateDatabase
+    +DropDatabase"
+    ]
+
+    ACCESS-ADMINS["<b>ACCESS-ADMINS</b>
+    +GrantAccessRights"
+    ]
+
+    DDL-ADMINS["<b>DDL-ADMINS</b>
+    +CreateDirectory
+    +CreateTable
+    +CreateQueue
+    +WriteAttributes
+    +AlterSchema
+    +RemoveSchema"
+    ]
+
+    USERS[<b>USERS</b>
+    +ConnectDatabase
+    ]
+    ADMINS[<b>ADMINS</b>]
+```
+
+[//]: # (diplodoc support for mermaid lacks support for markdown in labels)

ydb/docs/en/core/concepts/datamodel/_assets/cluster-scheme.drawio

@@ -0,0 +1,79 @@
+<mxfile host="drawio.yandex-team.ru" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 YaBrowser/25.2.0.0 Safari/537.36" version="24.7.8">
+  <diagram name="Page-1" id="xOArDndSjSA-d0e_20V2">
+    <mxGraphModel dx="1985" dy="1409" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-30" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;strokeColor=#000000;" edge="1" parent="1" source="DQRrSMZlwbo2s5G8Pi1W-28" target="DQRrSMZlwbo2s5G8Pi1W-29">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-41" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;strokeColor=#000000;" edge="1" parent="1" source="DQRrSMZlwbo2s5G8Pi1W-28" target="DQRrSMZlwbo2s5G8Pi1W-39">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-28" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;Cluster scheme root&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#bac8d3;strokeColor=#23445d;fontColor=#000000;" vertex="1" parent="1">
+          <mxGeometry width="160" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-43" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;strokeColor=#000000;" edge="1" parent="1" source="DQRrSMZlwbo2s5G8Pi1W-29" target="DQRrSMZlwbo2s5G8Pi1W-31">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-44" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;strokeColor=#000000;" edge="1" parent="1" source="DQRrSMZlwbo2s5G8Pi1W-29" target="DQRrSMZlwbo2s5G8Pi1W-32">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-47" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;strokeColor=#000000;" edge="1" parent="1" source="DQRrSMZlwbo2s5G8Pi1W-29" target="DQRrSMZlwbo2s5G8Pi1W-35">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-29" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;Database 1&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#7F7AA1;strokeColor=#7f7aa1;fontColor=#ffffff;" vertex="1" parent="1">
+          <mxGeometry x="120" y="80" width="160" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-31" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;Table 1&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#3399FF;" vertex="1" parent="1">
+          <mxGeometry x="240" y="160" width="160" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-45" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;strokeColor=#000000;" edge="1" parent="1" source="DQRrSMZlwbo2s5G8Pi1W-32" target="DQRrSMZlwbo2s5G8Pi1W-33">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-46" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;strokeColor=#000000;" edge="1" parent="1" source="DQRrSMZlwbo2s5G8Pi1W-32" target="DQRrSMZlwbo2s5G8Pi1W-34">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-32" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;Directory 1&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#7F7AA1;strokeColor=#7f7aa1;fontColor=#ffffff;" vertex="1" parent="1">
+          <mxGeometry x="240" y="240" width="160" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-33" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;Table 2&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#3399FF;" vertex="1" parent="1">
+          <mxGeometry x="360" y="320" width="160" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-34" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;Table 3&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#3399FF;" vertex="1" parent="1">
+          <mxGeometry x="360" y="400" width="160" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-48" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;strokeColor=#000000;" edge="1" parent="1" source="DQRrSMZlwbo2s5G8Pi1W-35" target="DQRrSMZlwbo2s5G8Pi1W-36">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-49" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;strokeColor=#000000;" edge="1" parent="1" source="DQRrSMZlwbo2s5G8Pi1W-35" target="DQRrSMZlwbo2s5G8Pi1W-38">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-35" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;Directory 2&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#7F7AA1;strokeColor=#7f7aa1;fontColor=#ffffff;" vertex="1" parent="1">
+          <mxGeometry x="240" y="480" width="160" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-50" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;strokeColor=#000000;" edge="1" parent="1" source="DQRrSMZlwbo2s5G8Pi1W-36" target="DQRrSMZlwbo2s5G8Pi1W-37">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-36" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;Directory 3&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#7F7AA1;strokeColor=#7f7aa1;fontColor=#ffffff;" vertex="1" parent="1">
+          <mxGeometry x="360" y="560" width="160" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-37" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;...&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=none;" vertex="1" parent="1">
+          <mxGeometry x="480" y="640" width="160" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-38" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;...&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=none;" vertex="1" parent="1">
+          <mxGeometry x="360" y="720" width="160" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-42" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;strokeColor=#000000;" edge="1" parent="1" source="DQRrSMZlwbo2s5G8Pi1W-39" target="DQRrSMZlwbo2s5G8Pi1W-40">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-39" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;Database 2&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#7F7AA1;strokeColor=#7f7aa1;fontColor=#ffffff;" vertex="1" parent="1">
+          <mxGeometry x="120" y="800" width="160" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="DQRrSMZlwbo2s5G8Pi1W-40" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;...&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=none;" vertex="1" parent="1">
+          <mxGeometry x="240" y="880" width="160" height="60" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

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

@@ -1,8 +1,16 @@
-# Data model and schema
+# Cluster structure
 
-This section describes the entities that {{ ydb-short-name }} uses within DBs. The {{ ydb-short-name }} core lets you flexibly implement various storage primitives, so new entities may appear in the future.
+This section describes the {{ ydb-short-name }} cluster scheme entities.
 
-{{ ydb-short-name }} is a relational database where the data is stored in [tables](table.md) with each table consisting of rows and columns. Database objects in {{ ydb-short-name }} can be organized into a hierarchy of [folders](dir.md).
+## {{ 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**. A root of the cluster scheme can be a directory or a root database. Children elements of the cluster scheme root can be [databases](../../concepts/glossary.md#database) or other [scheme objects](../../concepts/glossary.md#scheme-object). Scheme objects can use nested directories to form a hierarchy.
+
+![cluster scheme diagram](_assets/cluster-scheme.png =500x)
+
+## {{ ydb-short-name }} scheme objects
+
+Scheme objects in {{ ydb-short-name }} databases:
 
 * [Folder](dir.md)
 * [Table](table.md)

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

@@ -18,6 +18,21 @@ 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 an additional database is usually done externally by [DevOps engineers](../devops/index.md) or automation rather than via a SQL query.
 
+{{ 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.
@@ -262,6 +277,32 @@ 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.
 
+### Authentication token {#auth-token}
+
+An **authentication token** or **auth token** is a token that {{ ydb-short-name }} uses for [authentication](../security/authentication.md).
+
+{{ ydb-short-name }} supports various [authentication modes](../security/authentication.md) and token types.
+
+### User token {#user-token}
+
+When a YDB 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.
+
+### Database scheme {#scheme-database}
+
+A **database scheme** is a subset of the hierarchical namespace of a {{ ydb-short-name }} cluster that belongs to a database.
+
+### Database root {#scheme-database-root}
+
+A **database root** is a path to a database in a {{ ydb-short-name }} cluster scheme. This path acts as a root for database scheme objects.
+
+### Scheme root {#scheme-root}
+
+A **scheme root** is a root element of a [{{ ydb-short-name }} cluster scheme](datamodel/index.md#cluster-scheme). Children elements of the cluster scheme root can be [databases](#database) or other [scheme objects](#scheme-object).
+
 ### 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.
@@ -297,6 +338,24 @@ An **[access right](../security/authorization.md#right)** is an entity that repr
 
 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).
 
+### Access level {#access-level}
+
+An **access level** determines additional privileges of an [access subject](#access-subject) for [scheme objects](#scheme-object) as well as privileges that are not related to [scheme objects](#scheme-object).
+
+{{ ydb-short-name }} uses three access levels:
+
+- viewer
+- operator
+- administrator
+
+An access level is granted by adding an access subject to an [access level list](#access-level-list).
+
+### Access level list {#access-level-list}
+
+An **access level list** is a list of [SIDs](#access-sid) that grants a certain [access level](#access-level) to the associated [access subjects](#access-subject).
+
+{{ ydb-short-name }} provides several [access level lists](../reference/configuration/security_config.md#security-access-levels) that collectively determine [access levels](#access-level) in the system.
+
 ### 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).
@@ -305,6 +364,13 @@ An **[owner](../security/authorization.md#owner)** is an [access subject](#acces
 
 A **[user](../security/authorization.md#user)** is an individual utilizing {{ ydb-short-name }} to perform a specific function.
 
+{{ ydb-short-name }} has the following types of users depending on their source:
+
+- internal users in {{ ydb-short-name }} databases
+- external users from third-party directory services
+
+{{ ydb-short-name }} users are identified by their [SIDs](#access-sid).
+
 ### 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).