Дополнительные настройки для web-клиента¶

В этом разделе указаны опциональные настройки, которые задействуются в web-клиенте. Если web-клиент не используется или перечисленная ниже функциональность не требуется, то вы можете пропустить этот раздел.

Список особенностей web-клиента и его отличие от desktop-клиента доступен в документе Особенности и ограничения Web-клиента

Предпросмотр файлов¶

Описание¶

В карточках web клиента есть возможность предпросмотра приложенных файлов (т.е. просмотреть содержимое файла без его сохранения на диск). Предпросмотр для некоторых видов файлов работает без дополнительных настроек, например:

текстовые файлы - txt,
изображения - png, jpeg и др.,
web страницы - html и др.,
pdf файлы (для работы предпросмотра pdf файлов необходимо убедиться, что соответствующая настройка включена в конфигурационном файле app.json: "PreviewPdfEnabled": *true*).

Предпросмотр файлов с расширением tiff выполняется с помощью преобразования данного файла (плагином сервиса Chronos) в pdf и последующим отображением его в web клиенте.

Предпросмотр для офисных видов файлов (doc, docx, xls, xlsx, ppt, pptx, rtf и др.) работает посредством конвертации их в pdf через LibreOffice/OpenOffice и просмотре при помощи pdf.js.

При этом на сервере хранится кэш файлов, которые были сконвертированы для предпросмотра. При повторной попытке предпросмотра того же файла любым пользователем - сразу отображается уже сконвертированный pdf файл. Если файл был изменен (т.е. создана новая версия), то конвертация будет выполняться заново. Более подробно кэш файлов описан в руководстве администратора.

Note

Конвертация файлов в pdf для предпросмотра может использоваться не только в web-клиенте, но и в толстом клиенте при выставлении соответствующей настройки в карточке настроек сервера (см. Руководство администратора).

Настройка предпросмотра файлов¶

Для предпросмотра файлов необходимо установить и настроить веб-сервис Jinni (см. Руководство по установке Jinni);

Note

Если используется Р7-Офис/OnlyOffice, то файлы офисных форматов и PDF будут отображаться в предпросмотре через него (см. Настройка и установка Р7-Офис/OnlyOffice).

Important

Конвертация выполняется плагином FileConverterPlugin сервиса Chronos. Chronos в свою очередь отправляет запрос на конвертацию к веб-сервису Jinni, который выполняет обработку запросов в порядке очереди в однопоточном режиме. Большое количество одновременных запросов на конвертацию может вызывать длительную задержку на обработку операций по конвертации файлов. Кроме того, если Chronos и Jinni не разнесены на разные серверы, то это может создать существенную нагрузку на сервер приложений. Чтобы снять эту нагрузку с сервера приложений и ускорить обработку большого количества запросов на конвертацию файлов, рекомендуется дополнительно развернуть веб-сервис(-ы) Jinni на отдельном(-ых) сервере(-ах) для параллельной обработки запросов.

Note

В рамках проектного решения можно переопределить механизм конвертации в pdf, например, на использование SharePoint Word Authomation Services. Для этого нужно написать расширение, в котором переопределить класс Tessa.Extensions.Default.Chronos.FileConverters.PdfFileConverterWorker (исходный код класса входит в типовое решение, т.е. открыт для изучения и изменения. В комментариях в коде описано, что класс делает и как его переопределить). Это расширение должно быть добавлено в Chronos.

Настройка и установка Р7-Офис / OnlyOffice.¶

Для просмотра, предпросмотра и редактирования документов может использоваться Р7-Офис / OnlyOffice. Он устанавливается на сервер приложений, либо на отдельный сервер. Для установки нужно воспользоваться Инструкцией по установке. Затем в карточке настроек Р7-Офис / OnlyOffice указать адрес подключения к api сервера документов.

Адрес должен быть следующим: https://documentserver:port/web-apps/apps/api/documents/api.js, где:

documentserver - адрес сервера,
port - порт, по которому сервер доступен.

Note

Если порт при установке не был указан, то его можно изменить в файле ds.conf (для Р7 он находится по адресу C:\Program Files\R7-Office\DocumentServer-IE\nginx\conf).

Адрес, настроенный в карточке, должен быть доступен с компьютеров пользователей, т.е. это должен быть не localhost, а актуальный адрес сервера. Чтобы соответствовать политикам браузера CORS, адрес веб-клиента и адрес сервера документов должны быть доступны по одному доменному имени. Например, адрес веб-клиента https://tessa-pc/tessa/web соответствует имени tessa-pc, следовательно, сервер документов должен быть также по адресу https://tessa-pc:port/. Протокол у сервера документов должен быть настроен как https, причём используемый сертификат должен быть валиден для адреса сервера. Для примера экспортируем самоподписанный сертификат для нашего сервера с именем tessa-pc (укажем любой пароль). В IIS это можно сделать в разделе “Сертификаты сервера”. Укажите имя файла tessa.pfx или замените его в командах ниже.

Теперь установите утилиту openssl (на Windows 10 и Windows 11 можно воспользоваться WSL), перейдите в папку, в которую выгружен сертификат, и выполните в командной строке:

openssl pkcs12 -in ./tessa.pfx -clcerts -nokeys -out tessa.crt

openssl pkcs12 -in ./tessa.pfx -nocerts -nodes -out tessa.key

После ввода каждой команды потребуется ввести указанный выше пароль и нажать [Enter]. Теперь откройте файл nginx\conf\ds.conf в подпапке с установленным Р7-Офис. Например, это C:\Program Files\R7-Office\DocumentServer-IE\nginx\conf\ds.conf. Замените его содержимое на следующее:

