4.3.3. Установка FAM Mobile Services в ОС Linux из tar.gz-архива

[ Общие сведения ] [ Установка и настройка ] [ Установка файлов компонентов Avanpost FAM Mobile Services ] [ Настройка компонента Avanpost FAM Server ] [ Настройка компонента Push Service ] [ Установка и настройка компонента API Service ] [ Настройка на стороне Avanpost FAM Server ] [ Приложение А. Примеры настроенных конфигураций Avanpost Mobile Services через административную консоль ] [ Пример конфигурации №1. Установлены и настроены компоненты Push Service и API Service ] [ Пример конфигурации №2. Установлен и подключен Push Service без API Service ] [ Приложение Б. Настройка параметров через конфигурационный файл и примеры настроенных конфигураций ] [ Пример конфигурации №1 ] [ Пример конфигурации №2 ]

Общие сведения

Данная инструкция применима к любой ОС 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, до адресов:

Поэтому перед выполнением настройки необходимо убедиться, что эти сетевые адреса доступны через интернет с сервера, на котором размещается 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.

Перейти в административную консоль, Сервис/Настройки методов аутентификации, после чего создать метод аутентификации, указав следующие параметры:

Добавить метод аутентификации:
1. Название – указать произвольное название, например, «Avanpost Authenticator» или «мобильный аутентификатор»;
2. Фактор аутентификации – выбрать Avanpost Authenticator;
3. Метод активен – если метод единственный, то активировать.
На следующем шаге указать параметры работы метода аутентификации:
1. Ключ-тэг – указать любой уникальный удобный идентификатор, состоящий из букв латинского алфавита и цифр; будет фигурировать в журналах;
2. Метод активен – флаг включен;
3. Сервис push-уведомлений включен – если компонент API Service развёрнут и планируется к применению, то установить значение true;
4. Таймаут ожидания подтверждения через push-уведомление (в секундах) – можно оставить значение по умолчанию;
5. Адрес сервиса push-уведомлений – установлено значение параметра addr:port Push Service;
6. Внешний URL-aдрес – если компонент API Service развёрнут без последующего проксирования через внешний сетевой интерфейс, то установить значение параметра faddr:fport API Service; если компонент не развёрнут, то установить значение параметра base_url из основного конфигурационного файла компонента Avanpost FAM Server config.toml (начиная с версии FAM v1.8.7.346 меняется конфигурационный файл с config.json на config.toml);
7. Токен для подключения к 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"
    }
},
...