Настройка Федерации

Общая информация

На схеме ниже представлено федеративное взаимодействие пользователей из разных тенантов Федерации:

Федерация — протокол взаимодействия тенантов. Является транспортом по доставке данных между тенантами. Отвечает за проверку:

Соответствия требованиям доверия (Трастов).
Прав пользователей на внешнюю коммуникацию.
Готовность сервисов к взаимодействию.
Обеспечивает надежность и безопасность передачи данных.

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

Инсталляция — независимые развернутые стенды разных организаций. Могут включать в себя несколько тенантов.

Траст — доверительное отношение между двумя и более тенантами. Могут быть сформированы:

Между тенантами в разных инсталляциях On-premises.
Между тенантами внутри одной инсталляции.
Тенант из On-premise инсталляции с тенантом в SaaS-версии продукта.

Особенности работы Федерации:

Звонки между федерациями могут быть только гостевые.
Общение между двумя инсталляциями осуществляется по протоколу gRPC + TLS. Эндпоинт для взаимодействия в общем виде выглядит так:
```
federation.<домен удаленной инсталляции>:443
```

Схема взаимодействия между инсталляциями A и B по протоколу mTLS:

Предварительные условия

Для настройки Федерации вам понадобится доступ к серверу Мессенджер и ВКС и доступ к Панели администратора VK WorkSpace по адресу https://biz.<ваш домен>.
Для корректной работы сервиса Федерация добавьте на серверы каждой инсталляции дополнительные вычислительные ресурсы:
- 10% от имеющихся мощностей vCPU.
- 1 ГБ SSD.
- 2 ГБ RAM на каждую тысячу федеративных пользователей. Ожидаемый прирост RAM — около 1 ГБ в год в зависимости от количества сообщений Федерации.
Проверьте, что у всех инсталляций Федерации есть доступ друг к другу. Например, проверьте, что запрос из Инсталляции А доходит до Инсталляции В:
```
curl -I federation.<домен Инсталляции В>
```
Если доступов нет, администраторам инсталляций необходимо запросить друг у друга адреса Federation Proxy и разрешить обращаться только по адресам federation.<домен инсталляции>:443.
Для включения mTLS на каждой инсталляции необходимо сформировать следующий набор артефактов:
- публичный сертификат СА — cacert.pem
- публичный сертификат сервера — server.cert.pem
- приватный (секретный) ключ сервера — server.key.pem
- публичный сертификат клиента — client.cert.pem
- приватный (секретный) ключ клиента — client.key.pem
Как создать сертификаты — см. в разделе ниже.

Для осуществления взаимодействия Инсталляция A должна передать публичный сертификат клиента и приватный ключ клиента Инсталляции B и наоборот.

Итого на Инсталляции A должен быть набор следующих файлов:
- публичный сертификат СА — server.cacert.pem
- публичный сертификат сервера — server.cert.pem
- приватный (секретный) ключ сервера — server.key.pem
- публичный сертификат клиента — client.cert.pem
- приватный(секретный) ключ клиента — client.key.pem
- публичный сертификат CA удаленной инсталляции, которым подписан клиент — client_B.cacert.pem
- публичный сертификат клиента от удаленной инсталляции — client_B.cert.pem
- приватный(секретный) ключ клиента от удаленной инсталляции — client_B.key.pem
Все сертификаты рекомендуется разместить в директории /opt/certs.
Начиная с версии Мессенджера 26.1 вы можете управлять доступами пользователей Федерации при помощи скрипта. Для этого необходимо наличие на компьютере интерпретатора языка Python версии 3.0 и выше и менеджера пакетов pip. Если версия вашей инсталляции ниже 26.1, пропустите этот шаг.

Шаг 1. Получите tenantID

Перейдите на машину, где развернута Панель администратора VK WorkSpace и проверьте, есть ли в системе tenantID:

sudo docker exec -it bizpostgres1 psql pdd_postgres -U postgres

Если tenantID есть, в выводе команды будет:

SELECT common_tenant.tid
FROM common_tenant
ORDER BY common_tenant.id ASC
LIMIT 1;

Если ответ пустой, сгенерируйте новый tenantID, последовательно выполнив команды:

sudo docker exec -it bizf1 bash
. env/bin/activate
./manage.py shell
from pdd.common.models import Tenant
t = Tenant(name='test') # в параметре name укажите название вашей инсталляции на ланитинце (на свое усмотрение)
t.save()
print(t.tid)

После команды print(t.tid) будет вывод tenantID. Сохраните это значение, оно понадобится вам ниже.

Получите у администратора удаленной инсталляции его tenantID. Он понадобится вам ниже.

Важно