include includes/http-common.conf;
server {
  listen 0.0.0.0:32113 ssl;
  listen [::]:32113 ssl default_server;
  server_tokens off;

  ssl on;
  ssl_certificate           "C:/Tessa/tessa.crt";
  ssl_certificate_key       "C:/Tessa/tessa.key";

  ssl_session_cache  builtin:1000  shared:SSL:10m;
  ssl_protocols TLSv1.2;
  ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4;
  ssl_prefer_server_ciphers on;

  include includes/ds-*.conf;
}

Здесь:

32113 - номер порта, по которому будет прослушиваться трафик для сервера документов, этот же номер указывается в карточке настроек “Р7-Офис / OnlyOffice”;
ssl_certificate "C:/Tessa/tessa.crt" - путь к файлу сертификата;
ssl_certificate_key "C:/Tessa/tessa.key" - путь к файлу ключа сертификата.

Замените папку и имена файлов при необходимости. Теперь перезапустите службу Windows с именем “Р7-Офис. Сервер документов Proxy Service”. Служба будет запущена без сообщений об ошибках, если вы корректно настроили файл и сертификаты выше. При наличии ошибок перепроверьте их. Откройте в браузере ссылку, указанную в карточке настроек. Должен отобразиться текст скрипта. В примере это адрес: https://tessa-pc:32113/web-apps/apps/api/documents/api.js Убедитесь, что при выделении сертификата (слева от адресной строки) браузер показывает, что он корректный (даже если соединение отмечено как незащищённое, что может быть из-за того, что сертификат самоподписанный).

Для указанного порта (в примере это 32113) также потребуется добавить правило в брандмауэр, разрешающее входящий трафик TCP для этого порта.

Далее нужно обновить страницу браузера, на которой запущен Легкий клиент. После этого в контекстном меню файла появятся новые пункты: “Открыть для чтения в браузере”, “Редактировать в браузере”. А также, при наличии прав на добавление файлов, новое меню в файловом контроле - “Создать файл”. Предпросмотр файлов офисных форматов, а также файлов формата PDF будет происходить средствами Р7-Офис / OnlyOffice.

Important

В настройках конфигурационого файла (для Р7-Офис он находится по адресу C:\Program Files\R7-Office\DocumentServer-IE\config\default.json) есть параметр savetimeoutdelay. Этот параметр определяет задержку перед тем, как сервер документов Р7-Офис / OnlyOffice отправит информацию по изменениям к веб-сервису TESSA. Его наличие делает процесс обработки документа после сохранения более длительным, и его рекомендуется отключить, т.е. поставить значение "savetimeoutdelay": 0. Также, если в процессе открытия или предпросмотра файла появилась ошибка “Загрузка не удалась”, то нужно проверить логи офиса. Они в папке установки (например, C:\Program Files\R7-Office\DocumentServer-IE) в подпапке Log\converter. Если в файлах out***.log есть сообщения вида "unable to verify the first certificate", то проблема в недействительном сертификате, который установлен на сервере приложений TESSA. Обычно это происходит, если сертификат является самоподписанным и используется на тестовой инсталляции. В файле default.json, описанном выше, замените "rejectUnauthorized": true на "rejectUnauthorized": false, чтобы отключить проверку. После сохранения настроек перезапустите службы офиса.

