Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add security settings and builtin security reference #13319

Open
wants to merge 37 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
d34f99e
docs: add security settings and builtin security reference
ijon Jan 10, 2025
ddf6eed
update due to review comments
ijon Jan 15, 2025
802086d
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 15, 2025
0ac6879
fixup
ijon Jan 15, 2025
1010946
fixup
ijon Jan 16, 2025
5719d66
fixup: add ConnectDatabase for USERS
ijon Jan 16, 2025
aab402a
fixup: add direct link to disable_builtin_security
ijon Jan 16, 2025
b38f26d
fixup
ijon Jan 16, 2025
b105adf
revert: links to direct achors work incorrectly
ijon Jan 16, 2025
8ea4022
fixup: review comments
ijon Jan 16, 2025
f863b9a
fuse after rebase
ijon Jan 17, 2025
f2baf54
fixup
ijon Jan 17, 2025
9816673
fixup
ijon Jan 17, 2025
d76f100
Update ydb/docs/ru/core/security/builtin-security.md
ijon Jan 20, 2025
0e321d2
Update ydb/docs/ru/core/security/builtin-security.md
ijon Jan 20, 2025
e907708
fixup: touch up ldap auth
ijon Jan 20, 2025
0c50ccb
Update ydb/docs/ru/core/changelog-server.md
ijon Jan 21, 2025
8110d97
Update ydb/docs/ru/core/concepts/glossary.md
ijon Jan 21, 2025
951ace1
Update ydb/docs/ru/core/concepts/glossary.md
ijon Jan 21, 2025
beccbc2
Update ydb/docs/ru/core/concepts/glossary.md
ijon Jan 21, 2025
021dd6f
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 21, 2025
0276037
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 21, 2025
328fb46
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 21, 2025
ff8f8e0
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 21, 2025
f51c846
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 21, 2025
ccd9d07
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 21, 2025
4b8e0af
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 21, 2025
e5115b7
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 21, 2025
2696e83
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 21, 2025
f6e3ef3
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 21, 2025
e29a849
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 21, 2025
1588fae
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 22, 2025
7576c0d
Update ydb/docs/ru/core/reference/configuration/index.md
ijon Jan 22, 2025
862fc24
Update ydb/docs/ru/core/security/builtin-security.md
ijon Jan 22, 2025
b6f6004
Update ydb/docs/ru/core/security/builtin-security.md
ijon Jan 22, 2025
b600c3c
fixup: review comments
ijon Jan 23, 2025
db5014a
Merge branch 'main' into docs-security-config
ijon Jan 23, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions ydb/docs/ru/core/_includes/builtin-groups-graph.md
Original file line number Diff line number Diff line change
@@ -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)
284 changes: 242 additions & 42 deletions ydb/docs/ru/core/reference/configuration/index.md

Large diffs are not rendered by default.

54 changes: 54 additions & 0 deletions ydb/docs/ru/core/security/builtin-security.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# "Встроенная" настройка безопасности

