Установка FAM Mobile Services в ОС Linux из deb-пакета


[ Установка и настройка ] [ Требования к окружению ] [ DEB-пакет ] [ Общая часть установки ] [ Установка Push Service ] [ Установка API Service ] [ Настройка на стороне Avanpost FAM Server ] [ Настройка для адресов IPv6 ] [ Генерация сертификатов ] [ Настройка при генерации единого сертификата для всех служб ] [ Настройка при генерации отдельного сертификата для каждой службы ] [ Проверка доступности сервисов ]

Работы по установке компонентов Avanpost FAM Mobile Services выполняются на подготовленном сервере с ОС Linux. 

При установке будут использованы два пакета для работы Avanpost FAM Mobile Services:

  • API Service, предоставляющий API для мобильных приложений сотрудников;
  • Push Service, выполняющий роль брокера сообщений для доставки push-сообщений.

Установка и настройка

Требования к окружению

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

  1. В ОС семейства Debian Linux должны быть установлены следующие программы:
    - sudo (программа выполнения команд от имени суперпользователя).

  2. Выполнена синхронизация времени в ОС с сервером синхронизации времени.


Примечание

Установка и настройка указанных программ выходит за границы текущей инструкции и описана в справочных руководствах, идущих в комплекте с операционной системой Linux, на которой производится развёртывание.

DEB-пакет

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

При внесении изменений в собственный конфигурационный файл разворачивать систему стоит с учётом поправок по собственным настройкам (например, использовать другие пути к файлам).

Общая часть установки

  1. Открыть файл sources.list: 
    sudo nano /etc/apt/sources.list
  2. Указать репозиторий, для того, чтобы скачать последнюю версию пакета Avanpost FAM Mobile Services: 
    deb https://packages.avanpost.ru/repository/deb-hosted/ linux main
  3. Скачать публичный ключ репозитория: 
    wget -q "https://docs.avanpost.ru/certs/deb-hosted.gpg.key"
  4. Добавить публичный ключ в Систему: 
    sudo apt-key add deb-hosted.gpg.key

  5. Обновить список пакетов: 

    sudo apt update

Установка Push Service

Установить пакет pushgwsrv: 

sudo apt install pushgwsrv

Удержать пакет от обновления при выполнении команды 

sudo apt-mark hold pushgwsrv
sudo nano /etc/systemd/system/pushgwsrv.service

Указать актуальные значения параметров:

      • -addr – IP-адрес или хост, на котором требуется открытие сетевого порта для получения сетевых запросов от сервера Avanpost FAM; например – 0.0.1;
      • -port – порт, к которому будет подключаться Avanpost FAM Server; по умолчанию – 4222
[Unit]
Description=Avanpost FAM Mobile Services Push  

[Service]
WorkingDirectory=/opt/avanpost_mobile_services
ExecStart=/opt/avanpost_mobile_services/push_gateway_server -addr 127.0.0.1 -port 4222
Restart=always
RestartSec=10
SyslogIdentifier=pushgwsrv
User=idp  

[Install]
WantedBy=multi-user.target

Перезапустить службы: 

systemctl daemon-reload
systemctl enable pushgwsrv
systemctl start pushgwsrv

Установка API Service

Установить пакет authproxy: 

sudo apt install authproxy

Удержать пакет от обновления при выполнении команды 

sudo apt-mark hold authproxy
sudo nano /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) должно быть заменено на любое актуальное значение.

Важно

