Skip to content

Commit 0cffab3

Browse files
lopatinevgenylopatinevgeny
authored
25-1 SysView Auth Documentation (#15413 & #16654) (#20023)
2 parents a37b73d + 13175b9 commit 0cffab3

File tree

4 files changed

+241
-19
lines changed

4 files changed

+241
-19
lines changed

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,10 @@ An access subject can be a [user](#access-user) or a [group](#access-group).
280280

281281
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).
282282

283+
### Access right inheritance {#access-right-inheritance}
284+
285+
**Access rights inheritance** is a mechanism by which [access rights](#access-right) granted on parent [access objects](#access-object) are inherited by child objects in the hierarchical structure of the database. This ensures that permissions granted at a higher level in the hierarchy are applied to all sub-levels beneath it, unless [explicitly overridden](../reference/ydb-cli/commands/scheme-permissions.md#clear-inheritance).
286+
283287
### Access control list {#access-control-list}
284288

285289
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).

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

Lines changed: 117 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ DB system views contain:
1010
* [Top queries by certain characteristics](#top-queries).
1111
* [Query details](#query-metrics).
1212
* [History of overloaded partitions](#top-overload-partitions).
13+
* [Information about users, groups, and access rights](#auth).
1314

1415
{% note info %}
1516

@@ -29,8 +30,8 @@ Cumulative fields (`RowReads`, `RowUpdates`, and so on) store the accumulated va
2930

3031
Table structure:
3132

32-
| Field | Description |
33-
| --- | --- |
33+
| Column | Description |
34+
|--------|-------------|
3435
| `OwnerId` | ID of the SchemeShard serving the table.<br/>Type: `Uint64`.<br/>Key: `0`. |
3536
| `PathId` | ID of the SchemeShard path.<br/>Type: `Uint64`.<br/>Key: `1`. |
3637
| `PartIdx` | Partition sequence number.<br/>Type: `Uint64`.<br/>Key: `2`. |
@@ -99,10 +100,10 @@ Fields that provide information about the used CPU time (...`CPUTime`) are expre
99100

100101
Query text limit is 4 KB.
101102

102-
All tables have the same set of fields:
103+
All tables have the same structure:
103104

104-
| Field | Description |
105-
| --- | --- |
105+
| Column | Description |
106+
|--------|-------------|
106107
| `IntervalEnd` | The end of a one-minute or one-hour interval.<br/>Type: `Timestamp`.<br/>Key: `0`. |
107108
| `Rank` | Rank of a top query.<br/>Type: `Uint32`.<br/>Key: `1`. |
108109
| `QueryText` | Query text.<br/>Type: `Utf8`. |
@@ -180,8 +181,8 @@ Restrictions:
180181

181182
Table structure:
182183

183-
| Field | Description |
184-
| ---|--- |
184+
| Column | Description |
185+
|--------|-------------|
185186
| `IntervalEnd` | The end of a one-minute interval.<br/>Type: `Timestamp`.<br/>Key: `0`. |
186187
| `Rank` | Query rank within an interval (by the SumCPUTime field).<br/>Type: `Uint32`.<br/>Key: `1`. |
187188
| `QueryText` | Query text.<br/>Type: `Utf8`. |
@@ -250,10 +251,10 @@ The following system views (tables) store the history of points in time when the
250251

251252
These tables contain partitions with peak loads of more than 70% (`CPUCores` > 0.7). Partitions within a single interval are ranked by peak load value.
252253

253-
Both tables have the same set of fields:
254+
All tables have the same structure:
254255

255-
| Field | Description |
256-
| --- | --- |
256+
| Column | Description |
257+
|--------|-------------|
257258
| `IntervalEnd` | The end of a one-minute or one-hour interval.<br/>Type: `Timestamp`.<br/>Key: `0`. |
258259
| `Rank` | Partition rank within an interval (by CPUCores).<br/>Type: `Uint32`.<br/>Key: `1`. |
259260
| `TabletId` | ID of the tablet serving the partition.<br/>Type: `Uint64`. |
@@ -301,3 +302,109 @@ ORDER BY IntervalEnd desc, CPUCores desc
301302
```
302303

303304
* `"YYYY-MM-DDTHH:MM:SS.UUUUUUZ"`: Time in the UTC 0 zone (`YYYY` stands for year, `MM`, for month, `DD`, for date, `hh`, for hours, `mm`, for minutes, `ss`, for seconds, and `uuuuuu`, for microseconds). For example, `"2023-01-26T13:00:00.000000Z"`.
305+
306+
## Users, groups, and access rights {#auth}
307+
308+
The following system views contain information about users, access groups, user membership in groups, as well as information about access rights granted to groups or directly to users.
309+
310+
### Auth users
311+
312+
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.
313+
314+
This view can be fully accessed by administrators, while regular users can only view their own details.
315+
316+
Table structure:
317+
318+
| Column | Description |
319+
|--------|-------------|
320+
| `Sid` | [SID](../concepts/glossary.md#sid) of the user.<br />Type: `Utf8`.<br />Key: `0`. |
321+
| `IsEnabled` | Indicates if login is allowed; used for explicit administrator block. Independent of `IsLockedOut`.<br />Type: `Bool`. |
322+
| `IsLockedOut` | Indicates that user has been automatically deactivated due to exceeding the threshold for unsuccessful authentication attempts. Independent of `IsEnabled`.<br />Type: `Bool`. |
323+
| `CreatedAt` | Timestamp of user creation.<br />Type: `Timestamp`. |
324+
| `LastSuccessfulAttemptAt` | Timestamp of the last successful authentication attempt.<br />Type: `Timestamp`. |
325+
| `LastFailedAttemptAt` | Timestamp of the last failed authentication attempt.<br />Type: `Timestamp`. |
326+
| `FailedAttemptCount` | Number of failed authentication attempts.<br />Type: `Uint32`. |
327+
| `PasswordHash` | JSON string containing password hash, salt, and hash algorithm.<br />Type: `Utf8`. |
328+
329+
### Auth groups
330+
331+
The `auth_groups` view lists [access groups](../concepts/glossary.md#access-group).
332+
333+
This view can be accessed only by administrators.
334+
335+
Table structure:
336+
337+
| Column | Description |
338+
|--------|-------------|
339+
| `Sid` | [SID](../concepts/glossary.md#sid) of the group.<br />Type: `Utf8`.<br />Key: `0`. |
340+
341+
### Auth group members
342+
343+
The `auth_group_members` view lists membership details within [access groups](../concepts/glossary.md#access-group).
344+
345+
This view can be accessed only by administrators.
346+
347+
Table structure:
348+
349+
| Column | Description |
350+
|--------|-------------|
351+
| `GroupSid` | SID of the group.<br />Type: `Utf8`.<br />Key: `0`. |
352+
| `MemberSid` | SID of the group member. This can be either the SID of a user or the SID of a group.<br />Type: `Utf8`.<br />Key: `1`. |
353+
354+
### Auth permissions
355+
356+
The auth permissions views list assigned [access rights](../concepts/glossary.md#access-right).
357+
358+
There are two views:
359+
360+
* `auth_permissions`: Directly assigned access rights.
361+
* `auth_effective_permissions`: Effective access rights, accounting for [inheritance](../concepts/glossary.md#access-right-inheritance).
362+
363+
In this view, the user sees only those [access objects](../concepts/glossary.md#access-object) for which they have the `ydb.granular.describe_schema` permission.
364+
365+
Table structure:
366+
367+
| Column | Description |
368+
|--------|-------------|
369+
| `Path` | Path to the access object.<br />Type: `Utf8`.<br />Key: `0`. |
370+
| `Sid` | SID of the [access subject](../concepts/glossary.md#access-subject).<br />Type: `Utf8`.<br />Key: `1`. |
371+
| `Permission` | Name of the {{ ydb-short-name }} [access right](../yql/reference/syntax/grant.md#permissions-list).<br />Type: `Utf8`.<br />Key: `2`. |
372+
373+
#### Example queries
374+
375+
Retrieving explicitly granted permissions on the access object - table `my_table`:
376+
377+
```yql
378+
SELECT *
379+
FROM `.sys/auth_permissions`
380+
WHERE Path = "my_table"
381+
```
382+
383+
Retrieving effective permissions on the access object - table `my_table`:
384+
385+
```yql
386+
SELECT *
387+
FROM `.sys/auth_effective_permissions`
388+
WHERE Path = "my_table"
389+
```
390+
391+
Retrieving the permissions granted to the user `user3`:
392+
393+
```yql
394+
SELECT *
395+
FROM `.sys/auth_permissions`
396+
WHERE Sid = "user3"
397+
```
398+
399+
### Auth owners
400+
401+
The `auth_owners` view lists details of [access objects](../concepts/glossary.md#access-object) [ownership](../concepts/glossary.md#access-owner).
402+
403+
In this view, the user sees only those [access objects](../concepts/glossary.md#access-object) for which they have the `ydb.granular.describe_schema` permission.
404+
405+
Table structure:
406+
407+
| Column | Description |
408+
|--------|-------------|
409+
| `Path` | Path to the access object.<br />Type: `Utf8`.<br />Key: `0`. |
410+
| `Sid` | SID of the access object owner.<br />Type: `Utf8`. |

‎ydb/docs/ru/core/concepts/glossary.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -305,6 +305,10 @@
305305

306306
**[Право доступа](../security/authorization.md#right)** или **access right** — сущность, отражающая разрешение [субъекту доступа](#access-subject) выполнять конкретный набор операций в кластере или базе данных над конкретным [объектом доступа](#access-object).
307307

308+
### Наследование прав доступа {#access-right-inheritance}
309+
310+
**Наследование прав доступа** — механизм, при котором [права доступа](#access-right) выданные на родительские [объекты доступа](#access-object) наследуются дочерними объектами в иерархической структуре базы данных. Это гарантирует, что разрешения, предоставленные на более высоком уровне иерархии, применяются ко всем нижестоящим уровням, если они не [переопределены явно](../reference/ydb-cli/commands/scheme-permissions.md#clear-inheritance).
311+
308312
### Список прав {#access-control-list}
309313

310314
**[Список прав](../security/authorization.md#right)**, **access control list** или **ACL** — список всех [прав](#access-right), предоставленных [субъектам доступа](#access-subject) (пользователям и группам) на конкретный [объект доступа](#access-object).

‎ydb/docs/ru/core/dev/system-views.md

Lines changed: 116 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
* [Топы запросов по определенным характеристикам](#top-queries).
1111
* [Подробная информация о запросах](#query-metrics).
1212
* [История перегруженных партиций](#top-overload-partitions).
13+
* [Информацию о пользователях, группах и правах](#auth).
1314

1415
{% note info %}
1516

@@ -29,8 +30,8 @@
2930

3031
Структура представления:
3132

32-
Поле | Описание
33-
--- | ---
33+
Колонка | Описание
34+
------- | --------
3435
`OwnerId` | Идентификатор SchemeShard, обслуживающего таблицу.<br/>Тип: `Uint64`.<br/>Ключ: `0`.
3536
`PathId` | Идентификатор пути в SchemeShard.<br/>Тип: `Uint64`.<br/>Ключ: `1`.
3637
`PartIdx` | Порядковый номер партиции.<br/>Тип: `Uint64`.<br/>Ключ: `2`.
@@ -99,10 +100,10 @@ GROUP BY Path
99100

100101
Текст запроса ограничен 4 килобайтами.
101102

102-
Все представления содержат одинаковый набор полей:
103+
Все представления имеют одинаковую структуру:
103104

104-
Поле | Описание
105-
--- | ---
105+
Колонка | Описание
106+
------- | --------
106107
`IntervalEnd` | Момент закрытия минутного или часового интервала.<br/>Тип: `Timestamp`.<br/>Ключ: `0`.
107108
`Rank` | Ранг запроса в топе.<br/>Тип: `Uint32`.<br/>Ключ: `1`.
108109
`QueryText` | Текст запроса.<br/>Тип: `Utf8`.
@@ -181,7 +182,7 @@ WHERE Rank = 1
181182

182183
Структура представления:
183184

184-
Поле | Описание
185+
Колонка | Описание
185186
---|---
186187
`IntervalEnd` | Момент закрытия минутного интервала.<br/>Тип: `Timestamp`.<br/>Ключ: `0`.
187188
`Rank` | Ранг запроса в пределах интервала (по полю SumCPUTime).<br/>Тип: `Uint32`.<br/>Ключ: `1`.
@@ -250,10 +251,10 @@ LIMIT 100
250251

251252
В представления попадают партиции с пиковой нагрузкой более 70 % (`CPUCores` > 0,7). В пределах одного интервала партиции ранжированы по пиковому значению нагрузки.
252253

253-
Оба представления содержат одинаковый набор полей:
254+
Все представления имеют одинаковую структуру:
254255

255-
Поле | Описание
256-
--- | ---
256+
Колонка | Описание
257+
------- | --------
257258
`IntervalEnd` | Момент закрытия минутного или часового интервала.<br/>Тип: `Timestamp`.<br/>Ключ: `0`.
258259
`Rank` | Ранг партиции в пределах интервала (по CPUCores).<br/>Тип: `Uint32`.<br/>Ключ: `1`.
259260
`TabletId` | Идентификатор таблетки, обслуживающей партицию.<br/>Тип: `Uint64`.
@@ -301,3 +302,109 @@ ORDER BY IntervalEnd desc, CPUCores desc
301302
```
302303

303304
* `"YYYY-MM-DDTHH:MM:SS.UUUUUUZ"` — время в зоне UTC 0 (`YYYY` — год, `MM` — месяц, `DD` — число, `hh` — часы, `mm` — минуты, `ss` — секунды, `uuuuuu` — микросекунды). Например, `"2023-01-26T13:00:00.000000Z"`.
305+
306+
## Пользователи, группы и права доступа {#auth}
307+
308+
Следующие системные представления содержат информацию о пользователях, группах доступа, членстве пользователей в группах, а также информацию о предоставленных правах доступа группам или непосредственно пользователям.
309+
310+
### Информация о пользователях
311+
312+
Представление `auth_users` содержит список внутренних [пользователей](../concepts/glossary.md#access-user) {{ ydb-short-name }}. В него не входят пользователи, аутентифицированные через внешние системы, такие как LDAP.
313+
314+
Полный доступ к этому представлению имеют администраторы. Обычные пользователи могут просматривать только свои собственные данные.
315+
316+
Структура таблицы:
317+
318+
| Колонка | Описание |
319+
|---------|----------|
320+
| `Sid` | [SID](../concepts/glossary.md#sid) пользователя.<br />Тип: `Utf8`.<br />Ключ: `0`. |
321+
| `IsEnabled` | Указывает, разрешён ли вход данному пользователю; используется для явной блокировки администратором. Независим от `IsLockedOut`.<br />Тип: `Bool`. |
322+
| `IsLockedOut` | Указывает, что данный пользователь автоматически заблокирован из-за превышения количества неудачных аутентификаций. Независим от `IsEnabled`.<br />Тип: `Bool`. |
323+
| `CreatedAt` | Время создания пользователя.<br />Тип: `Timestamp`. |
324+
| `LastSuccessfulAttemptAt` | Время последней успешной аутентификации.<br />Тип: `Timestamp`. |
325+
| `LastFailedAttemptAt` | Время последней неудачной аутентификации.<br />Тип: `Timestamp`. |
326+
| `FailedAttemptCount` | Количество неудачных аутентификаций.<br />Тип: `Uint32`. |
327+
| `PasswordHash` | JSON-строка, содержащая хеш пароля, соль и алгоритм хеширования.<br />Тип: `Utf8`. |
328+
329+
### Информация о группах
330+
331+
Представление `auth_groups` содержит список [групп доступа](../concepts/glossary.md#access-group).
332+
333+
Доступ к этому представлению имеют только администраторы.
334+
335+
Структура таблицы:
336+
337+
| Колонка | Описание |
338+
|---------|----------|
339+
| `Sid` | [SID](../concepts/glossary.md#sid) группы.<br />Тип: `Utf8`.<br />Ключ: `0`. |
340+
341+
### Информация о членстве в группах
342+
343+
Представление `auth_group_members` содержит информацию о членстве в [группах доступа](../concepts/glossary.md#access-group).
344+
345+
Доступ к этому представлению имеют только администраторы.
346+
347+
Структура таблицы:
348+
349+
| Колонка | Описание |
350+
|---------|----------|
351+
| `GroupSid` | SID группы.<br />Тип: `Utf8`.<br />Ключ: `0`. |
352+
| `MemberSid` | SID участника группы. Может быть указан как SID непосредственно пользователя, так и SID группы.<br />Тип: `Utf8`.<br />Ключ: `1`. |
353+
354+
### Информация о правах доступа
355+
356+
Представления содержат список выданных [прав доступа](../concepts/glossary.md#access-right).
357+
358+
Включают два представления:
359+
360+
* `auth_permissions`: Явно выданные права доступа.
361+
* `auth_effective_permissions`: Эффективные права доступа с учётом [наследования](../concepts/glossary.md#access-right-inheritance).
362+
363+
Пользователю в данном представлении отображаются только те [объекты доступа](../concepts/glossary.md#access-object), на которые у него есть право `ydb.granular.describe_schema`.
364+
365+
Структура таблицы:
366+
367+
| Колонка | Описание |
368+
|---------|----------|
369+
| `Path` | Путь к объекту доступа.<br />Тип: `Utf8`.<br />Ключ: `0`. |
370+
| `Sid` | SID [субъекта доступа](../concepts/glossary.md#access-subject).<br />Тип: `Utf8`.<br />Ключ: `1`. |
371+
| `Permission` | Название [права доступа](../yql/reference/syntax/grant.md#permissions-list) {{ ydb-short-name }}.<br />Тип: `Utf8`.<br />Ключ: `2`. |
372+
373+
#### Примеры запросов
374+
375+
Получение явно предоставленных прав на объект доступа - таблицу `my_table`:
376+
377+
```yql
378+
SELECT *
379+
FROM `.sys/auth_permissions`
380+
WHERE Path = "my_table"
381+
```
382+
383+
Получение эффективных прав на объект доступа - таблицу `my_table`:
384+
385+
```yql
386+
SELECT *
387+
FROM `.sys/auth_effective_permissions`
388+
WHERE Path = "my_table"
389+
```
390+
391+
Получение прав, предоставленных пользователю `user3`:
392+
393+
```yql
394+
SELECT *
395+
FROM `.sys/auth_permissions`
396+
WHERE Sid = "user3"
397+
```
398+
399+
### Информация о владельцах объектов доступа {#auth-owners}
400+
401+
Представление `auth_owners` отображает информацию о [владельцах](../concepts/glossary.md#access-owner) [объектов доступа](../concepts/glossary.md#access-object).
402+
403+
Пользователю в данном представлении отображаются только те [объекты доступа](../concepts/glossary.md#access-object), на которые ему предоставлено право `ydb.granular.describe_schema`.
404+
405+
Структура таблицы:
406+
407+
| Колонка | Описание |
408+
|---------|----------|
409+
| `Path` | Путь к объекту доступа.<br />Тип: `Utf8`.<br />Ключ: `0`. |
410+
| `Sid` | SID владельца объекта доступа.<br />Тип: `Utf8`. |

0 commit comments

Comments
 (0)