База знаний FAM/MFA+ : Установка FAM Mobile Services в ОС Linux из tar.gz-архива

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

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

Шаги для установки:

  1. Получить архив Avanpost.Mobile.Push.Service.*.tar.gz версии, соответствующей версии компонента Avanpost FAM Server .
  2. Распаковать файлы архива Avanpost.Mobile.Push.Service.*.tar.gz на предназначенном для этого сервере в DMZ в каталог /opt/avanpost_mobile_services .

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

В конфигурационном файле на узле, на котором развёрнут Avanpost FAM Server, требуется проверить наличие параметра backgroundTasks в значении true в конфигурационном файле config.json .

Настройка компонента 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.

Шаги по настройке:

  1. Зарегистрировать службу mobpushfam для компонента push_gateway_server (Push Service) из состава Avanpost FAM Mobile Services:

    [Unit]
    Description=Avanpost FAM Mobile Services Push
      
    [Service]
    WorkingDirectory=/opt/avanpost_mobile_services
    ExecStart=/opt/avanpost_mobile_services/push_gateway_server --baddr 10.10.17.45 --bport 4222
    Restart=always
    RestartSec=10
    SyslogIdentifier=mobpushfam
    User=idp
      
    [Install]
    WantedBy=multi-user.target

    где при необходимости указать актуальные значения параметров:

    1. --baddr – IP-адрес или хост, на котором требуется открытие сетевого порта для получения сетевых запросов от сервера Avanpost FAM; например – 10.10.17.45 ;

    2. --bport – порт, к которому будет подключаться Avanpost FAM Server; по умолчанию – 4222 .

  2. Выполнить регистрацию и запуск службы mobpushfam :

    systemctl daemon-reload
    systemctl enable mobpushfam
    systemctl start mobpushfam

По результатам выполненной настройки компонента API Service следует зафиксировать параметры, которые потребуются на следующем шаге:

  • baddr:bport Push Service.

Установка и настройка компонента API Service

Работы по установке компонента API Service выполняются на подготовленном сервере, предназначенном для размещения компонентов Avanpost FAM Mobile Services.

В случае отсутствия DMZ возможно отказаться от использования компонента API Service и использовать стандартный API-интерфейс, предоставляемый Avanpost FAM Server. Следует учитывать, что в этом случае могут возникнуть риски, связанные с прямой публикацией в интернет HTTP/HTTPS-интерфейсов Avanpost FAM Server.

Шаги по выполнению настройки:

  1. Зарегистрировать службу mobapifam для компонента authenticator_proxy (API Service) из состава Avanpost FAM Mobile Services:

    [Unit]
    Description=Avanpost FAM Mobile Services API
      
    [Service]
    WorkingDirectory=/opt/avanpost_mobile_services
    ExecStart=/opt/avanpost_mobile_services/authenticator_proxy --baddr 10.10.17.45 --bport 9999 --faddr 95.31.144.35 --fport 8888 --token tokenvalue12345678
    Restart=always
    RestartSec=10
    SyslogIdentifier=mobapifam
    User=idp
      
    [Install]
    WantedBy=multi-user.target

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

    • --baddr и --bport – указав соответственно адрес и порт внутреннего сетевого интерфейса, к которому будет обращаться компонент Avanpost FAM Server (или экземпляры компонента Avanpost FAM Server в случае использования кластеризованной схемы развёртывания); IP-адрес в примере ( 10.10.17.45 ) по умолчанию не определён и должен быть заменён на актуальное значение, порт по умолчанию – 9999 ;

    • --faddr и --fport – указав соответственно адрес и порт внешнего сетевого интерфейса, к которому будут обращаться через интернет мобильные приложения Avanpost Authenticator ; IP-адрес в примере ( 95.31.144.35 ) по умолчанию не определён и должен быть заменён на актуальное значение, порт по умолчанию – 8888 ;

    • --token – секретный токен, который далее должен быть указан на стороне компонента Avanpost FAM Server; значение токена в примере ( 12345678 ) должно быть заменено на актуальное значение.

      Значение параметра token обязательно для указания и должно содержать не менее 5 символов

  2. Выполнить регистрацию и запуск службы mobapifam :

    systemctl daemon-reload
    systemctl enable mobapifam
    systemctl start mobapifam

Если требуется выполнить публикацию внутреннего сетевого интерфейса компонента API Service (определяемого параметрами baddr:bport компонента 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 доступен порт:

  • baddr:bport 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.json ;
    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.json удалить.

В этом случае на стороне основного серверного компонента Avanpost FAM Server открыть основной конфигурационный файл config.json и на основе выполнить настройку секции mobilePushConfig :

  • pushServiceEnable –  установлено значение true ;
  • radiuWaitApproveInSeconds – установлено значение 15;
  • brokerAddresss – установлено значение параметра baddr:bport Push Service;
  • proxyService.enable – если компонент API Service развёрнут и планируется к применению, то установить значение true ;
  • proxyService.backendProxyURL – установлено значение параметра baddr:bport API Service ;
  • proxyService.frontendProxyURL – если компонент API Service развёрнут без последующего проксирования через внешний сетевой интерфейс, то установить значение параметра faddr:fport API Service ;  если компонент не развёрнут, то установить значение параметра base_url из основного конфигурационного файла компонента Avanpost FAM Server config.json ;
  • proxyService.token – установлено значение параметра token API Service.

Пример конфигурации №1

Пример настроенной секции mobilePushConfig в файле config.json компонента 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.json компонента 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"
    }
},
...