В токене не должно содержаться кириллических символов, а также спецсимволов (~ . .. / # ? * [ ] ; & < > | ! $). Сам токен следует обрамлять одинарными кавычками в качестве дополнительной защиты (экранирование символов от использования их в качестве параметров командной строки).

[Unit]
Description=Avanpost FAM Mobile Services API  

[Service]
WorkingDirectory=/opt/avanpost_mobile_services
ExecStart=/opt/avanpost_mobile_services/authenticator_proxy -baddr 127.0.0.1 -bport 9999 -faddr 127.0.0.1 -fport 8888 -token tokenvalue12345678
Restart=always
RestartSec=10
SyslogIdentifier=authproxy
User=idp  

[Install]
WantedBy=multi-user.target

Перезапустить службы:

systemctl daemon-reload
systemctl enable authproxy
systemctl start authproxy

Настройка на стороне Avanpost FAM Server

Перед выполнением настройки следует убедиться, что с сервера Avanpost FAM доступен порт:

  • addr:port Push Service;
  • baddr:bport API Service.

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

  1. Добавить метод аутентификации:
    1. Название – указать произвольное название, например, «Avanpost Authenticator» или «мобильный аутентификатор»; 
    2. Фактор аутентификации – выбрать Avanpost Authenticator;
    3. Метод активен – если метод единственный, то активировать.
  2. На следующем шаге указать параметры работы метода аутентификации:
    1. Ключ-тэг – указать любой уникальный удобный идентификатор, состоящий из букв латинского алфавита и цифр; будет фигурировать в журналах;
    2. Метод активен – флаг включен; 
    3. Сервис push-уведомлений включен – если компонент API Service развёрнут и планируется к применению, то установить значение true;
    4. Таймаут ожидания подтверждения через push-уведомление (в секундах) – можно оставить значение по умолчанию;
    5. Адрес сервиса push-уведомлений – установлено значение параметра baddr:bport 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-уведомлений будет доступен и будет функционировать.

Важно

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

 

Настройка для адресов IPv6

Если в сети используется IPv6, то адрес внутреннего сетевого интерфейса, к которому будет обращаться компонент Avanpost FAM Server (или экземпляры компонента Avanpost FAM Server в случае использования кластеризованной схемы развёртывания); IP-адрес (в примере ниже указан как 127.0.0.1) по умолчанию должен быть заменён на 0.0.0.0. В случае, если адрес внутреннего сетевого интерфейса совпадает с адресом Avanpost FAM Server , то указывается 127.0.0.1.

Генерация сертификатов

Допускаются два способа использования сертификатов (дальнейшая настройка отличается в зависимости от выбранного способа): 

  • генерация единого сертификата для всех служб;
  • генерация отдельного сертификата для каждой службы.

Настройка при генерации единого сертификата для всех служб

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

  1. Перейти в директорию /opt/authenticator_proxy (допускается перейти в другое место с указанием пути к настраиваемой службе).

    Путь к системному хранилищу сертификатов зависит от ОС:

    1. CentOS/RHEL 8: /etc/pki/ca-trust/extracted/pem/.

    2. Debian/Ubuntu: /etc/ssl/certs/.

  2. Выполнить команду по аналогии с нижеприведенной (значения IP-адреса, CN и прочие параметры должны быть заменены на актуальные):
    openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout key.pem -out cert.pem -subj "/CN=my1.api-service.fam" -addext "subjectAltName=DNS:api-service.fam,DNS:*.api-service.fam,IP:10.10.161.172"
  3. Добавить сертификат в службу, при настройке путь до сертификата. Данное действие требуется выполнить как для служб API, так и служб PUSH.
    1. Настройку TLS-соединения для служб API осуществлять по аналогии с данным примером (при необходимости настроить несколько служб API):
      [Unit]
Description=Avanpost FAM Mobile Services API

[Service]
WorkingDirectory=/opt/authenticator_proxy_2
ExecStart=/opt/authenticator_proxy_2/authenticator_proxy -baddr 10.10.161.172 -bport 9992 -faddr 10.10.161.172 -fport 8882 -token 123456 -tls -tlscert /opt/authenticator_proxy/cert.pem -tlskey /opt/authenticator_proxy/key.pem
Restart=always
RestartSec=10
SyslogIdentifier=authproxy
User=idp

[Install]
WantedBy=multi-user.target
    2. Настройку TLS-соединения для служб PUSH осуществлять по аналогии с данным примером (при необходимости настроить несколько служб PUSH):
      [Unit]
Description=Avanpost FAM Mobile Services Push

[Service]
WorkingDirectory=/opt/push_gateway_server_2
ExecStart=/opt/push_gateway_server_2/push_gateway_server -adr 10.10.161.172 -port 4224 -tls -tlscert /opt/authenticator_proxy/cert.pem -tls-key /opt/authenticator_proxy/key.pem
Restart=always
RestartSec=10
SyslogIdentifier=pushgwsrv
User=idp

[Install]
WantedBy=multi-user.target
  4. Чтобы настройки были перечитаны и изменения вступили в силу, выполнить следующую команду после изменения параметров:
    systemctl daemon-reload
  5. Для завершения настройки выполнить запуск служб authproxy и pushgwsrv при помощи нижеперечисленных команд:
    systemctl enable authproxy
systemctl start authproxy
systemctl enable pushgwsrv
systemctl start pushgwsrv

    Важно

    При настройке в разделе "Контактная информация" настроек метода "Avanpost Authenticator" поля данных должны быть заполнены во избежание возникновения ошибок.

     

  6. В административной консоли Avanpost FAM Server перейти в режим "Сервис", раздел "Настройки методов аутентификации" и войти в настройки метода "Avanpost Aurhenticator".
  7. Загрузить сертификат в формате .pem для Push-сервиса и API-сервиса:
    1. Включить флаг "Push-сервис использует TLS" и нажать кнопку "Выберите файл" в разделе "Сертификат TLS (PEM)", указав путь до файла .pem.
    2. Включить флаг "API-сервис использует TLS" и нажать кнопку "Выберите файл" в разделе "Сертификат TLS (PEM)", указав путь до файла .pem.
    3. Нажать кнопку "Сохранить".


Настройка при генерации отдельного сертификата для каждой службы

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

  1. Перейти в директорию /opt/authenticator_proxy (допускается перейти в другое место с указанием пути к настраиваемой службе).

  2. Создать файлы формата .pem (отдельный файл для API-сервисов и отдельный для Push-сервисов), скопировав в него содержимое сертификатов. 

    Пример файла, содержащего сгенерированный сертификаты. 

  3. В административной консоли Avanpost FAM Server перейти в режим "Сервис", раздел "Настройки методов аутентификации" и войти в настройки метода "Avanpost Aurhenticator".
  4. Загрузить сертификаты в формате .pem для Push-сервиса и API-сервиса:
    1. Включить флаг "Push-сервис использует TLS" и нажать кнопку "Выберите файл" в разделе "Сертификат TLS (PEM)", указав путь до файла .pem, содержащего сертификаты для Push-сервисов.
    2. Включить флаг "API-сервис использует TLS" и нажать кнопку "Выберите файл" в разделе "Сертификат TLS (PEM)", указав путь до файла .pem, содержащего сертификаты для API-сервисов.
    3. Нажать кнопку "Сохранить".

Проверка доступности сервисов

Для проверки доступности API-сервисов необходимо обратиться к faddr:fport по следующим адресам:

  • /api/health/live – для получения информации, запущена ли служба;
  • /api/health/ready – для получения информации о готовности к обработке подключений (если к службе подключен по меньшей мере один FAM Server, API-сервис готов к обработке подключений).

 


Обсуждение