Общие сведения
Данная инструкция применима к любой ОС Linux, обладающей следующими характеристиками:
- Имеется systemd.
- Отсутствует файрволл либо корректно настроены его компоненты (SElinux и т.д.).
- Имеется возможность использования прокси-сервера (к примеру – Nginx) для обеспечения HTTPS/TLS.
Под компонентами Avanpost FAM Mobile Services понимаются два компонента:
- API Service, предоставляющий API для мобильных приложений сотрудников;
- Push Service, выполняющий роль брокера сообщений для доставки push-сообщений.
Типовая схема размещения компонентов Avanpost FAM Mobile Services с применением DMZ выглядит следующим образом:
Другие варианты развёртывания описаны в описании архитектуры компонента Avanpost FAM Mobile Services.
Установка и настройка
Установка файлов компонентов Avanpost FAM Mobile Services
Работы по установке компонентов Avanpost FAM Mobile Services выполняются на подготовленном сервере с ОС Linux.
Шаги для установки:
- Получить архив Avanpost.Mobile.Push.Service.*.tar.gz версии, соответствующей версии компонента Avanpost FAM Server.
- Распаковать файлы архива Avanpost.Mobile.Push.Service.*.tar.gz на предназначенном для этого сервере в DMZ в каталог /opt/push_gateway_service.
Настройка компонента Avanpost FAM Server
В конфигурационном файле на узле, на котором развёрнут Avanpost FAM Server, требуется проверить наличие параметра backgroundTasks в значении true в конфигурационном файле config.toml (начиная с версии FAM v1.8.7.346 меняется конфигурационный файл с config.json на config.toml).
Настройка компонента Push Service
Работы по настройке компонента Push Service выполняются на подготовленном сервере в DMZ, предназначенном для размещения компонентов Avanpost FAM Mobile Services.
В случае отсутствия DMZ возможно размещение компонента на сервере, на котором размещён компонент Avanpost FAM Server. В этом случае потребуется открыть с сервера с Avanpost FAM Server сетевой доступ через интернет до Google API-адресов, перечисленных ниже.
Для корректной работы Push Service и механизма push-уведомлений требуется сетевой доступ через интернет с сервера, на котором будет размещён компонент Push Service, до адресов:
https://fcm.googleapis.com
https://firestore.googleapis.com
https://oauth2.googleapis.com
https://www.googleapis.com
https://oauth-login.cloud.huawei.com
https://push-api.cloud.huawei.com
Поэтому перед выполнением настройки необходимо убедиться, что эти сетевые адреса доступны через интернет с сервера, на котором размещается Push Service.
Шаги по настройке:
- Используя любой текстовый редактор, отредактировать файл с настройками. При желании можно использовать любой текстовый редактор, доступный в системе, в данном примере работа ведется на основе использования редактора vi.
sudo vi /etc/systemd/system/pushgwsrv.service
2. Указать актуальные значения параметров:
- --addr – IP-адрес или хост, на котором требуется открытие сетевого порта для получения сетевых запросов от сервера Avanpost FAM; например – 0.0.1;
- --port – порт, к которому будет подключаться Avanpost FAM Server; по умолчанию – 4222
3. Указать в поле User пользователя, который будет запускать сервис.
[Unit] Description=Avanpost FAM Mobile Services Push [Service] WorkingDirectory=/opt/push_gateway_server ExecStart=/opt/push_gateway_server/push_gateway_server -addr 10.10.181.96 -port 4222 Restart=always RestartSec=10 SyslogIdentifier=pushgwsrv User=idp [Install] WantedBy=multi-user.target
4. Перезапустить службы:
sudo systemctl daemon-reload sudo systemctl restart pushgwsrv
По результатам выполненной настройки компонента API Service следует зафиксировать параметры, которые потребуются на следующем шаге:
- addr:port Push Service.
Установка и настройка компонента API Service
Работы по установке компонента API Service выполняются на подготовленном сервере, предназначенном для размещения компонентов Avanpost FAM Mobile Services.
В случае отсутствия DMZ возможно отказаться от использования компонента API Service и использовать стандартный API-интерфейс, предоставляемый Avanpost FAM Server. Следует учитывать, что в этом случае могут возникнуть риски, связанные с прямой публикацией в интернет HTTP/HTTPS-интерфейсов Avanpost FAM Server.
Шаги по выполнению настройки:
- Используя любой текстовый редактор, отредактировать файл с настройками. При желании можно использовать любой текстовый редактор, доступный в системе, в данном примере работа ведется на основе использования редактора vi.
sudo vi /etc/systemd/system/authproxy.service
Указать актуальные значения параметров:
- --baddr и --bport – указав соответственно адрес и порт внутреннего сетевого интерфейса, к которому будет обращаться компонент Avanpost FAM Server (или экземпляры компонента Avanpost FAM Server в случае использования кластеризованной схемы развёртывания); IP-адрес (в примере ниже указан как 127.0.0.1) по умолчанию не определён и должен быть заменён на актуальное значение, порт по умолчанию – 9999;
- --faddr и --fport – указав соответственно адрес и порт внешнего сетевого интерфейса, к которому будут обращаться через интернет мобильные приложения Avanpost Authenticator; IP-адрес (в примере ниже указан как 127.0.0.1) по умолчанию не определён и должен быть заменён на актуальное значение, порт по умолчанию – 8888;
- --token – секретный токен, который далее должен быть указан на стороне компонента Avanpost FAM Server; значение токена в примере (tokenvalue12345678) должно быть заменено на любое актуальное значение.
Важно
В токене не должно содержаться кириллических символов, а также спецсимволов (~ . .. / # ? * [ ] ; & < > | ! $). Сам токен следует обрамлять одинарными кавычками в качестве дополнительной защиты (экранирование символов от использования их в качестве параметров командной строки).
2. Указать в поле User пользователя, который будет запускать сервис:
[Unit] Description=Avanpost FAM Mobile Services API [Service] WorkingDirectory=/opt/authenticator_proxy ExecStart=/opt/authenticator_proxy/authenticator_proxy --baddr 127.0.0.1 --bport 9999 --faddr 127.0.0.1 --fport 8888 --token 111111111 Restart=always RestartSec=10 SyslogIdentifier=authproxy User=idp [Install] WantedBy=multi-user.target
3. Перезапустить службы:
systemctl daemon-reload systemctl enable authproxy systemctl start authproxy
Если требуется выполнить публикацию внутреннего сетевого интерфейса компонента API Service (определяемого параметрами addr:port компонента API Service) и внешнего сетевого интерфейса компонента API Service (определяемого параметрами faddr:fport компонента API Service) с применением TLS/HTTPS, то необходимо использовать любой веб-сервер с поддержкой требуемого уровня TLS, например, Nginx.
Avanpost FAM Server для взаимодействия с API Service использует механизм HTTP Long Polling с таймаутом в 30 секунд. Поэтому при использовании прокси-серверов, веб-серверов или межсетевых экранов между Avanpost FAM Server и API Service следует разрешить использование таймаутов для HTTP-запросов не менее 30 секунд.
По результатам выполненной настройки компонента API Service следует зафиксировать значения параметров, которые потребуются на следующем шаге:
- baddr:bport API Service;
- faddr:fport API Service;
- token API Service.
Настройка на стороне Avanpost FAM Server
Перед выполнением настройки следует убедиться, что с сервера Avanpost FAM доступен порт:
- addr:port Push Service;
- baddr:bport API Service.
Перейти в административную консоль, Сервис/Настройки методов аутентификации, после чего создать метод аутентификации, указав следующие параметры:
- Добавить метод аутентификации:
- Название – указать произвольное название, например, «Avanpost Authenticator» или «мобильный аутентификатор»;
- Фактор аутентификации – выбрать Avanpost Authenticator;
- Метод активен – если метод единственный, то активировать.
- На следующем шаге указать параметры работы метода аутентификации:
- Ключ-тэг – указать любой уникальный удобный идентификатор, состоящий из букв латинского алфавита и цифр; будет фигурировать в журналах;
- Метод активен – флаг включен;
- Сервис push-уведомлений включен – если компонент API Service развёрнут и планируется к применению, то установить значение
true
; - Таймаут ожидания подтверждения через push-уведомление (в секундах) – можно оставить значение по умолчанию;
- Адрес сервиса push-уведомлений – установлено значение параметра addr:port Push Service;
- Внешний URL-aдрес – если компонент API Service развёрнут без последующего проксирования через внешний сетевой интерфейс, то установить значение параметра faddr:fport API Service; если компонент не развёрнут, то установить значение параметра base_url из основного конфигурационного файла компонента Avanpost FAM Server config.toml (начиная с версии FAM v1.8.7.346 меняется конфигурационный файл с config.json на config.toml);
- Токен для подключения к API-сервису – установлено значение параметра token API Service. Значение параметра token обязательно для заполнения и должно быть равно значению, указанному ранее для параметра token для запуска компонента API Service.
После создания и включения метода аутентификации требуется подождать от нескольких секунд до 1 минуты для выполнения автоматического перезапуска обработчиков. Сервер системы Avanpost FAM самостоятельно считает новые параметры и выполнит переподключение. После этого механизм push-уведомлений будет доступен и будет функционировать.
Важно
При настройке в разделе "Контактная информация" поля данных не должны быть пустыми, их следует заполнить во избежание появления ошибки.
Проверка установки и настройки
На сервере с Avanpost FAM Server выполнить проверку подключения компонента Avanpost FAM Server к Push Service и API Service:
journalctl -ru fam
В журнале должны содержаться сообщения "External (firebase) store for tempcodes checked successful" и "Start long-polling avanpost authenticator proxy":
{"level":"debug","time":"2022-06-16T13:11:14+03:00","message":"Run reverse proxy server"} {"level":"debug","time":"2022-06-16T13:11:14+03:00","message":"SSO server start..."} <16> 1 2022-06-16T13:11:14+03:00 192.168.0.83 - SERVCTL [command="/opt/idp/fam" user_os="idp"] Service IDP started {"level":"debug","factor":"avanpost authenticator","time":"2022-06-16T13:11:14+03:00","message":"External (firebase) store for tempcodes checked successful..."} {"level":"debug","time":"2022-06-16T13:11:14+03:00","message":"Start long-polling avanpost authenticator proxy..."}
На стороне пользовательского сценария включить для любого из приложений метод аутентификации Avanpost Authenticator.
Приложение А. Примеры настроенных конфигураций Avanpost Mobile Services через административную консоль
Пример конфигурации №1. Установлены и настроены компоненты Push Service и API Service
Пример конфигурации №2. Установлен и подключен Push Service без API Service
Приложение Б. Настройка параметров через конфигурационный файл и примеры настроенных конфигураций
Для версий Avanpost FAM ранее 1.4 был доступен метод настройки параметров через конфигурационный файл без настройки через административную консоль.
Данный вариант настройки оставлен для обратной совместимости с ранними версиями Avanpost FAM и компонентов Avanpost FAM Mobile Services. При наличии возможности настройки параметров через административную консоль рекомендуется выполнить ручной перенос параметров Avanpost Authenticator в административную консоль, а секцию mobilePushConfig из конфигурационного файла config.toml удалить.
В этом случае на стороне основного серверного компонента Avanpost FAM Server открыть основной конфигурационный файл config.toml (начиная с версии FAM v1.8.7.346 меняется конфигурационный файл с config.json на config.toml) и на основе выполнить настройку секции mobilePushConfig:
- pushServiceEnable – установлено значение true;
- radiuWaitApproveInSeconds – установлено значение 15;
- brokerAddresss – установлено значение параметра addr:port Push Service;
- proxyService.enable – если компонент API Service развёрнут и планируется к применению, то установить значение true;
- proxyService.backendProxyURL – установлено значение параметра baddr:port API Service;
- proxyService.frontendProxyURL – если компонент API Service развёрнут без последующего проксирования через внешний сетевой интерфейс, то установить значение параметра faddr:fport API Service; если компонент не развёрнут, то установить значение параметра base_url из основного конфигурационного файла компонента Avanpost FAM Server config.toml;
- proxyService.token – установлено значение параметра token API Service.
Пример конфигурации №1
Пример настроенной секции mobilePushConfig в файле config.toml компонента Avanpost FAM Server при обращении приложения Avanpost Authenticator к API по IP-адресу:
... "mobilePushConfig": { "pushServiceEnable": true, "radiusWaitApproveInSeconds": 15, "brokerAddress": "localhost:4222", "proxyService": { "enable": true, "backendProxyURL": "http://10.10.17.45:9999", "frontendProxyURL": "http://95.31.144.35:8888", "token": "tokenvalue12345678" } }, ...
Пример конфигурации №2
Пример настроенной секции (начиная с версии FAM v1.8.7.346 меняется конфигурационный файл с config.json на config.toml) в файле config.toml компонента Avanpost FAM Server при обращении приложения Avanpost Authenticator к API Service через прокси-сервер (например, Nginx), который выполняет преобразование доменного имени mobapifam.dmz.company.ru:443 на IP-адрес и порт 95.31.144.35:8888; при этом для работы HTTPS/TLS требуется настраивать при помощи средств прокси-сервера:
... "mobilePushConfig": { "pushServiceEnable": true, "radiusWaitApproveInSeconds": 15, "brokerAddress": "localhost:4222", "proxyService": { "enable": true, "backendProxyURL": "http://10.10.17.45:9999", "frontendProxyURL": "https://mobapifam.dmz.company.ru", "token": "tokenvalue12345678" } }, ...