
### Необходимые топики в  Kafka для базового кластера
  
| Название топика                      | Количество партиций (min) | Consumer Group |   Кем используется    |
| ------------------------------------ | :-----------------------: | :------------: | :-------------------: |
| `ZakromaNotification`                |             8             |    Zakroma     | Компонент Notfication |
| `ZakromaNotificationDeadLetterQueue` |             8             |    Zakroma     | Компонент Notfication |
| `ZakromaSecLog`                      |             8             |    Zakroma     |   Компонент Seclog    |
| `ZakromaSecLogDeadLetterQueue`       |             8             |    Zakroma     |   Компонент Seclog    |
| `ZakromaBackgroundCore`              |             8             |    Zakroma     |    Компонент Core     |
| `ZakromaWorker0`                     |             8             |    Zakroma     |   Компонент Worker    |
| `ZakromaWorker1`                     |             8             |    Zakroma     |   Компонент Worker    |
  

### Необходимые топики в Kafka для Мультикластера  
  
#### Первый кластер Kafka
  
| Название топика                          | Количество партиций (min) |  Consumer Group  |   Кто пишет    |   Кто читает   |
| ---------------------------------------- | :-----------------------: | :--------------: | :------------: | :------------: |
| `ZakromaNotification`                    |             8             |     Zakroma      | Первый кластер | Первый кластер |
| `ZakromaNotificationDeadLetterQueue`     |             8             |     Zakroma      | Первый кластер | Первый кластер |
| `ZakromaSecLog`                          |             8             |     Zakroma      | Первый кластер | Первый кластер |
| `ZakromaSecLogDeadLetterQueue`           |             8             |     Zakroma      | Первый кластер | Первый кластер |
| `ZakromaBackgroundCore`                  |             8             |     Zakroma      | Первый кластер | Первый кластер |
| `ZakromaWorker0`                         |             8             |     Zakroma      | Первый кластер | Первый кластер |
| `ZakromaWorker1`                         |             8             |     Zakroma      | Первый кластер | Первый кластер |
| `ZakromaStorageCluster-1`                |            16             | ZakromaCluster-2 | Первый кластер | Второй кластер |
| `ZakromaGatewayCluster-1`                |            16             | ZakromaCluster-2 | Первый кластер | Второй кластер |
| `ZakromaStorageDeadLetterQueueCluster-1` |            16             | ZakromaCluster-2 | Первый кластер | Второй кластер |
  
#### Второй кластер Kafka
  
| Название топика                          | Количество партиций (min) |  Consumer Group  |   Кто пишет    |   Кто читает   |
| ---------------------------------------- | :-----------------------: | :--------------: | :------------: | :------------: |
| `ZakromaNotification`                    |             8             |     Zakroma      | Второй кластер | Второй кластер |
| `ZakromaNotificationDeadLetterQueue`     |             8             |     Zakroma      | Второй кластер | Второй кластер |
| `ZakromaSecLog`                          |             8             |     Zakroma      | Второй кластер | Второй кластер |
| `ZakromaSecLogDeadLetterQueue`           |             8             |     Zakroma      | Второй кластер | Второй кластер |
| `ZakromaBackgroundCore`                  |             8             |     Zakroma      | Второй кластер | Второй кластер |
| `ZakromaWorker0`                         |             8             |     Zakroma      | Второй кластер | Второй кластер |
| `ZakromaWorker1`                         |             8             |     Zakroma      | Второй кластер | Второй кластер |
| `ZakromaStorageCluster-2`                |            16             | ZakromaCluster-1 | Второй кластер | Первый кластер |
| `ZakromaGatewayCluster-2`                |            16             | ZakromaCluster-1 | Второй кластер | Первый кластер |
| `ZakromaStorageDeadLetterQueueCluster-2` |            16             | ZakromaCluster-1 | Второй кластер | Первый кластер |
  

### Основные параметры Kafka  
  
| Параметр              | Значение                | Описание                                                                                                      |
| --------------------- |-------------------------| ------------------------------------------------------------------------------------------------------------- |
| `partitions`          | 8 / 16 (min)            | Параллелизм обработки. Чем больше партиций, тем выше нагрузка на Kafka и больше перерабатывающая способность. |
| `replication-factor`  | 2 (min)                 | Минимум два брокера осуществляют репликацию топиков для обеспечения отказоустойчивости.                       |
| `retention.ms`        | 259200000 (3 дня) (min) | Время хранения сообщений в топике.                                                                            |
| `cleanup.policy`      | delete                  | Политика очистки сообщений из топика                                                                          |
| `min.insync.replicas` | 2 (min)                 | Гарантия синхронной записи на указанный минимум реплик.                                                       |