"Встроенная" настройка безопасности применяется автоматически при первом запуске кластера {{ ydb-short-name }}, если секция настроек безопасности в конфигурации кластера ([секция `security_config`](../reference/configuration/index.md#security)) не содержит явных настроек.

Применение "встроенной" конфигурации безопасности выключается по [флагу `domains_config.disable_builtin_security`](../reference/configuration/index.md#domains-config).
ijon marked this conversation as resolved.
Show resolved Hide resolved

"Встроенная" настройка безопасности добавляет в систему суперпользователя, а также реализует набор ролей безопасности для удобного управления пользователями.
ijon marked this conversation as resolved.
Show resolved Hide resolved

## Роли
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Если мы вводим термин «роли», то его в надо в глоссарий и обязательно с объяснением в чём отличия от групп (в других СУБД они могут быть вообще синонимами).

Но в реальности это же насколько я понимаю скорее захардкоженные группы просто?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Роль -- логическое понятие, физически в ydb есть группы и списки уровней доступа. Ролей, как сущностей, нет. Но это не мешает пользователю думать о модели управления доступом в терминах ролей.

Встроенная настройка безопасности, по сути, как раз и создаёт набор групп для реализации набора ролей в рамках определённой модели управления доступом.

О чём здесь и сказано. Это предложение -- про смысл, а не про реализацию.


Роль | Описание
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

вероятно это субъективно, но кажется эта табличка легче читалась бы в обратном порядке: мол вот у нас пользователь совсем без прав и мы по мере чтения видим группы с дополнительными правами, а сейчас наоборот от полных прав по ходу чтения что-то теряется и надо прям напрячься чтоб понять что именно

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Тогда нужно разворачивать с ног на голову и диаграмму иерархии групп. А у диаграммы порядок был такой изначально и, как мне говорили, подсмотрен в документации oracle.

--- | ---
`ADMINS` | Неограниченные права на всю схему кластера.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

что такое схема кластера?

Copy link
Collaborator Author

@ijon ijon Jan 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

В чём состоит вопрос?

Мы же говорим про объекты схемы (директории, таблицы, топики)? -- ну так объекты схемы живут в схеме, схема одна на весь кластер и это единое пространство -- схема кластера. Да, в схеме кластера есть подпространства -- схемы баз.

Могу в словарь добавить ровно слова выше -- это follow-up, вообще не входит в фокус текущего pr.

[YDBDOCS-1006: Описать понятие и концепцию схемы (кластера, баз)]

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

по картинке выглядит как-будто ADMINS сам по себе дополнительных прав не даёт? а лишь является алиасом к DATABASE-ADMINS+DATA-WRITERS — если так, то лучше в тексте это тоже прямым текстом написать

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Словами уже выражен конечный эффект ("может всё"), и картинка дополняет и подкрепляет слова визуально. Почему уточнение про ADMINS вдруг важно, что даст?

В статье описывается к чему приводит встроенная настройка безопасности, и не описывается логическая модель доступа, которую эта настройка реализует. И задача так и не ставилась.

Если хочется продвигать и рекомендовать эту нашу встроенную модель доступа, рассказывать какая она удобная, объяснять почему в ней такие роли и почему это хорошо, то это отдельная тема и follow-up.

`DATABASE-ADMINS` | Права на управление базами, схемой и доступами на схеме, без доступа к данным.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

тут схема — это «схема кластера» из предыдущего пункта или что-то другое?
без контекста я б подумал, что речь о схеме данных таблиц, которая про ассортимент колонок и их типы данных

в общем, конкретнее надо

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Конечно, имеется в виду схема как пространство путей (кластера или базы). Это понятие более высокого порядка, чем набор колонок с типами в таблице.
Существовало в ydb всегда и испокон веков. Для меня загадка, почему его нет в документации.

А слова схемный объект или объект схемы (в документации есть оба варианта) как воспринимаются?

Как в документации называется пространство путей, в котором живут директории, базы, таблицы, топики и т.п.? -- можно было бы попробовать заменить им понятие схемы. Хотя понятие схемы настолько фундаментальное, что скорее всего не получится.

`ACCESS-ADMINS` | Права на управление доступами на схеме, без доступа к данным.
`DDL-ADMINS` | Права на управление схемой, без доступа к данным.
`DATA-WRITERS` | Права на доступ к схемным объектам, и на чтение и изменение данных.
`DATA-READERS` | Права на доступ к схемным объектам, и на чтение данных.
`METADATA-READERS` | Права на доступ к схемным объектам, без доступа к данным.
`USERS` | Права на доступ к базам, общая группа всех пользователей.

## Группы
ijon marked this conversation as resolved.
Show resolved Hide resolved

Роли реализуются с помощью иерархии пользовательских групп и необходимого набора разрешений этим группам. Возможности групп задаются с помощью разрешений, выданных на корне схемы кластера.

Группы включаются друг в друга и таким образом по цепочке наследуют соответствующие разрешения:

{% include notitle [builtin-groups-graph](../_includes/builtin-groups-graph.md) %}

Например, пользователям группы `DATA-WRITERS`:

- разрешено смотреть схему -- `METADATA-READERS`
- читать данные -- `DATA-READERS`
- и менять их -- `DATA-WRITERS`
ijon marked this conversation as resolved.
Show resolved Hide resolved

Пользователям группы `DDL-ADMINS`:

- разрешено смотреть схему -- `METADATA-READERS`
- и менять ёё -- `DDL-ADMINS`.
ijon marked this conversation as resolved.
Show resolved Hide resolved

Пользователи группы `ADMINS` со схемой и данными могут делать всё.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Нужно пояснить как эти группы сочетаются с настройками ***_allowed_sids. Например, не понятно:

  1. если пользователь уже состоит в группе ADMINS, получит ли он какие-то дополнительные права при добавлении его же в administration_allowed_sids?
  2. даёт ли какая-то из этих групп к управлению бекапами, что было примером у monitoring_allowed_sids? и почему это вообще не просто чтение данных?
  3. можно ли «испортить» описываемое тут поведение по умолчанию через эти настройки ***_allowed_sids?

Copy link
Collaborator Author

@ijon ijon Jan 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Про сочетание с *_allowed_sid -- это follow-up.

Ещё раз -- прямо сейчас здесь просто фиксация того, что встроенная настройка безопасности делает. А делает она сейчас неполноценную вещь. Например, ADMINS без добавления в administration_allowed_sids -- никакой не админ, но встроенная настройка сама *_allowed_sids не манипулирует.

Что именно нужно ещё делать, чтобы админы кластера и админы баз заработали, как надо, -- про это последующие pr'ы (которые ждут этого).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. если пользователь уже состоит в группе ADMINS, получит ли он какие-то дополнительные права при добавлении его же в administration_allowed_sids?

Получит. ADMINS без членства в administration_allowed_sids не является полноценным админом.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. даёт ли какая-то из этих групп к управлению бекапами, что было примером у monitoring_allowed_sids? и почему это вообще не просто чтение данных?

Бекап не просто чтение, потому что при бекапе делается копия таблиц, то есть запись. Отдельной роли/группы только на бекапы в этой модели нет. В этой модели бекап может делать только ADMINS.

Copy link
Collaborator Author

@ijon ijon Jan 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. можно ли «испортить» описываемое тут поведение по умолчанию через эти настройки ***_allowed_sids?

Частично можно. Можно не дать доступ в YDB UI или дать всем группам админство. Но на права на схеме это не повлияет.


## Суперпользователь
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

в глоссарий это

Copy link
Collaborator Author

@ijon ijon Jan 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Уже отвечал -- нет чёткого определения пока -- follow-up.


Суперпользователь входит в группу `ADMINS` (и `USERS`) и обладает полными правами на схему кластера.

По-умолчанию, суперпользователь называется `root` и имеет пустой пароль.
ijon marked this conversation as resolved.
Show resolved Hide resolved
ijon marked this conversation as resolved.
Show resolved Hide resolved

## Группа всех пользователей

Группа `USERS` также определяется как общая группа всех локальных пользователей. При последующем создании локальных пользователей они будут автоматически становиться членами группы `USERS`.

[//]: # (TODO: добавить ссылку на раздел про работу с пользователями)

1 change: 1 addition & 0 deletions ydb/docs/ru/core/security/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@

- [{#T}](authentication.md)
- [{#T}](authorization.md)
- [{#T}](builtin-security.md)
- [{#T}](audit-log.md)
- Шифрование:

Expand Down
2 changes: 2 additions & 0 deletions ydb/docs/ru/core/security/toc_p.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ items:
href: authentication.md
- name: Авторизация
href: authorization.md
- name: Настройки безопасности по-умолчанию
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

важно определиться с названием этой фичи и везде консистентно его использовать: тут «по умолчанию», а если кликнуть в заголовке будет «встроенная»

задача со звёздочкой: желательно чтоб при использовании этого названия ещё не приходилось каждый раз кавычки рисовать

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Я бы унифицировал ко Встроенной настройке безопасности. Заметь, это не настройки (набор параметров), а настройка (как процесс налаживания/конфигурирования).

Называть это везде по текстам "настройка по умолчанию" -- слишком неточно и непонятно.

Кавычки со "встроенная" можно потерять, но здесь хочется второе-третье мнение.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Убрал кавычки со "Встроенная".

href: builtin-security.md
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
href: builtin-security.md
href: builtin.md

security уже есть в урле, второй раз его ни к чему добавлять

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Не согласен. Иерархия живёт и изменяется, документ живёт, не устоялось всё настолько, чтобы было можно надеяться на контекст. Но главное, что в словах builtin security главное слово всё-таки security, его нельзя потерять -- это как статью про "жаркое солнце" назвать "жаркое".

- name: Аудитный лог
href: audit-log.md
- name: Шифрование
Expand Down
Loading
Loading