При использовании Легкого клиента в Firefox, во время работы с Р7-Офис может появиться ошибка “Редактор Р7-Офис / OnlyOffice не может быть загружен. Проверьте, что адрес API-скрипта в карточке настроек Р7-Офис / OnlyOffice корректен и доступен, а также ничего не блокирует его работу”. В таком случае нужно перейти по адресу подключения к api сервера документов (в примере выше это https://tessa-pc:32113/web-apps/apps/api/documents/api.js) и на предупреждение браузера о вероятной угрозе безопасности нажать “Дополнительно” и далее “Принять риск и продолжить”:

Установка с использованием Docker¶

Для запуска сервера Р7 в Docker нужно выполнить одну из команд ниже. Сервисы и ресурсы Р7 будут доступны по https.

Запуск в режиме без поддержки JWT (JWT_ENABLED=false):

sudo docker run -i -t -p 32113:443 --add-host=tessa-pc:host-gateway --restart=always  \
-v C:/Tessa/default.json:/etc/r7-office/documentserver/default.json  \
-v C:/Tessa/ds.conf.tmpl:/etc/r7-office/documentserver/nginx/ds.conf.tmpl  \
-v C:/Tessa/tessa.crt:/etc/r7-office/documentserver/nginx/tessa.crt  \
-v C:/Tessa/tessa.key:/etc/r7-office/documentserver/nginx/tessa.key \
-e JWT_ENABLED=false   r7office/documentserver-ee:2024.1.1.375

Запуск с поддержкой JWT, и установленным секретом (JWT_SECRET=...), который нужно указать и в карточке настроек Р7-Офис / OnlyOffice:

sudo docker run -i -t -p 32113:443 --add-host=tessa-pc:host-gateway --restart=always  \
-v C:/Tessa/default.json:/etc/r7-office/documentserver/default.json  \
-v C:/Tessa/ds.conf.tmpl:/etc/r7-office/documentserver/nginx/ds.conf.tmpl  \
-v C:/Tessa/tessa.crt:/etc/r7-office/documentserver/nginx/tessa.crt  \
-v C:/Tessa/tessa.key:/etc/r7-office/documentserver/nginx/tessa.key \
-e JWT_SECRET=QROJ8ouPvovYNpwIZsSBThDmCrOMI8k1   r7office/documentserver-ee:2024.1.1.375

Здесь:

32113 - номер порта, по которому будет прослушиваться трафик для сервера документов, этот же номер указывается в карточке настроек “Р7-Офис / OnlyOffice”;
tessa-pc - доменное имя сервера;
C:/Tessa/tessa.crt - путь к файлу сертификата;
C:/Tessa/tessa.key - путь к файлу ключа сертификата.
C:/Tessa/default.json - путь к файлу конфига Р7. Пример файла;
C:/Tessa/ds.conf.tmpl - путь к файлу конфига внутреннего nginx. Пример файла.

ЭП - электронная подпись¶

В web-клиенте есть возможность использовать ЭП для подписания файлов. По умолчанию данный функционал отключен.

Настройка ЭП¶

Для настройки ЭП в web-клиенте необходимо выполнить следующие действия:

В конфигурационном файле app.json (который расположен по пути C:\inetpub\wwwroot\tessa) включить плагин: "CryptoProPluginEnabled": true,
Установить КриптоПро ЭП Browser plug-in. Описание плагина, а также ссылка для его скачивания на странице https://www.cryptopro.ru/products/cades/plugin/.

Проверка работы ЭП¶

После выполнения указанных выше настроек в web-клиенте в карточке документа для приложенных файлов появится пункт меню “Подписать”:

При нажатии на него откроется окно для выбора ключа, которым необходимо подписать данный файл:

После успешного подписания файла около него появится дополнительный значок:

Проверка подписей также выполняется с помощью меню на файле:

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

Зеленый – целостность подписи верна, сертификат проверен и подтвержден доверенным сертификатом.
Красный – целостность подпись не верна.
Голубой – целостность подписи верна, сертификат не удалось проверить до доверенного.

Настройка Windows аутентификации¶

Note

Автоматическая Windows аутентификация в Web клиенте доступна только для десктопных версий Яндекс.Браузер, Chrome и Firefox на платформе Windows.

Note

Описание механизма работы аутентификации пользователей в платформе TESSA можно найти в Руководстве Администратора.

Настройка серверной части, используя средства IIS (только на платформе Windows)¶

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

В IIS создать пул приложений (в этом примере с именем “tessawin”) с параметрами, аналогичными основному пулу приложений (указать “Без управляемого кода” в выпадающем списке)
Выбрать созданный пул, нажать пункт “Дополнительные параметры” в контекстном меню, и указать ту же учётную запись, которая указывалась для основного пула. Если в настройках основного пула указана встроенная учётная запись ApplicationPoolIdentity, то её необходимо поменять на явно заданную учётную запись, которая у обоих пулов должна быть одинаковой (ApplicationPoolIdentity соответствует разным учётным записям для каждого пула). Не указывайте более одного рабочего процесса для этого пула приложений, независимо от количества процессов для основного пула приложений.
В IIS в папке сайты → Default Web Site → tessa создать новое приложение:

Укажите псевдоним, например, tw_winauth. Пул приложений - созданный выше “tessawin”. И физический путь (путь к приложению) установите такой же, как у серверной части -C:\inetpub\wwwroot\tessa\web:
Для созданного приложения в разделе “Проверка подлинности” включить Проверка подлинности Windows, остальные - отключить (обычно анонимная аутентификация по умолчанию включена, её необходимо отключить).
В конфигурационном файле C:\inetpub\wwwroot\tessa\web\web.config убедиться, что включена Windows аутентификация (параметр forwardWindowsAuthToken):

<aspNetCore processPath=".\Tessa.Web.Server.exe" arguments="" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" forwardWindowsAuthToken="true" requestTimeout="00:10:00" startupTimeLimit="3600" hostingModel="InProcess">

Note

Остальные параметры данной строки описаны в статье, однако менять их не рекомендуется.
В конфигурационном файле C:\inetpub\wwwroot\tessa\app.json включить параметр "WinAuth" (удалить служебные символы // перед параметром).
- В параметре "WinAuthIsEnabled" укажите true.
- В параметре "WinAuth" необходимо указать путь к точке с windows аутентификацией: "tessa/tw_winauth", где tessa - путь к папке в IIS.
- В параметре "GuyFawkesAuth" – путь к точке с приложением и анонимной аутентификацией: "tessa/web".
- По умолчанию указан параметр "WinAutoLogin": true, включающий автоматический вход с windows аутентификацией. Если автоматический вход не выполнен, то отображается обычное окно входа с сообщением. Если вход выполнен, но требуется ввести другие логин/пароль, то пользователь может выполнить выход из учётной записи, что переведёт его на окно входа с возможностью ввести любые логин/пароль или нажать кнопку “Вход Windows”. Если автоматический вход необходимо выключить для всех пользователей, то укажите значение false для этого параметра.

Note

Путь к приложениям необходимо указывать в формате название сайта или папки / название приложения.

Теперь необходимо перезапустить оба пула приложений.

Настройка серверной части, используя модуль Kerberos аутентификации в платформе TESSA (работает на Windows и Linux платформах)¶

Для настройки возможности Windows аутентификации на Linux необходимо выполнить следующие действия:

Note

Проверьте наличие keytab файла по пути /etc/krb5.keytab. Если файл существует и сервер приложений введён в домен, то переходите к пункту 3. Если сервер введён в домен, но отсутствует keytab файл, то переходите к пункту 2, иначе начинайте настройку с пункта 1.

Введите сервер на Linux платформе в домен (если этого не было сделано ранее).
1. Установите realmd с помощью команды yum install или apt-get. Например: yum install sssd realmd oddjob oddjob-mkhomedir adcli samba-common samba-common-tools krb5-workstation openldap-clients policycoreutils-python -y
2. Измените DNS сервер на сервер домена (если это требуется), редактируя файл resolv.conf. Например: sudo nano /etc/resolv.conf.
3. Введите в домен с помощью команды realm join --user=Administrator DOMAIN.LOCAL, где Administrator имя пользователя с возможностью ввода в домен, а DOMAIN.LOCAL - название домена.
4. Проверьте с помощью команды realm list успешность входа.
5. Файл по пути /etc/krb5.keytab сохраните и переходите к пункту 3. Действия в пункте 2 не требуются.
Сгенерируйте keytab файл (если сервер был введен ранее в домен, но keytab файл не сохранился, или не был выполнен пункт 1):
1. Добавьте сервер (если это не было сделано ранее), к примеру, HOST-LINUX в домен с помощью команды dsadd. Пример: dsadd computer "CN=HOST-LINUX,CN=Computers,DC=DOMAIN,DC=LOCAL"
2. Свяжите сервер (если это не было сделано ранее) и имя субъекта-службы (Service Principal Name, далее SPN) с помощью команды ktpass. Пример: ktpass /mapuser DC\HOST-LINUX /princ HTTP/HOST-LINUX@DOMAIN.LOCAL /pass Master1234 /ptype KRB5_NT_SRV_HST /crypto all /mapop set /out c:\temp\web.keytab +answer где через /pass указывается пароль, который будет установлен для учетной записи TessaUser, а /out - указание папки экспорта
  
  Note
  
  Если ваш сервер доступен в сети под несколькими DNS именами (они же SPN), то следует воспользоваться командой ktpass с дополнительными аргументами. Например: ktpass /mapuser DC\HOST-LINUX /princ HTTP/HOST-LINUX2@DOMAIN.LOCAL /pass Master1234 -setpass /kvno 2 /ptype KRB5_NT_SRV_HST /crypto all /mapop set /in c:\temp\web.keytab /out c:\temp\web2.keytab -setupn. Обратите внимание на параметр /kvno равный 2. В случае, если при генерации нового keytab файла он увеличится, то предыдущие keytab файлы перестанут действовать. Поэтому используется параметр -setpass отключающий изменение пароля. Проверить уровень kvno можно двумя последовательно введенными командами: ldifde -d "CN=HOST-LINUX,CN=Computers,DC=DOMAIN,DC=LOCAL" -l "userPrincipalName,servicePrincipalName,msDS-KeyVersionNumber" -f c:\temp\account.ldif и type c:\temp\account.ldif. Kvno это атрибут msDS-KeyVersionNumber.
3. Проверьте связь имени субъекта-службы (SPN) и сервера с помощью команды setspn. Пример: setspn -L DC\HOST-LINUX
Полученный keytab файл поместите в папку tessa, где находится файл лицензии, к примеру, /home/tessa/tessa/web
В файле app.json включите настройку Kerberos.Enabled. Так же для работы аутентификации по указанному логину и паролю включите LDAP аутентификацию.
Установите настройку "Kerberos.DisableRealmCheck": true, если требуется отключить проверку соответствия имен домена. Оставьте значение по умолчанию false, если ваша доменная архитектура это позволяет.

Пример настройки:

"LDAP": {
    "Enabled": true,
    "UseSsl": true,
    "EnforceTls12": true,
    "Url": "DOMAIN.LOCAL",
    "Port": null,
    "TimeoutMilliseconds": null,
    "BindDn": "DC\\TessaUser",
    "BindCredentials": "Master1234",
    "SearchBase": "dc=domain,dc=local",
    "SearchFilter": "(&(objectClass=person)(sAMAccountName={0}))"
},

Параметры GuyFawkesAuth (путь до веб-приложения в IIS) и WinAuth (путь до веб-приложения в IIS для аутентификации в web-клиенте) оставьте пустыми. Пример настройки:
```
"Kerberos.Enabled": true,
"Kerberos.Keytab": "*.keytab",
"Kerberos.DisableRealmCheck": false,

"GuyFawkesAuth": "",
"WinAuthIsEnabled": true,
"WinAuth": "",
"WinAutoLogin": true,
```
Добавьте DNS запись уровня А (если это не было сделано ранее):
1. Откройте DNS Manager с помощью команды dnsmgmt.msc.
2. Раскройте узел Forward Lookup Zones.
3. Кликните на домене правой кнопкой мыши и выберете New Host (A or AAAA)....
4. Введите информацию об имени хоста целевой машины и ее IP-адрес в сети (более подробно см. Руководство по установке СЭД TESSA на Linux).

Настройка браузера¶

Настройка браузера Яндекс.Браузер и Chrome:

Запустите Панель управления - Свойства обозревателя. На вкладке “Безопасность” для зоны Надежные узлы в разделе “Уровень безопасности” нажмите на кнопку “Другой”:

Прокрутите список, чтобы для параметра “Проверка подлинности пользователя” выставить Автоматический вход в сеть с текущим именем пользователя:

Далее необходимо сервер добавить в надежные узлы:

В открывшемся окне прописываем имя сервера TESSA:
Настройка браузера Firefox:

В адресной строке браузера введите about:config. Далее в поле поиска введите network.automatic. Дважды кликните на параметре network.automatic-ntlm-auth.trusted-uris:

В открывшемся окне пропишите имя сервера TESSA:

Проверка работы Windows аутентификации¶

Откройте адрес в браузере https://SERVER_NAME/tessa/web и проверьте - должно открыться окно логина, где также есть кнопка Win Login:

Нажав на кнопку Win Login, произойдет автоматическая аутентификация в Web клиенте TESSA под текущей учетной записью пользователя.

Note

В TESSA в карточке сотрудника должен быть указан тип входа в систему - Пользователь Windows, а в поле “Аккаунт” - корректная учетная запись.

SAML и ADFS¶

Web-клиент поддерживает аутентификацию, основанную на стандарте SAML 2.0. В частности, этот способ аутентификации можно использовать для интеграции с ADFS (Active Directory Federation Services).

Для работы SAML необходимы два сертификата: сертификат identity provider (idp.pem, его вам должен выдать провайдер SAML/ADFS) и service provider (sp.pfx, это ваш сертификат, его необходимо сгенерировать самостоятельно). Эти сертификаты обычно размещаются в одной папке с конфигурационным файлом web-приложения app.json, в котором и задаются настройки SAML.

Чтобы включить аутентификацию через SAML, требуется настроить приложение через файл конфигурации app.json. Все настройки находятся в отдельном блоке “SAML”.

Параметр	Описание
`SignIn`	Включает и отключает аутентификацию через SAML
`SiteURL`	URL приложения
`SPEntityID`	Уникальный id приложения для service provider
`SingleSign`	URL для запроса аутентификации
`SingleLogout`	URL для запроса логаута
`LogoutBinding`	Тип привязки для запроса логаута. Допустимые значения: `Post`, `Redirect`
`NameIDPolicy`	Настройки ограничений идентификатора имени пользователя в SAML. См. спецификацию SAML 2.0. В качестве значения может быть указан `null`
`IDPCert`	Путь до сертификата identity provider. Для IDCert, SPCert действуют обычные правила указания путей в app.json. Если файлы сертификатов расположены в той же папке, что и app.json, используйте префикс ‘@’, чтобы имя файла выглядело так: ‘@certname.pem’
`SPCert`	Путь до сертификата service provider
`SPCertPass`	Пароль для сертификата service provider
`SignAlgorithm`	Криптоалгоритм
`CertificateValidationMode`	Метод проверки сертификата
`RevocationMode`	Метод проверки сертификата
`CreateUserAfterAuthenticationIfNotExists`	Если флаг установлен в true, то при успешной SAML-аутентификации система автоматически создает пользователя, если его нет в системе. В карточке сотрудника заполняются поля: “Имя”, “E-mail”, “Логин”. Для дополнения карточки перед сохранением можно написать серверное расширение на сохранение карточки сотрудника (подробнее описано в руководстве разработчика Web-клиента)
`AddNewUserToRoles`	Перечисленные через запятую идентификаторы статических/динамических ролей, в которые система при создании автоматически включит пользователя. Например, ‘7ff52dc0-ff6a-4c9d-ba25-b562c370004d’ - это идентификатор динамической роли ‘Все сотрудники’
`LoginClaimType`	Идентификатор XML-атрибута логина сотрудника в ответном сообщении от identity provider. По умолчанию равен http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
`NameClaimType`	Идентификатор XML-атрибута имени сотрудника в ответном сообщении от identity provider. По умолчанию равен http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
`EmailClaimType`	Идентификатор XML-атрибута электронной почты сотрудника в ответном сообщении от identity provider. По умолчанию равен http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
`SetSAMLCookie`	Если флажок установлен, то после успешной аутентификации будут установлены cookies для быстрой повторной аутентификации на сервере авторизации
`ExpireTimeSpan`	Продолжительность действия cookies для SAML-аутентификации. По умолчанию равно 24 часа
`SlidingExpiration`	При установленном флажке будет использоваться скользящий срок действия cookies для SAML-аутентификации. Это значит, что по истечении половины срока, заданного параметром `ExpireTimeSpan`, при обращении к web-серверу cookies для SAML-аутентификации будут заменены на новые с тем же сроком действия
`UpdateEmailLoginUsers`	При установленном флажке аутентификация происходит по следующему алгоритму: если по login-параметру сотрудник не найден, то пытаемся найти его по email-параметру в поле “Логин” карточки сотрудника. Если сотрудник с указанным email найден, то обновляем его логин в карточке на актуальный

После настройки метаданные будут доступны по адресу %SiteURL%/SAML/Metadata. При типовой установке это адрес вида https://your_server_name.ru/tessa/web/SAML/Metadata. Обращаем ваше внимание, что регистр символов важен!

Note

Если CertificateValidationMode отличен от “None”, то необходимо добавить сертификат identity provider (idp.pem) в доверенные сертификаты на сервере приложений.

Note

SPEntityID - уникальный id приложения должен быть зарегистрирован в SAML-сервисе. SAML-провайдеру отправляется SPEntityID и ссылка на метаданные, которые доступны по адресу %SiteURL%/SAML/Metadata

При включенной аутентификации SAML окно логина будет с одной кнопкой Login.

Note

В TESSA в карточке сотрудника должен быть указан тип входа в систему - Пользователь Windows или Пользователь LDAP, а в поле “Аккаунт” - учетная запись или уникальный идентификатор пользователя. При использовании ADFS сопоставление сотрудника в TESSA и сотрудника из сервиса происходит по email сотрудника. Поэтому в карточке сотрудника должен быть указан актуальный email.

Note

При использовании в качестве провайдера аутентификации сервиса Keycloak и некоторых других не допускается применять самоподписанные сертификаты SSL в веб-сервере TESSA.

OAuth и OpenID Connect¶

Web-клиент поддерживает аутентификацию с помощью внешних провайдеров, работающих по протоколу OAuth 2.0 или OpenID Connect (OIDC) - расширение для протокола OAuth.

Настройка конфигурации¶

Для того чтобы включить аутентификацию через OAuth, требуется настроить файл конфигурации app-oauth.json.

Параметр объекта OAuth:
```
"Enabled": false
```
Включает и отключает аутентификацию по протоколам OAuth и OIDC.
Параметр объекта OAuth:
```
"UpdateEmailLoginUsers": false
```
Если для флага установлено значение true и сотрудник в системе не был найден по полю Аккаунт, но был найден по полю E-mail, то значение для поля Аккаунт будет установлено равным значению из поля E-mail.
Параметр объекта OAuth:
```
"CreateUserAfterAuthenticationIfNotExists": false
```
Если для флага установлено значение true, то при успешной OAuth-аутентификации система автоматически создаст пользователя, если он отсутствует в системе. При этом в карточке сотрудника будут заполнены следующие поля: Фамилия, Имя, Отчество, Полное имя, Краткое имя, Дата рождения, Телефон, Мобильный телефон, Домашний телефон, E-mail, Аккаунт (совпадает с полем E-mail). Можно написать серверное расширение на сохранение карточки сотрудника для заполнения других полей или изменения уже заполненных полей (подробнее описано в руководстве разработчика web-клиента). Подробнее об инициализации полей в карточке сотрудника см. раздел Сопоставление полей карточки и утверждений.

Note

Утверждения, из которых будут браться значения для заполнения полей новой карточки сотрудника, можно настроить в параметре "Claims".

Note

Для новых сотрудников будет установлен тип входа Пользователь Windows.
Параметр объекта OAuth:
```
"AddNewUserToRoles": [ "7ff52dc0-ff6a-4c9d-ba25-b562c370004d" ]
```
Перечисление идентификаторов ролей (кроме контекстных) через запятую, в которые система включит пользователя автоматически при его создании. Например, по умолчанию указан идентификатор динамической роли Все сотрудники.

Note

Используется, если для параметра "CreateUserAfterAuthenticationIfNotExists" установлено значение true.
Параметр объекта OAuth:
```
"Providers": [ ]
```
Список доступных внешних провайдеров для внешней аутентификации посредством OAuth или OIDC. По умолчанию используются провайдеры Google, Yandex и VKontakte.

Note

В окне входа в систему провайдеры отображаются в порядке согласно их порядку в конфигурационном файле.
Параметр массива объектов Providers:
```
"Name": "Provider"
```
Уникальное название провайдера. По совместительству является схемой внешней аутентификации.
Параметр массива объектов Providers:
```
"Icon": "provider.png"
```
Опциональный параметр, который задаёт относительный путь до иконки провайдера, отображаемой в окне входа в систему. Например, "/icons/provider.png" или "provider.png".

Tip

Иконки провайдеров должны размещаться в папке веб-сервиса по пути web/wwwroot/images/oauth.

Note

Если значение не задано, то вместо иконки отображается заголовок из параметра "Caption".
Параметр массива объектов Providers:
```
"Caption": {
    "en": "Login with Provider",
    "ru": "Войти с Provider"
}
```
Опциональный параметр, который задаёт заголовок провайдера, отображаемый в окне входа в систему. Значение может включать в себя несколько культур, при этом язык определяется в зависимости от языка пользовательского агента (браузера). Если язык пользовательского агента не удалось определить или он отсутствует в наборе допустимых значений, то по умолчанию будет использоваться английский язык ("en").

Note

Если параметры "Caption" и "Icon" не заданы, то в качестве заголовка используется значение из параметра "Name".
Параметр массива объектов Providers:
```
"UsePkce": false
```
Опциональный параметр, который включает или отключает использование стандарта “Ключ проверки для обмена кодом” (PKCE).

Note

При использовании OIDC значение параметра будет применено только в том случае, если для параметра "ResponseType" задано значение "Code". Подробнее см. RFC 7636.
Параметр массива объектов Providers:
```
"UseOpenIdConnect": false
```
Опциональный параметр, который включает или отключает использование протокола OIDC. Данный параметр определяет, какой из проколов будет использован для внешней аутентификации. Если параметр задан и имеет значение true, то будет использоваться протокол OIDC, в противном случае будет использоваться протокол OAuth.

Important

Некоторые параметры обязательны для одного протокола и игнорируются для другого протокола. Подробнее о том, какой параметр для какого протокола используется, приводится в описании этого параметра.
Параметр массива объектов Providers:
```
"GetClaimsFromUserInfoEndpoint": false
```
Опциональный параметр, который используется только для OIDC и определяет необходимость обращения обработчика к конечной точке, содержащей информацию о пользователе, для получения дополнительных утверждений.

Note

Так как получение дополнительных утверждений возможно только после создания удостоверения на основе идентификационного токена, то значение параметра будет учтено, если для параметра "ResponseType" задано значение "id_token".
Параметр массива объектов Providers:
```
"ResponseType": "code id_token token"
```
Опциональный параметр, который используется только для OIDC и определяет процесс обработки авторизации, а также набор токенов и параметров, получаемых от конечной точки авторизации пользователя внешним провайдером. Список доступных значений и их возможных комбинаций перечислены в OpenIdConnectResponseType.
Параметр массива объектов Providers:
```
"ResponseMode": "form_post"
```
Опциональный параметр, который используется только для OIDC и определяет, как сервер авторизации возвращает параметры результата от конечной точки авторизации. Список доступных значений и их возможных комбинаций перечислены в OpenIdConnectResponseMode.
Параметр массива объектов Providers:
```
"Authority": "https://provider.ru"
```
Опциональный параметр, который используется и является обязательным только для OIDC и определяет общедоступную конечную точку, которая обслуживает документ конфигурации OIDC.
Параметр массива объектов Providers:
```
"Prompt": "none"
```
Опциональный параметр, который используется только для OIDC и определяет набор строковых значений, указывающих, запрашивает ли сервер авторизации конечного пользователя повторную аутентификацию и согласие. Список доступных значений и их возможных комбинаций перечислены в Спецификации OpenID Connect.
Параметр массива объектов Providers:
```
"AuthorizationEndpoint": "https://provider.ru/autrhorize"
```
Опциональный параметр, который используется и является обязательным только для OAuth и определяет общедоступную конечную точку, которая начинает процесс авторизации. Она получает запрос от пользователя с разрешением на доступ к ресурсам, после чего перенаправляет пользователя на страницу, где он может авторизовать или отклонить запрос на предоставление доступа к ресурсам от приложения.
Параметр массива объектов Providers:
```
"TokenEndpoint": "https://provider.ru/token"
```
Опциональный параметр, который используется и является обязательным только для OAuth и определяет общедоступную конечную точку, которая используется для получения токенов, которые предоставляют приложению доступ к данным пользователя. После того как пользователь подтвердил запрос на авторизацию, приложение отправляет запрос на получение токена. Если запрос был выполнен успешно, приложение получает токен, который может быть использован для доступа к данным пользователя.
Параметр массива объектов Providers:
```
"UserInformationEndpoint": "https://provider.ru/userinfo"
```
Опциональный параметр, который используется и является обязательным только для OAuth и определяет общедоступную конечную точку, которая возвращает информацию о пользователе. Она может включать имя пользователя, адрес электронной почты, идентификатор пользователя и другие данные, которые могут быть полезны для приложения.
Параметр массива объектов Providers:
```
"ClientId": "x1e20p33qwt58"
```
Уникальный идентификатор клиента, который используется для идентификации приложения при обращении к протоколам OAuth или OIDC. Для получения идентификатора приложения, его необходимо зарегистрировать у провайдера, поддерживающего OAuth или OIDC, например, на сайте Yandex. При регистрации необходимо будет предоставить некоторую информацию о приложении: название, описание, URI перенаправления, тип приложения и другие необходимые данные.

Important

По умолчанию, в качестве URI перенаправления используется адрес /oauth/callback.
Параметр массива объектов Providers:
```
"ClientSecret": "78rg5vw017jwx"
```
Секретный ключ клиента, который используется для защиты запросов, отправляемых к внешним провайдерам. Ключ должен храниться в секрете и не должен раскрываться никому, включая пользователям приложения. Ключ будет выдан вместе с "ClientId" при регистрации приложения у внешнего провайдера.
Параметр массива объектов Providers:
```
"Scopes": [ "openid", "profile", "email" ]
```
Набор уровней доступа к ресурсам пользователя, которые запрашивает приложение при аутентификации. Например, приложение может запросить доступ к профилю пользователя, его электронной почте, контактам и другим данным.

Note

При использовании OIDC будет запрошен стандартный набор уровней доступа [ "openid", "profile", "email" ], поэтому параметр можно опустить.
Параметр массива объектов Providers:
```
"Claims": {
    "id": "login",
    "avatar": "picture",
    "last_name": "family_name"
}
```
Набор утверждений, которые описывают права и разрешения приложения на доступ к ресурсам пользователя. В системе используется фиксированный набор утверждений (см. раздел Сопоставление полей карточки и утверждений), на основе которого заполняются поля карточки пользователя при её создании (см. параметр "CreateUserAfterAuthenticationIfNotExists"). Так как не все провайдеры предоставляют одинаковый набор утверждений, то используются параметры для сопоставления утверждений. Например, "from": "to", где "from" - утверждение провайдера, а "to" - утверждение, используемое в платформе.

Note

При использовании протокола OAuth, по умолчанию, выполняется сохранение всех утверждений провайдера и добавляются утверждения, заданные в параметрах сопоставления.

При использовании протокола OIDC, по умолчанию, выполняется сохранение только тех утверждений провайдера, которые определены стандартом OIDC, а также утверждения, заданные в параметрах сопоставления.

Проверка аутентификации¶

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

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

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

После успешной внешней аутентификации произойдёт вход в систему TESSA и перенаправление на необходимую страницу.

Note

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

Алгоритм поиска и создания сотрудника¶

После успешной аутентификации с помощью внешнего провайдера система пытается получить утверждение email для электронной почты пользователя.
- Если утверждение не было найдено, то процесс прекращается и возвращается ошибка.
- Если утверждение было найдено, то выполняется поиск сотрудника в системе по полю Аккаунт, которое совпадает с утверждением email без учёта регистра.
  - Если сотрудник был найден, то для него открывается сессия и выполняется вход в систему.
  - Если сотрудник не был найден, то выполняется поиск сотрудника в системе по полю E-mail, которое совпадает с утверждением email без учёта регистра.
    - Если было найдено более одного сотрудника с заданным адресом электронной почты, то процесс прекращается и возвращается ошибка.
    - Если сотрудник не был найден и признак "CreateUserAfterAuthenticationIfNotExists" не установлен, то процесс прекращается и возвращается ошибка.
    - Если сотрудник не был найден и признак "CreateUserAfterAuthenticationIfNotExists" установлен, то сотрудник создаётся в системе, для него открывается сессия и выполняется вход в систему.
    - Если был найден один сотрудник и признак "UpdateEmailLoginUsers" не установлен, то процесс прекращается и возвращается ошибка.
    - Если был найден один сотрудник и признак "UpdateEmailLoginUsers" установлен, то для поля Аккаунт в карточке сотрудника устанавливается значение из поля E-mail и выполняется вход в систему.

Сопоставление полей карточки и утверждений¶

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

Поле карточки	Утверждение
LastName	family_name, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
FirstName	given_name, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
MiddleName	middle_name
FullName	name, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
ShortName	nickname
BirthDate	birthdate, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth
MobilePhone	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone
HomePhone	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/homephone
Phone	phone_number, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/otherphone
Email	email, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddres
Login	email, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddres

Первое утверждение в столбце Утверждение является приоритетным. Если оно не задано или его значение является пустым, то используется второе и последующие утверждения.

Если для поля FullName не найдено ни одного из утверждений или значения всех утверждений пусты, то используется значение из поля ShortName.

Если для поля FirstName не найдено ни одного из утверждений или значения всех утверждений пусты, то используется значение из поля FullName.

Если для поля Phone не найдено ни одного из утверждений или значения всех утверждений пусты, то используется первое непустое значение из полей MobilePhone и HomePhone.

Установка Deski¶

Deski - это приложение-ассистент, позволяющее пользователям web-клиента работать с файлами (например, открывать на редактирование), не скачивая их в браузере.

Deski кэширует файлы в папке пользователя в зашифрованном виде и выполняет функцию экономии трафика, позволяя не скачивать файлы с сервера, если они уже доступны локально.

Используется AES-256 шифрование. Deski создаёт свой ключ, который хранится в его локальных файлах. Ключ создается на основании мастер-ключа. Мастер-ключ ротируется каждые 10 дней (можно изменить в настройке CipherKeyRotationInterval в app.json веб-сервиса) и не хранится локально, а имеется только у Deski в памяти. Мастер ключи индивидуальны для сотрудника (они хранятся в БД), Deski получает последние два актуальных ключа от сервера и использует их для шифрования и расшифровки собственных ключей, хранящихся локально в зашифрованном виде. Затем эти свои ключи шифруют и расшифровывают контент. Расшифровать клиент может то, что зашифровано текущим или предыдущим мастер-ключом (20 дней).

В архиве со сборкой, в папке DeskiSetup в подпапках расположены инсталляторы для разных операционных систем. Все инсталляторы автоматически публикуются при установке конфигурации, далее пользователи могут самостоятельно скачать и установить данное приложение (более подробно в Руководстве пользователя), правами администратора при этом пользователям обладать не надо.

Note

Если конфигурация была установлена вручную без задействования скриптов или же автоматическая публикация по каким-то причинам не прошла, то опубликовать Deski можно вручную (см. Руководство администратора).

По умолчанию приложение устанавливается в папку профиля пользователя LocalAppData, оттуда же и запускается.

Tip

По установке Deski на ОС Linux обратитесь к разделу Установка ассистента web-клиента Deski.

Установка TESSA Assistant¶

TESSA Assistant - это приложение-ассистент для мобильных устройств, позволяющее пользователям web-клиента в мобильных браузерах осуществлять просмотр, подписание и проверку подписи файла.

TESSA Assistant кэширует файлы внутри приложения в зашифрованном виде, и выполняет функцию экономии трафика, позволяя не скачивать файлы с сервера, если они уже доступны локально.

Данное мобильное приложение доступно в Google Play и App Store.

TESSA Assistant для подписания использует ключевые носители Рутокен ЭЦП (более подробно на сайте производителя) и локальное хранилище ключей СКЗИ “КриптоПро CSP”.

Note

Если в процессе подключения ключевого носителя Рутокен ЭЦП возникли проблемы с их обнаружением на ОС Android, то попробуйте выполнить действия указанные на странице производителя.

Note

На платформе iOS на устройствах iPad для работы с ключевыми носителями Рутокен ЭЦП через технологию NFC дополнительно требуется установить мобильное приложение “Рутокен VCR” на связанное устройство iPhone XR или новее. Данным приложением можно пользоваться бесплатно первый 7 дней. Далее потребуется приобрести лицензию на каждое устройство, на котором будет установлено приложение и с помощью которого будут подписываться документы на iPad.

Warning

Для работы модуля необходима лицензия, включающая модуль “Приложение-ассистент для мобильных устройств”.

Warning

Для возможности подписания файла с помощью СКЗИ “КриптоПро CSP” версии 5.0 требуется лицензия на право использования СКЗИ “КриптоПро CSP” версии 5.0 на одном рабочем месте. При первой установке приложения активируется временная лицензия на 3 месяца.

Основные настройки¶

Для работы модуля необходимо включить галочку "Использовать приложение-ассистент для мобильных устройств" в настройках сервера и перезапустить легкий клиент.

Note

Если кнопка "Использовать приложение-ассистент для мобильных устройств" заблокирована, то необходимо перепроверить наличие лицензии на модуль "Приложение-ассистент для мобильных устройств".

Описание механизма¶

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

Note

Для шифрования используется симметричный алгоритм блочного шифрования AES-256.

Создание доверенного сертификата¶

Здесь будет показано, как создать доверенный сертификат для вашего сервера приложений.

Для настройки параметров сертификатов используются следующие файлы конфигураций:

localhost.cnf. Настройки сертификата для сервера приложений. В файле нужно добавить доменные имена и/или IP для приложений (DNS.1, DNS.2 и т.д., IP.1, IP.2 и т.д.). Также в секции [ dn ] можно настроить название сертификата.
root_create.cnf. Настройки создания корневого сертификата. В секции [ req_dn ] можно настроить название сертификата. Корневой сертификат по умолчанию будет создан на 10 лет, что можно изменить в параметре default_days.
root_sign.cnf. Настройки создания сертификата для сервера приложений. Сертификат по умолчанию будет создан на 1 год, что можно изменить в параметре default_days.
Создайте пустой файл index. В него будут добавлены ссылки на все созданные сертификаты.
Создайте пустой файл serial.txt. Запишите в него шестнадцетиричное, как мининум двухначное число, например 01 - это будет серийный номер следующего выпущенного сертификата.

Выполните следующие команды. В итоге будут созданы сертификаты rootCA.pfx (его надо добавить в корневые доверенные в оснастке Сертификаты на всех машинах, с которых будет осуществляться доступ к серверу приложений), localhost.pfx (его надо добавить в настройки IIS).

Создание ключа для корневого сертификата

openssl ecparam -out rootCA.key -name prime256v1 -genkey

Создание запроса на корневой сертификат

openssl req -new -key rootCA.key -out rootCA.req -nodes -config root_create.cnf

Создание самоподписанного корневого сертификата

openssl ca -out rootCA.pem -keyfile rootCA.key -selfsign -config root_create.cnf  -in rootCA.req

(Опционально) Посмотреть созданный сертификат

openssl x509 -noout -text -in rootCA.pem

Создание ключа для сервера приложений

openssl ecparam -out localhost.key -name prime256v1 -genkey

Создание запроса на сертификат для сервера приложений

openssl req -new -sha256 -key localhost.key -out localhost.csr -config .\localhost.cnf

Создание сертификата сервера приложений

openssl ca -in localhost.csr  -cert rootCA.pem -keyfile rootCA.key -out localhost.pem -config root_sign.cnf

Создание pfx-файлов

openssl pkcs12 -inkey rootCA.key -in rootCA.pem -export -out rootCA.pfx
openssl pkcs12 -inkey localhost.key -in localhost.pem -export -out localhost.pfx