Укажите в параметре name то же имя инсталляции, что и при создании сертификатов

Получение tenantID без доступа к Панели администратора

TenantID можно сгенерировать самостоятельно через кодирование домена в base58. Например, если нужно объединить домены example1.ru, example2.ru, example3.ru в один тенант:

Перейдите на сайт.
В поле Input введите короткое название тенанта (например, corpmail).
В поле Output отобразится tenantID (например, HdeYhnp4L8b). Длина tenantID не должна превышать 11 символов.

Шаг 2. Включите Kafka Kubernetes operator

В веб-интерфейсе установщика VK Workspace нажмите кнопку в правом верхнем углу и выберите Продукты → Мессенджер.
Включите переключатель Kafka Kubernetes operator.
Нажмите кнопку Сохранить.
Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
Выберите Kafka Kubernetes operator и распределите сервисы.
Запустите автоматическую установку, нажав на кнопку Play .

Шаг 3. Включите Федерацию

Перед включением убедитесь, что у вас есть доступ до удаленной инсталляции (см. предусловия).

В веб-интерфейсе установщика VK Workspace нажмите кнопку в правом верхнем углу и выберите Продукты → Мессенджер.
Включите переключатель для Федерации.
Нажмите кнопку Сохранить.
Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
Нажмите кнопку Добавить → Распределение продуктов Helm.
В открывшейся форме укажите Кластер K8s и Namespace для Федерации.
Нажмите кнопку Сохранить.
Запустите автоматическую установку, нажав на кнопку Play .

Настройка параметров Федерации

В веб-интерфейсе установщика VK Workspace перейдите в Проекты → vkteams.

В окне Формы проекта vkteams выберите Federation (Настройка федерации). Откроется форма с параметрами для заполнения:

Заполните параметры в соответствии с таблицей:

Параметр	Действие	Примечание
`Включить федерацию`	Включить переключатель	Включает сервисы Федерации
`Включить event manager`	Включить переключатель	Включает event manager для отображения признака федеративности чатов и пользователей
`grpc публичный серверный сертификат CA`	Указать сертификат	В формате PEM: `-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----`
`grpc серверный сертификат`	Указать сертификат	В формате PEM: `-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----`
`grpc приватный ключ серверного сертификата`	Указать ключ	В формате PEM: `-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----`
`Имя инсталляции`	Указать название	Название инсталляции на латинице

В разделе Инстансы федерации нажмите кнопку + Добавить и заполните поля для каждой удалённой инсталляции:

Параметр	Действие	Примечание
`Адрес удаленного стенда`	Указать адрес удаленного стенда в формате federation.<домен удаленной инсталляции>:443	При наведении на иконку ⓘ появляется подсказка с описанием параметра
`Публичный сертификат CA удалённой инсталляции, которым подписан клиент`	Указать сертификат	В формате PEM: `-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----`
`Имя удалённой инсталляции на латинице (cert_cn)`	Указать название	CN из клиентского сертификата
`Имя удалённой инсталляции на латинице (name)`	Указать название	Название удалённой инсталляции
`Публичный сертификат клиента от удалённой инсталляции`	Указать сертификат	В формате PEM: `-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----`
`Приватный (секретный) ключ клиента от удалённой инсталляции`	Указать ключ	В формате PEM: `-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----`
`tenantID удалённой инсталляции`	Получить у администратора удаленной инсталляции	При наведении на иконку ⓘ появляется подсказка с описанием параметра. Кнопка +Добавить позволяет добавлять несколько tenantID

В дополнительных настройках укажите:

Параметр	Действие	Примечание
`Локальный тенант`	Указать идентификатор локального tenantID из Шага 1	При наведении на иконку ⓘ появляется подсказка с описанием параметра
`message-send-api-enabled`	Включить переключатель	Включает новый метод для отправки сообщений
`Включить шифрование данных`	Включить переключатель	Включает взаимную аутентификацию по сертификатам (mTLS)

Перейдите на главную страницу веб-интерфейса установщика, нажав на логотип VK WorkSpace.
Запустите автоматическую установку, нажав на кнопку Play .

Шаг 4. Получите скрипт для управления пользователями

Скрипт используется в версии Мессенджера 26.1 и выше. Если версия вашей инсталляции ниже 26.1, перейдите к шагу 4.

Для использования скрипта необходимо наличие на компьютере интерпретатора языка Python версии 3.0 и выше и менеджера пакетов pip.

Скачайте и разархивируйте архив в любой удобной директории.

Перейдите в директорию и выполните команды:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Шаг 5. Добавьте пользователей в Федерацию

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

На обеих инсталляциях нужно:

