Коннектор UniBPM: Keycloak (unibpm-external-task-keycloak)

Назначение

Модуль unibpm-external-task-keycloak предоставляет коннектор UniBPM для взаимодействия BPMN‑процессов с системой управления идентификацией Keycloak через механизм External Task.

Коннектор позволяет процессам:

• получать данные пользователя
• искать пользователя по username
• получать группы пользователя
• получать информацию о группе
• получать участников группы

Модуль выполняется сервисом Integration Runtime, который получает задания из Kafka‑топиков UniBPM.

Архитектура

BPMN Service Task
→ UniBPM Engine
→ Kafka Topic (external-task.jobs.*)
→ Integration Runtime
→ Handler коннектора Keycloak
→ Keycloak Admin REST API

Компонент Назначение

UniBPM Engine публикует задания External Task Integration Runtime выполняет обработчики коннекторов KeycloakClient HTTP‑клиент для Keycloak Handlers реализуют конкретные действия коннектора

Поддерживаемые действия

Action Описание

user.get Получить пользователя по ID user.getByUsername Найти пользователя по username user.groups Получить группы пользователя group.get Получить группу по ID group.members Получить участников группы group.getByName Найти группу по name

Общие extension properties

Каждый BPMN Service Task должен определять следующие свойства:

Свойство Обязательное Описание

uni.connector ✔ имя коннектора (keycloak) uni.action ✔ выполняемое действие uni.version ✔ версия коннектора kc.result ✖ имя переменной процесса для результата kc.select ✖ фильтрация атрибутов результата

Фильтрация результата (kc.select)

Свойство kc.select позволяет возвращать только выбранные поля ответа Keycloak.

Фильтрация работает как whitelist‑проекция атрибутов.

Пример

Ответ Keycloak:

{
  "id": "123",
  "username": "ivanov",
  "email": "ivanov@reunico.com"
}

Конфигурация BPMN:

kc.select = id,email

Результат:

```json
{
  "id": "123",
  "email": "info@reunico.com"
}

Вложенные атрибуты

Поддерживается выбор вложенных полей:

kc.select = id,attributes.signerFullName

Результат:

{
  "id": "123",
  "attributes": {
    "signerFullName": "Seva Ivanov"
  }
}

Работа со списками

Если ответ содержит массив объектов, фильтрация применяется к каждому элементу.

Пример:

kc.select = id,email

Результат:

[
  {
    "id": "1",
    "email": "a@company.com"
  },
  {
    "id": "2",
    "email": "b@company.com"
  }
]

Действия

user.get

Получить пользователя по ID.

Extension properties

Свойство Обязательное Описание

kc.userId ✔ ID пользователя Keycloak kc.result ✖ имя переменной результата kc.select ✖ фильтрация результата

Пример

uni.connector = keycloak
uni.action = user.get
uni.version = v1

kc.userId = ${userId}
kc.result = userData

user.getByUsername

Получить пользователя по username.

Extension properties

Свойство Обязательное Описание

kc.username ✔ username пользователя kc.result ✖ переменная результата kc.select ✖ фильтрация результата

Пример:

uni.connector = keycloak
uni.action = user.getByUsername
uni.version = v1

kc.username = ${initiator}

user.groups

Получить группы пользователя.

Extension properties

Свойство Обязательное Описание

kc.userId ✔ ID пользователя kc.result ✖ переменная результата kc.select ✖ фильтрация результата

Результат:

kc.groups = List<KeycloakGroup>

group.get

Получить группу по ID.

Extension properties

Свойство Обязательное Описание

kc.groupId ✔ ID группы kc.result ✖ переменная результата kc.select ✖ фильтрация результата

group.getByName

Получить группу по имени.

Extension properties

Свойство Обязательное Описание

kc.groupName ✔ ID группы kc.result ✖ переменная результата kc.select ✖ фильтрация результата

group.members

Получить участников группы.

Extension properties

Свойство Обязательное Описание

kc.groupId ✔ ID группы kc.first ✖ offset kc.max ✖ limit kc.result ✖ переменная результата kc.select ✖ фильтрация результата

BPMN ошибки

Некоторые ошибки коннектора преобразуются в BPMN Error.

Код Описание

KC_USER_NOT_FOUND пользователь не найден KC_GROUP_NOT_FOUND группа не найдена

Пример BPMN Service Task

uni.connector = keycloak
uni.action = user.groups
uni.version = v1

kc.userId = ${initiator}
kc.result = groups
kc.select = id,name

Результат:

[
  { "id": "...", "name": "Managers" },
  { "id": "...", "name": "HR" }
]

Требования

Сервис‑аккаунт Keycloak должен иметь следующие роли:

realm-management
manage-users
view-users
query-groups

Технологии

• Java 17
• Spring Boot
• OpenFeign
• Kafka
• Jackson
• Keycloak Admin REST API