Общие сведения
Данная инструкция применима к любой ОС Linux, обладающей следующими характеристиками:
- Имеется systemd.
- Отсутствует либо корректно настроены firewall-компоненты (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
.
Настройка компонента 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
Поэтому перед выполнением настройки необходимо убедиться, что эти сетевые адреса доступны через интернет с сервера, на котором размещается 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
Указать актуальные значения параметров:
- --addr и --port – указав соответственно адрес и порт внутреннего сетевого интерфейса, к которому будет обращаться компонент 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 --addr 127.0.0.1 --port 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 следует зафиксировать значения параметров, которые потребуются на следующем шаге:
addr:port API Service;
faddr:fport API Service;
token API Service.
Настройка на стороне Avanpost FAM Server
Перед выполнением настройки следует убедиться, что с сервера Avanpost FAM доступен порт:
addr:port Push Service
;addr:port 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 Serverconfig.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
и на основе выполнить настройку секции mobilePushConfig
:
pushServiceEnable
– установлено значениеtrue
;radiuWaitApproveInSeconds –
установлено значение 15;brokerAddresss –
установлено значение параметраaddr:port Push Service;
proxyService.enable
– если компонент API Service развёрнут и планируется к применению, то установить значениеtrue
;proxyService.backendProxyURL
– установлено значение параметраaddr:port API Service
;proxyService.frontendProxyURL
– если компонент API Service развёрнут без последующего проксирования через внешний сетевой интерфейс, то установить значение параметраfaddr:fport API Service
; если компонент не развёрнут, то установить значение параметраbase_url
из основного конфигурационного файла компонента Avanpost FAM Serverconfig.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
Пример настроенной секции mobilePushConfig
в файле 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" } }, ...