Настройка Kafka

Настройка окружения


### Создать базу(ы) данных и схемы

1. Зайти под пользователем с админ. правами (по умолчанию - postgres):
```sh 
sudo su - postgres
```

2. Подключиться к базе через psql:
```sh 
psql -U postgres -d postgres
```
3. Выполнить SQL команды для создания пользователя и cхем. Заменить значение **zakroma_password** на своё:

```sql
-- Zakroma
CREATE USER zakroma_user LOGIN PASSWORD 'zakroma_password';
CREATE DATABASE zakroma WITH OWNER zakroma_user;
\c zakroma;
DROP SCHEMA public;
CREATE SCHEMA core AUTHORIZATION zakroma_user;
CREATE SCHEMA permission AUTHORIZATION zakroma_user;
CREATE SCHEMA seclog AUTHORIZATION zakroma_user;
CREATE SCHEMA notification AUTHORIZATION zakroma_user;
CREATE SCHEMA worker0 AUTHORIZATION zakroma_user;

```

4. Дополнительно необходимо создать extension в схеме `worker0` при версии postgres <13
``` sql
-- При устновке в разные БД
\c worker1

CREATE EXTENSION if not exists pgcrypto CASCADE;
```

``` sql
-- При устновке в разные схемы в рамках одной БД
\c zakroma

CREATE EXTENSION if not exists pgcrypto SCHEMA worker0;
```
5. После создания баз и схем выйти из учетной psql:
```sh
exit
```
Затем выйти из учетной записи postgres:
```sh
exit
```

Настройка PostgreSQL


## Обзор методов авторизации

Закрома.Хранение поддерживает несколько методов авторизации пользователей:

1. **file** - Базовая авторизация с локальными пользователями
2. **ldap** - Нативная LDAP авторизация без Keycloak
3. **keycloak** - Авторизация через Keycloak (с поддержкой LDAP)

### Метод авторизации: file (Базовый)

Используется для простых развертываний или тестирования. Пользователи и их пароли задаются непосредственно в конфигурации.

#### Настройка в конфигурации установки:
```yaml
auth:
  type: file

# Настройка локальных пользователей
users:
  - name: zakromaadmin
    password: zakromaadmin
    groups:
      - clouduser
  - name: user1
    password: password1
    groups:
      - group1
  - name: user2
    password: password2
    groups:
      - group2
```

#### Особенности:
- Простота настройки и управления
- Подходит для небольших развертываний
- Пароли хранятся в конфигурации (рекомендуется использовать хеширование)
- Пользователи назначаются в группы для управления доступом

### Метод авторизации: ldap (Нативный LDAP)

Используется для прямой интеграции с LDAP-каталогом без промежуточного Keycloak. Подходит для организаций, которые хотят использовать существующую LDAP-инфраструктуру напрямую.

#### Настройка в конфигурации установки:
```yaml
auth:
  type: ldap

# Настройка подключения к LDAP
ldap:
  # URL для подключения к LDAP серверу
  url: "ldap://10.10.0.10:389"
  # DN пользователя для подключения к LDAP серверу
  bind_dn: "CN=Administrator,CN=Users,DC=zakroma,DC=local"
  # Пароль пользователя для подключения к LDAP серверу
  bind_password: "SuperStrongPass1234!"
  # Фильтр для поиска пользователей по LDAP классам
  user_filter: "(objectClass=person)"
  # Фильтр для поиска пользователей по вхождению в LDAP группы
  group_filter: "(objectClass=group)"
  # Атрибут для поиска группы
  group_name_attribute: "cn"
  # Путь в LDAP дереве, с которого начинать поиск групп
  group_search_dn: "ou=groups,dc=zakroma,dc=local"
  # Атрибут имени пользователя
  user_name_attribute: "sAMAccountName"
  # Путь в LDAP дереве, с которого начинать поиск пользователей
  user_search_dn: "CN=Users,DC=zakroma,DC=local"
  # Атрибут, отвечающий за имя пользователя
  user_firstname_attribute: "givenName"
  # Атрибут, отвечающий за фамилию пользователя
  user_lastname_attribute: "sn"
  # Атрибут, отвечающий за email пользователя
  user_email_attribute: "mail"
  # Атрибут, в котором хранится список членств пользователя
  membership_attribute_name: "member"
  # Тип атрибута, определяющего членство пользователя
  membership_attribute_type: "dn"
```