Составить список пользователей, которым разрешено федеративное общение, и запустить команду, которая сформирует файл с белым списком.
Передать файл с белым списком в удаленную инсталляцию и получить такой же файл от удаленной инсталляции.
Загрузить файлы с белыми списками на каждой инсталляции.

Внимание

Эта процедура должна быть выполнена в всех инсталляциях, входящих в Федерацию. Без наличия белого списка со всех сторон и их загрузки в удалённой инсталляции — федеративная коммуникация будет невозможна.

1. Создайте файл с белым списком пользователей

Создайте файл whitelist.yaml и наполните его списком пользователей, которым разрешено федеративное взаимодействие с удаленной инсталляцией. Формат файла:
```
remoteTenant: HWqHczeM2P # tenantID удаленной инсталляции
users:
    "i.ivanov@company_domain":
    "n.belov@company_domain":
    "a.petrov@company_domain":
```
- remoteTenant — tenantID удаленной инсталляции, для которой выбранным пользователям разрешается общение.
- users — список пользователей. В конце email обязательно ставьте двоеточие. Email в этом случае — это ключ объекта, в котором потом могут быть дополнительные значения.
Создайте файл с белым списком remote_whitelist.yaml — на сервере Мессенджер и ВКС выполните команду.

Для версии Мессенджера 25.4 и ниже:
```
creeper federation whitelist --file=whitelist.yaml --outfile=remote_whitelist.yaml
```
где:
- whitelist — whitelist.yaml, описанный выше;
- outfile — remote_whitelist.yaml со списком fid'ов пользователей, который необходимо передать в удаленную инсталляцию инсталляцию.
Для версии Мессенджера 26.1 и выше:
```
python3 main.py --stentor-base-url stentor-fed1-el7.v3.im-sandbox.devmail.ru --whitelist ./example/whitelist.yaml --outfile remote_whitelist.yaml
```
где:
- stentor-base-url — имя хоста к api-stentor, как правило имеет вид stentor-<hostname>;
- aimsid — аутентификационный идентификатор для запросов к stentor-base-url;
- whitelist — whitelist.yaml, описанный выше;
- outfile — remote_whitelist.yaml со списком fid'ов пользователей, который необходимо передать в удаленную инсталляцию инсталляцию.
Команда создает файл remote_whitelist.yaml, где каждому пользователю присваивается федеративный идентификатор (fid). Файл имеет следующую структуру:
```
users:
    "i.ivanov@company_domain":
        fid: fid:0/HZnKEBoqDU/100401
    "n.belov@company_domain":
        fid: fid:0/HZnKEBoqDU/100402
    "a.petrov@company_domain":
        fid: fid:0/HZnKEBoqDU/100403
```
Передайте файл remote_whitelist.yaml в удаленную инсталляцию.
Передача файла в удаленную инсталляцию должна производиться безопасным способом

Возможные варианты передачи списков email для заведения белого списка:
- Файлы защищены паролем в письме или на физических носителях.
- Сжатые зашифрованные письма.
- Предоставление своего SFTP/FTPS.
- По ссылке с вводом логина и пароля.

2. Загрузите список пользователей от удаленной инсталляции

Получите файл remote_whitelist.yaml от удаленной инсталляции.
На сервере Мессенджер и ВКС добавьте полученный файл в любую директорию и выполните команду:
```
creeper federation whitelist --file=remote_whitelist.yaml
```

Как создать сертификаты

Сгенерированные сертификаты и ключи должны быть доступны на чтение/запись только для root-пользователя/сервисов Мессенджер и ВКС в рамках прав доступа файловой системы.

Выпустите CA сертификат и ключ, последовательно выполнив команды:
```
# mkdir /root/mtls
# mkdir /root/mtls/private
# mkdir /opt/certs
# openssl genrsa -out /root/mtls/private/cakey.pem 4096
# openssl req -new -x509 -days 3650 -key /root/mtls/private/cakey.pem -out /opt/certs/server.cacert.pem
```
Каждая инсталляция Федерации выпускает свой публичный сертификат CA.

Выпустите серверный сертификат и ключ:

[ req ]
distinguished_name  = req_distinguished_name

[v3_req]
subjectAltName = @alt_names

[alt_names]
DNS.1 = federation.domain.ru # хост локальной инсталляции

[ req_distinguished_name ]
C  = RU
ST = Moscow
L  = Moscow
O  = CompanyA
CN = <installation_А> # укажите имя локальной инсталляции на латинице

Перейдите в директорию с сертификатами /opt/certs и создайте приватный ключ:
```
# cd /opt/certs
# openssl genrsa -out server.key.pem 4096
```

Переподпишите с SNA:

# openssl req -new -nodes -out server.csr.pem -keyout server.key.pem -config /root/mtls/san.cnf -subj "/CN=<company_installation_name>"

