Установка 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 для мобильных приложений Avanpost Authenticator (E-passport Mobile для iOS) сотрудников;
  • Push Service, выполняющий роль брокера сообщений для доставки push-сообщений в приложения сотрудников Avanpost Authenticator (E-passport Mobile для iOS).

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

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

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

  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

Установку FAM Push Service выполнять следующим образом:

  1. Установить пакет pushgwsrv: 
    sudo apt install pushgwsrv
  2. Удержать пакет от обновления при выполнении команды:
    sudo apt-mark hold pushgwsrv
    sudo nano /etc/systemd/system/pushgwsrv.service
  3. Указать актуальные значения параметров:
    ПараметрЗначение
    [Unit]

    Description

    		Описание (наименование) сервиса. 
    [Service]
    WorkingDirectoryРабочая директория, в которой запускается процесс.

    ExecStart

    Команда для запуска сервиса с указанием полного пути к исполняемому файлу и параметрами командной строки. Содержит следующие параметры:

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

    Restart

    		Параметр настройки автоматического перезапуска сервиса (значение always означает, что сервис будет автоматически перезапускаться при любой причине остановки).

    RestartSec

    		Время ожидания (в секундах) перед перезапуском сервиса после его остановки.

    SyslogIdentifier

    		Имя, под которым логи сервиса записываются в системный журнал (syslog).

    User

    		Идентификатор пользователя, от имени которого запускается процесс. Рекомендуется использовать специально созданного пользователя idp. 

    [Install]

    WantedBy

    		Параметр, указывающий, когда должен быть запущен сервис (по умолчанию multi-user.target сервис будет запускаться автоматически при загрузке системы).
    [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. Убедиться, что необходимые порты открыты в межсетевом экране firewalld (в противном случае сервис окажется недоступен извне).
  5. Перезапустить службы:
    sudo systemctl daemon-reload
sudo systemctl enable pushgwsrv
sudo systemctl start pushgwsrv
  6. По результатам выполненной настройки компонента API Service следует зафиксировать параметры, которые потребуются на следующем шаге: 
    • addr:port Push Service.

Установка API Service

Установку FAM API Service выполнять следующим образом:

  1. Установить пакет authproxy:
    sudo apt install authproxy
  2. Удержать пакет от обновления при выполнении команды: 
    sudo apt-mark hold authproxy
    sudo nano /etc/systemd/system/authproxy.service
  3. Указать актуальные значения параметров:
    ПараметрЗначение
    [Unit]

    Description

    		Описание (наименование) сервиса. 
    [Service]
    WorkingDirectoryРабочая директория, в которой запускается процесс.

    ExecStart

    Команда для запуска сервиса с указанием полного пути к исполняемому файлу и параметрами командной строки. Содержит следующие параметры

    • --baddr – Адрес интерфейса для входящих запросов от мобильного приложения. IP-адрес (в примере ниже указан как 127.0.0.1): по умолчанию не определён и должен быть заменён на актуальное значение.
    • --bport – Порт внутреннего сетевого интерфейса, к которому будет обращаться компонент Avanpost FAM Server (или экземпляры компонента Avanpost FAM Server в случае использования кластеризованной схемы развёртывания). Порт по умолчанию – 9999.
    • --faddr – Адрес внешнего сетевого интерфейса, к которому обращаются мобильные приложения Avanpost Authenticator (E-passport Mobile). IP-адрес по умолчанию не определён и должен быть заменён на актуальное значение. 
    • --fport – Порт внешнего сетевого интерфейса, к которому обращаются мобильные приложения Avanpost Authenticator (E-passport Mobile). Порт по умолчанию – 8888.
    • --token – Cекретный токен, заданный на стороне компонента Avanpost FAM Server при настройке API Service.

      Важно

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

    • --skip-not-initial – Обязательный флаг для режима работы с несколькими FAM-узлами в отказоустойчивом исполнении. Обеспечивает агрегацию push-уведомлений и маршрутизацию запросов.

    Restart

    		Параметр настройки автоматического перезапуска сервиса (значение always означает, что сервис будет автоматически перезапускаться при любой причине остановки).

    RestartSec

    		Время ожидания (в секундах) перед перезапуском сервиса после его остановки.

    SyslogIdentifier

    		Имя, под которым логи сервиса записываются в системный журнал (syslog).

    User

    		Идентификатор пользователя, от имени которого запускается процесс. Рекомендуется использовать специально созданного пользователя idp. 

    [Install]

    WantedBy

    		Параметр, указывающий, когда должен быть запущен сервис (по умолчанию multi-user.target сервис будет запускаться автоматически при загрузке системы).
    [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
  4. Убедиться, что необходимые порты открыты в межсетевом экране firewalld (в противном случае сервис окажется недоступен извне).
  5. Перезапустить службы: 
    sudo systemctl daemon-reload
sudo systemctl enable authproxy
sudo systemctl start authproxy

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

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

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

Настройку компонента на стороне FAM Server необходимо выполнять следующим образом (для получения более подробной информации следует обратиться к статьям Управление аутентификацией и Настройка метода Avanpost Authenticator):

  1. В административной консоли в режиме "Сервис" перейти в раздел "Настройки методов аутентификации".
  2. Нажать кнопку "Добавить метод аутентификации".
  3. Настроить параметры согласно таблице и нажать "Далее". 
    ПараметрЗначение
    НазваниеУказать произвольное название (например, «Avanpost Authenticator»).
    Фактор аутентификацииВыбрать «Avanpost Authenticator».
    Метод активенУстановить флаг.
  4. На следующем шаге указать параметры работы метода аутентификации согласно таблице (дополнительной информации о параметрах представлена в статье Настройка метода Avanpost Authenticator):
    ПараметрЗначение
    Ключ-тэгУказать любой уникальный удобный идентификатор, состоящий из букв латинского алфавита и цифр (значение будет фигурировать в журналах).
    Метод активенУстановить флаг.
    Мобильные сервисы включены и доступны для пользователейУстановить флаг.
    Адрес push-сервисаВвести значение: baddr:bport Push Service.
    Email службы технической поддержки

    Ввести контактную информацию и сообщение для пользователей.

    Во избежание возникновения ошибки данные поля должны быть заполнены.


    Телефон службы технической поддержки
    Сообщение для пользователей

    DNS-имя (хост), используемое в качестве внешнего URL-адреса для подключения мобильного приложения Avanpost Authenticator, не должно содержать символа подчёркивания (_). Согласно стандарту DNS (RFC 1035), имена хостов должны соответствовать правилам LDH (только латинские буквы, цифры и дефис).

  5. Нажать кнопку "Сохранить".
  6. В разделе "Настройки методов аутентификации" перейти в профиль настроенного метода и задать следующие параметры. 
    ПараметрЗначение
    Внешний URL-aдрес

    Ввести один из следующих вариантов:

    • Если компонент API Service развёрнут без последующего проксирования через внешний сетевой интерфейс, то установить значение параметра faddr:fport API Service; 
    • Если компонент не развёрнут, то установить значение параметра base_url из основного конфигурационного файла компонента Avanpost FAM Server config.toml.
    Токен для подключения к API-сервисуЗначение, указанное ранее для параметра token для запуска компонента API Service.
  7. Дождаться автоматического перезапуска обработчиков: после завершения настройки и включения метода аутентификации (процесс может занять от нескольких секунд до 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
  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-сервис готов к обработке подключений).

 


Обсуждение