#### Особенности:
- Прямая интеграция с LDAP без промежуточных компонентов
- Поддержка Active Directory и OpenLDAP
- Гибкая настройка атрибутов и фильтров
- Подходит для корпоративных развертываний с существующей LDAP-инфраструктурой

### Метод авторизации: keycloak

Используется для интеграции с Keycloak, который может работать как с внутренними пользователями, так и с LDAP-каталогами. Keycloak предоставляет дополнительные возможности управления пользователями, ролями и группами.

#### Варианты настройки Keycloak:
1. **LDAP с ролями** - синхронизация групп LDAP с ролями Keycloak
2. **Внутренние пользователи** - управление пользователями внутри Keycloak
3. **LDAP с группами** - прямая синхронизация групп LDAP без создания ролей

## Настройка на версии keycloak  >= 19.X.X

1. Заходим консоль администрирования keycloak.
Выбираем существующий или создаём новый realm. 
2. Необходимо создать нового клиента. Переходим в Clients, в открывшимся окне нажимаем create и создаем нового Client ID с именем zakroma В новом окне настройки меняем:
        - `Client authentication: On`
        - `Authorization: On`
        - `Direct Access Grants` Для Keycloak 26.1 и выше

3. Настраиваем сервисный аккаунт
**Clients -> Zakroma -> Service Account Roles**.  
Нажать `Assign role` -> Выбрать `admin` -> `Assign`

4. Настраиваем маппинг для пользователей
**Clients -> Zakroma -> Сlient Scopes -> zakroma-dedicated** . 
**Add mapper -> By configuraton -> User Attribute**.
        - `Mapper Type: User Attribute`     
        - `Name: username-mapper`
        - `User Attribute: username`
        - `Token Claim Name: username`
        - `Claim JSON Type: String`
        - `Add to access token: ON`   

4. `Realm Settings -> Keys` копируем kid и pyblic_key ключа с алгоритмом RS256 в настройки установки zakroma. 

5. `Clients -> zakroma -> Credentials` копируем clientSecret в настройки установки zakroma. 

6. Увеличим время жизни токена. Переходим на вкладки слева `Realm Settings -> Tokens`. Проставим следующее значение:
	
	- `Access Token Lifespan: 10 minute`
  

7. Настройка реестра пользователей

> [!info] Для тестов без LDAP
> Для тестового использования возможно использовать внутренний реестр пользователей keycloak, без интеграции с ldap.

<button tabpanelId="test" tabId="ldap-tab" isActive="true"> LDAP </button>
<button tabpanelId="test" tabId="keycloak-tab"> Keycloak inner </button>
<button tabpanelId="test" tabId="keycloak-groups-tab"> Keycloak Groups </button>
<details tabpanelId="test" tabId="ldap-tab" isActive="true">
   <summary></summary>

#### Используется при хранении пользователей в LDAP-каталоге

#### На вкладке User Federation -> Add new provider -> ldap 
--------------

Далее заполняем значения (на примере OpenLdap):

	- `Vendor: other #other если используется OpenLdap и Active Directory если Active Directory`
	- `Connection URL: ldap://openldap.openldap.svc.cluster.local:389`
	- `Bind Type: simple`
	- `Bind DN: cn=admin,dc=demo,dc=zakroma,dc=ru`
	- `Bind Credential: xxx`
	- `Edit Mode: UNSYNCED`
	- `Users DN: ou=users,dc=demo,dc=zakroma,dc=ru`
	- `Username LDAP attribute: cn`
	- `RDN LDAP attribute: cn`
	- `UUID LDAP attribute: cn`
	- `User Object Classes: person, organizationalPerson`


и нажимаем <kbd>Save</kbd>. 

#### Далее создаём маппер из Ldap в Keycloak: Mappers -> Add mapper
--------------
Создаем mapper c именем role-mapper c типом `role-ldap-mapper`.
Общая суть сводится к синхронизации групп AD с ролями пользователей в keycloak. Пример настроек:
	- `LDAP Roles DN: ou=groups,dc=demo,dc=zakroma,dc=ru`
	- `Role Name LDAP Attribute: cn`
	- `Role Object Classes: groupOfUniqueNames`
	- `Membership LDAP Attribute: uniqueMember`
	- `Membership Attribute Type: DN`
	- `Membership User LDAP Attribute: uid`
	- `Mode: LDAP_ONLY`
	- `User Role Retrieve Strategy: LOAD_ROLES_BY_MEMBER_ATTRIBUTE`
	- `Member-Of LDAP Attribute: memberOf`
	- `ClientID: zakroma`


#### Создаём ещё один mapper c именем username-mapper c типом `user-attribute-ldap-mapper`:
--------------
	- `User Model Attribute: username`
	- `LDAP Attribute: uid`