Выпустите сертификат (подпишите у CA):

# openssl x509 -req -in server.csr.pem -CA server.cacert.pem -CAkey /root/mtls/private/cakey.pem  -CAcreateserial -out server.cert.pem -days 365 -extensions v3_req -extfile /root/mtls/san.cnf

Убедитесь, что в SAN-сертификате есть хост локальной инсталляции:
```
# openssl x509 -in server.cert.pem -noout -text | grep -A1 "Subject Alternative Name"   
```
Под каждую инсталляцию, с которой устанавливается соединение, выпустите клиентские ключ и сертификат. В CN и SAN добавьте информацию удаленной инсталляции (в которую будете передавать эти сертификаты). В конфигурации сервиса Fedproxy полю cert_cn для каждой инсталляции задайте значение соответственно CN клиентских сертификатов:
```
# openssl genrsa -out client.key.pem 4096
# openssl req -new -key client.key.pem -out client.csr.pem -subj "/CN=<имя удаленной инсталляции>"
# openssl x509 -req -in client.csr.pem -CA server.cacert.pem -CAkey /root/mtls/private/cakey.pem   -CAcreateserial -out client.cert.pem -days 365   -extfile <(echo "subjectAltName=DNS:<хост удаленной инсталляции>")
```
где <имя удаленной инсталляции> — значение параметра cert_cn конфигурационного файла federation.yml.

Пример команды:
```
# openssl genrsa -out client.key.pem 4096
# openssl req -new -key client.key.pem -out client.csr.pem -subj "/CN=installation_В"
# openssl x509 -req -in client.csr.pem -CA server.cacert.pem -CAkey /root/mtls/private/cakey.pem   -CAcreateserial -out client.cert.pem -days 365   -extfile <(echo "subjectAltName=DNS:federation.domain.ru")
```
Полученные сертификаты client.cert.pem, client.key.pem и server.cacert.pem (переименовав в client.cacert.pem) передайте в инсталляцию B.

Как управлять правами пользователей Федерации

Функциональность доступна для инсталляций версии 26.1 и выше.

Вы можете управлять правами пользователей на федеративное взаимодействие:

Выдать права — пользователь получает статус активности на федеративное взаимодействие в рамках траста/тенантов.
Изъять права:
- В локальном тенанте пользователь получает статус запрета на федеративное взаимодействие в рамках траста.
- Во все тенанты траста направляется информация об изъятии прав у пользователя на федеративное взаимодействие в рамках траста.
- Пользователь удаляется из всех федеративных чатов траста, но:
  - Если пользователь состоит в более чем одном трасте, то удаляются только те чаты, которые не подходят под активные трасты.
  - Личные чаты с федеративными пользователями, взаимодействие с которыми было доступно только в рамках данного траста, становятся доступны только для просмотра.
  - Групповые федеративные чаты траста, в котором были изъяты права, доступы только для просмотра и выхода из них.
Возобновить взаимодействие — пользователь получает статус активности на федеративное взаимодействие в рамках траста/тенантов.

Администратор инсталляции может управлять правами пользователей Федерации в своей инсталляции. Например, администратор инсталляции А может запретить пользователю инсталляции В Иванову писать пользователям инсталляции А. При этом у Иванова останется возможность взаимодействовать с пользователями других инсталляций Федерации — С и D.

Создайте файл whitelist.yaml, который содержит всех пользователей Федерации. Формат файла:
```
users:
    "test1@fed1-el7.v3.im-sandbox.devmail.ru":
        fid: fid:0/HZnKEBoqDU/100401
        action: init
    "test2@fed1-el7.v3.im-sandbox.devmail.ru":
        fid: fid:0/HZnKEBoqDU/100402
        action: allow
        tenant: Xasfda4F
    "test3@fed1-el7.v3.im-sandbox.devmail.ru":
        fid: fid:0/HZnKEBoqDU/100403
        action: deny
        tenant: Xasfda4F
```
где:
- action — принимает значение:
  - init — инициализировать (создать) федеративного пользователя.
  - allow — вернуть пользователю возможность осуществлять федеративное взаимодействие.
  - deny — запретить пользователю осуществлять федеративное взаимодействие.
- tenant — определяет тенант, для которого устанавливается действие. Если параметр не указан, то действие применяется ко всем тенантам. Параметр является обязательным, если значение action — deny или allow. Параметр является опциональным, если значение action — init .
Внимание

Email не может дублироваться, должен быть уникальным
1. Запустите скрипт для применения изменений:
```
python3 main.py --stentor-base-url stentor.myteaminternal --whitelist ./example/whitelist.yaml
```