Представляем вашему вниманию вторую статью из цикла “Как в Entaxy ION сделать …?”. В ней мы обратим ваше внимание на конфигурацию сервисов REST и SOAP. Представьте ситуацию, когда у вас есть файл с описанием сервиса – это может быть json или yaml, описанный по спецификации OpenAPI или xml с WSDL описанием SOAP сервиса. Вам требуется оперативно запустить сервис по этому описанию, чтобы системы-источники могли начать отправлять данные. А ещё этот сервис надо как-то обезопасить. А ещё… Но обо всё по порядку – расскажем и научим в этой статье.
Обмен данными между системами начинается с точек входа – в них инициирующая система отправляет пакеты данных в принимающую систему. Согласно нашему опыту, наиболее часто используются следующие точки входа:
Файловый обмен – совместно используемая папка
REST/SOAP сервис
Отдельное внимание хочется уделить безопасности точек входа – представьте задачу получения данных, которые пушат внешние поставщики. Эту задачу возможно решить при помощи белого списка адресов. А если эта стратегия по какой-то причине не применима?
В этой статье расскажем, как настроить и запустить сервисы REST и SOAP API на интеграционной платформе Entaxy ION.
На платформе различают два типа сервисов:
Защищенные (PROTECTED)
Открытые (PUBLIC)
Защищенные сервисы требуют обязательной привязки к профилю системы внутри Entaxy ION, чтобы гарантировать доступ только представленным на платформе внешним системам. При создании защищенного сервиса необходимо выбрать тип авторизации: JAAS или OAuth (с режимами STANDALONE (локальная независимая проверка токенов) или INTROSPECT (для динамической проверки токенов через внешний сервер)).
В процессе создания защищенного сервиса автоматически создается входной коннектор, который нужно подключить к соответствующему профилю системы. Этот профиль должен быть привязан к учетной записи пользователя, обеспечивая контроль доступа к сервису. Чтобы узнать, как построить интеграцию, а также что такое профиль и коннектор, ознакомьтесь с первой статьёй цикла - ссылка.
Публичные сервисы, в свою очередь, могут быть настроены без обязательной привязки к профилю системы и без обязательной авторизации, предоставляя гибкость в управлении доступом в зависимости от потребностей вызывающей системы.
В этой статье мы уделим большее внимание защищённым сервисам.
SOAP и REST: Поддерживаемые форматы данных
Для REST API наиболее распространённым форматом данных является JSON, простой и лёгкий в использовании, позволяющий эффективно обмениваться данными между системами. Entaxy ION поддерживает спецификацию OpenAPI 3.0.1 упрощая описание и интеграцию сервисов.
SOAP API использует XML, который описывает структуру и содержимое сообщений, включая данные и инструкции для выполнения удалённых операций или вызовов методов.
СОЗДАНИЕ СЕРВИСОВ
РЕСУРСЫ
Перед созданием сервиса необходимо сначала загрузить файлы описаний API в раздел «Ресурсы», который служит основным хранилищем для всех файлов и компонентов, необходимых для функционирования платформы, обеспечивая централизованное управление ресурсами. Entaxy ION поддерживает форматы JSON и YAML для REST API, а также WSDL для SOAP API.
СЕРВИСЫ
После загрузки описания приступаем к созданию сервиса:
Переходим в раздел «Сервисы» и нажимаем кнопку «Add Service».
Выбираем нужный тип сервиса: REST::OPENAPI::PROTECTED или SOAP::WSDL::PROTECTED.
В разделе параметров general в поле Object Id указываем имя сервиса.
В разделе параметров main в поле OpenApi schema (для REST) и WSDL schema (для SOAP) загружаем соответствующий файл описания API из раздела «Ресурсы».
Затем переходим в раздел параметров Security, где выбираем используемый тип авторизации:
AUTHORIZATION TYPE: JAAS (REST/SOAP)
Ключевые параметры:
Authorization realm: выбор области авторизации (по умолчанию используется предустановленный реалм karaf, с возможностью создания пользовательского реалма);
Public Service Schema: Активация публичного доступа к схеме сервиса независимо от аутентификации;
Restrict access by roles: Активация управления доступом на основе ролей, назначенных учетным записям пользователей;
Roles allowed to access: Указание ролей, которым разрешен доступ.
AUTHORIZATION TYPE: OAUTH STAND ALONE (REST)
Ключевые параметры:
Public Service Schema: Активация публичного доступа к схеме сервиса независимо от аутентификации;
Restrict access by roles: Активация управления доступом на основе ролей, назначенных учетным записям пользователей;
Roles allowed to access: Указание ролей, которым разрешен доступ;
Regexp for jwt auth filter: Шаблон (регулярное выражение) для проверки и фильтрации JWT-токенов. По умолчанию указано \W+, что соответствует любому неалфавитно-цифровому символу;
Keystore: Выбор keystore используемого для проверки подписи токенов;
Jwt Alias: Alias ключа из выбранного keystore.
AUTHORIZATION TYPE: OAUTH INTROSPECT (REST)
Ключевые параметры:
Public Service Schema: Активация публичного доступа к схеме сервиса независимо от аутентификации;
Introspect Authorization Login: логин для авторизации при использовании Introspect URL;
Introspect Authorization Password: пароль для авторизации при использовании Introspect URL;
Introspect URL: URL-адрес сервиса для проверки токенов.
Http receive timeout: Максимальное время ожидания для получения ответа от сервера при запросе информации о токене.
6 После выбора типа авторизации и заполнения необходимых полей нажимаем кнопку «Add» для создания сервиса.
Для защищённых (REST/SOAP) сервисов необходимо подключение входного коннектора для взаимодействия с внешними системами. Коннектор создаётся автоматически сразу после создания сервиса.
Рассмотрим, как запустить защищённый REST-сервис при выборе типа авторизации JAAS.
Следующим шагом после создания сервиса создаем профиль отправляющей системы и подключаем коннектор:
Для создания профиля переходим в раздел «Профили» и нажимаем кнопку «Add profile». Указываем имя системы и нажимаем кнопку «Add».
Добавляем к профилю входной коннектор защищённого сервиса.
Перейдя на вкладку «Profile Diagram», мы можем увидеть схему настроенного взаимодействия, визуализирующую структуру профиля системы, подключенного к нему коннектора и их взаимодействие с потоками данных, где:
Source (Источник данных) — защищённый REST-сервис
system1C.rest-service-rest-connector-in.main — подключенный входной коннектор защищённого REST-сервиса, содержащий точки кастомизации:
pre-route — предварительная обработка данных на уровне коннектора
response — обработка ответа на уровне коннектора
IN-FLOW – входной поток данных профиля системы, содержащий точки кастомизации:
pre-route — предварительная обработка данных на уровне профиля системы
response — обработка ответа на уровне профиля системы
default-route – маршрутизатор, соединяющий систему отправителя с другими сущностями архитектуры Entaxy
Диаграмма наглядно отображает структуру настроенного взаимодействия, позволяя проверить корректность конфигурации.
Безопасность
После создания систем и подключения коннекторов необходимо настроить авторизацию, ассоциировав учетную запись пользователя с профилем отправляющей системы.
a. Переходим в раздел «Безопасность», затем в подраздел «JAAS». Здесь можно выбрать предустановленный реалм «karaf» или создать кастомный реалм с индивидуальными настройками безопасности (пользователями, ролями и политиками доступа) или подключить дополнительные модули, такие как JDBC или LDAP. Далее из списка подключённых модулей выбираем «karaf-properties» (Хранит данные пользователей в формате плоского файла. Пароли могут быть опционально зашифрованы алгоритмом хеширования).
b. Затем выбираем одного из предустановленных пользователей (или создаем нового пользователя), например, «karaf» (пароль по умолчанию — «karaf») и ассоциируем его с профилем отправляющей системы.
Проверка доступа к защищенному сервису
Теперь можно проверить доступ к защищённому сервису с помощью Postman, используя в качестве имени пользователя и пароля учётные данные: karaf/karaf.
Список развернутых на платформе сервисов можно просмотреть по адресу: http://localhost:8181/cxf
a. Проверка доступа без ролевых ограничений
Выполняем запрос к сервису и проверяем, что доступ предоставляется без ограничений по ролям.
b. Проверка ограничения доступа по ролям
Для ограничения доступа по ролям в разделе «Безопасность» сервиса активируем чек-бокс «Restrict access by roles» и указываем роль (или их перечень через запятую), которым будет разрешен доступ к сервису. Если необходимо предоставить доступ всем пользователям, можно использовать символ '*' (звездочка), что откроет доступ для всех ролей. Важно, чтобы роли, указанные здесь, были корректно настроены в выбранном реалме JAAS (например, «karaf»), так как доступ к сервису будет зависеть от настроек аутентификации и авторизации в рамках этого реалма.
c. Проверка отказа в доступе
Проверяем доступ к сервису, указывая роль, которой нет у пользователя karaf. Убедимся, что доступ к сервису для этого пользователя будет запрещён.
Аналогичным образом выполняется настройка и запуск защищённого SOAP сервиса.
Защищённые сервисы обеспечивают дополнительный уровень безопасности благодаря использованию входного коннектора, который гарантирует защиту данных при их передаче и обеспечивает гибкий контроль над маршрутизацией. После получения сообщения, с учётом всех настроек безопасности и маршрутизации, Entaxy направляет его в целевую систему для дальнейшей обработки.