####  Синхронизируем пользователей.
--------------
Возвращаемся к настройкам на вкладке `User Federation -> ldap -> settings` и жмем на синхронизацию всех пользователей, тут должны увидеть что пользователи были добавлены. 

####  В необходимых настройках Zakroma необходимо выставить значение свойства userRoleName в то название роли, в которая присутствует у всех нужных пользователей. Т.е. только пользователи с данной ролью смогут пользоваться системой Zakroma.

</details>

<details tabpanelId="test" tabId="keycloak-tab">
<summary></summary>

#### Используется для тестирования, либо нестандартной конфигурации

#### Создаём роли: Clients -> Zakroma -> Roles
--------------
По кнопке `Create role` добавить роль:
        - `clouduser`
   
#### Создаём пользователей в Keycloak: Users -> Add user
--------------
```
Username: zakromaadmin
First name: Admin
Last name: Zakroma
```

#### Задаём пароль: Users -> zakromaadmin -> Credentials -> Set password
--------------
        - `Temporary: off`

#### Назначаем роль: User -> zakromaadmin -> Role mapping -> Assign Role
--------------
Переключить в режим Filter by Clients  -> в поиске написать "zakroma"
        - `clouduser`      

</details>

<details tabpanelId="test" tabId="keycloak-groups-tab">
<summary></summary>

#### Используется при хранении пользователей в LDAP-каталоге с авторизацией через группы

Этот вариант настройки позволяет использовать группы LDAP для авторизации без создания ролей в Keycloak. Пользователи авторизуются на основе принадлежности к определенным группам в LDAP.

#### На вкладке User Federation -> Add new provider -> ldap 
--------------

Далее заполняем значения (на примере OpenLdap):

	- `Vendor: other #other если используется OpenLdap и Active Directory если Active Directory`
	- `Connection URL: ldap://openldap.openldap.svc.cluster.local:389`
	- `Bind Type: simple`
	- `Bind DN: cn=admin,dc=demo,dc=zakroma,dc=ru`
	- `Bind Credential: xxx`
	- `Edit Mode: UNSYNCED`
	- `Users DN: ou=users,dc=demo,dc=zakroma,dc=ru`
	- `Username LDAP attribute: cn`
	- `RDN LDAP attribute: cn`
	- `UUID LDAP attribute: cn`
	- `User Object Classes: person, organizationalPerson`

и нажимаем <kbd>Save</kbd>. 

#### Создаём маппер групп из LDAP в Keycloak: Mappers -> Add mapper
--------------
Создаем mapper c именем group-mapper c типом `group-ldap-mapper`.
Этот маппер синхронизирует группы LDAP с группами Keycloak. Пример настроек:
	- `LDAP Groups DN: ou=groups,dc=demo,dc=zakroma,dc=ru`
	- `Group Name LDAP Attribute: cn`
	- `Group Object Classes: groupOfUniqueNames`
	- `Membership LDAP Attribute: uniqueMember`
	- `Membership Attribute Type: DN`
	- `Membership User LDAP Attribute: uid`
	- `Mode: LDAP_ONLY`
	- `User Groups Retrieve Strategy: LOAD_GROUPS_BY_MEMBER_ATTRIBUTE`
	- `Member-Of LDAP Attribute: memberOf`
	- `Mapped Group Attributes: cn`
	- `Drop non-existing groups during sync: ON`

#### Создаём(если не существует) маппер атрибутов пользователя c именем username-mapper c типом `user-attribute-ldap-mapper`:
--------------
	- `User Model Attribute: username`
	- `LDAP Attribute: uid`

#### Синхронизируем пользователей и групп
--------------
Возвращаемся к настройкам на вкладке `User Federation -> ldap -> settings` и выполняем синхронизацию:
1. Жмем `Sync all users` - синхронизируем всех пользователей
2. Переходим в `Mappers -> group-mapper -> Sync LDAP Groups to Keycloak` - синхронизируем группы

#### Настройка Закрома.Хранение для работы с группами
--------------
Для изменения стратегии синхрониации пользоватей на конфигурацию с группами необходимо поменять переменную sync_strategy и установить корневую группу для синхронизации, как показано ниже: 

	- `sync_strategy: "groups"`
	- `user_group: "zakroma-users-group"` - название группы в keycloak, и в ldap соответственно.
	- `default_admin: "zakromaadmin"` - Имя пользователя в группе zakroma-users-group , который будет назначен администратором платформы.
    

Только пользователи, входящие в указанную группу, смогут пользоваться системой Zakroma.

</details>