Интеграция по GraphQL

Система предоставляет открытый API для управления учетными записями и другими объектами Системы из внешних приложений. API реализован по протоколу GraphQL — стандартному способу построения веб-API, функциональному аналогу REST API: запрос передается HTTP-методом POST в формате JSON, ответ возвращается в формате JSON.

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

• управление учетными записями — создание, изменение, блокировка и удаление пользователей, назначение групп;
• управление факторами аутентификации — способы МФА пользователя, доверенные устройства;
• управление политиками доступа — сервисы, группы, директории, поставщики ИД;
• выгрузка данных — журналы событий, отчеты об изменении прав пользователей.

Адрес конечной точки API: https://<SERVER>/dopusk/graphql, где <SERVER> — адрес сервера Системы.

Возможности API

Через API доступны справочники Системы. Для каждого объекта поддерживаются операции чтения, создания, изменения и удаления. Состав доступных объектов приведен в таблице.

Объект API	Справочник	Описание
users	Пользователи	Учетные записи, способы МФА, членство в группах
groups	Группы	Группы пользователей, роли доступа
services	Сервисы	Сервисы Единой точки входа, протоколы подключения
directories	Директории	Директории пользователей, синхронизация
idProviders	Поставщики ИД	Внешние поставщики идентификации
userAttributes	Пользовательские атрибуты	Атрибуты учетных записей
attrGroups	Атрибуты сервисов	Атрибуты, передаваемые сервисам
registrationRequests	Запросы на регистрацию	Обработка запросов на самостоятельную регистрацию
certificates	Сертификаты	Сертификаты Системы и пользователей
personalAccessTokens	-	Токены доступа пользователей
devices	-	Устройства пользователей
auditLog	Журнал событий	События аудита Системы
userAccessRightsLogs	Отчеты	Данные отчетов об изменении прав
tickets	-	Билеты Единой точки входа

Дополнительно доступны операции без справочника: synchronizeDirectory — запуск синхронизации директории по ее идентификатору.

Чтение поддерживает отбор записей: точный фильтр по значениям полей, сравнения GTE, LTE, GT, LT, перечисление значений IN, объединение условий AND, OR, NOT, а также постраничную выборку параметрами offset и limit. Связанные объекты запрашиваются вложенными полями, например группы и контакты пользователя.

Включение API

По умолчанию API выключен — конечная точка не регистрируется и запросы к ней завершаются ошибкой 404. Включение выполняется параметром server.graphql.enabled и требует перезапуска Системы.

1. Установить параметр server.graphql.enabled в значение true.
2. Перезапустить сервисы Системы (см. Установка Системы).

После включения API доступен по адресу https://<SERVER>/dopusk/graphql.

При необходимости конечную точку можно вынести на отдельный порт — например, чтобы ограничить доступ к API на уровне сети. За это отвечают параметры server.graphql.port (номер порта) и server.graphql.context-path (путь контекста на отдельном порту).

Доступ к API

Доступ к API предоставляется администраторам Системы — пользователям, входящим в группу ROLE_SUPERUSER (см. Назначение роли пользователям). Запросы выполняются с правами администратора, действия фиксируются в журнале событий.

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

1. Установить значение параметра server.graphql.service-token — длинную случайную строку.

2. Передавать токен в каждом запросе в заголовке:

curl -s https://<SERVER>/dopusk/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SERVICE-TOKEN>" \
  -d '{"query": "{ users(limit: 2) { id name displayName blocked } }"}'

Токен предоставляет полный доступ к API, поэтому его значение хранится в защищенном хранилище (например, в секрете Docker или vault).

При обращении без допустимого токена и без сессии администратора Система возвращает ответ с кодом 401 и ошибкой UNAUTHENTICATED, а при сессии без прав администратора — код 403 и ошибку FORBIDDEN.

Выполнение запросов

Тело запроса — JSON с полем query, содержащим запрос GraphQL. Ответ возвращается в формате JSON: данные — в поле data, ошибки — в поле errors.

Получение списка пользователей с ограничением количества записей:

curl -s https://<SERVER>/dopusk/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SERVICE-TOKEN>" \
  -d '{"query": "{ users(limit: 2) { id name displayName blocked } }"}'

Ответ:

{
  "data": {
    "users": [
      {
        "id": "03772d6f-9f92-4820-bbb6-798cf4f99c64",
        "name": "test@test.ru",
        "displayName": "Тестовый пользователь",
        "blocked": false
      },
      {
        "id": "0465acda-b763-4cbd-a7ea-41c73af659d3",
        "name": "test2@test.ru",
        "displayName": "Пользователь2",
        "blocked": false
      }
    ]
  }
}

Отбор пользователей по точному значению поля и связанные объекты — директория и группы:

curl -s https://<SERVER>/dopusk/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SERVICE-TOKEN>" \
  -d '{"query": "{ users(filter: {name: \"<USER>\"}) { id name blocked directory { name } groups { name } } }"}'

Создание пользователя (мутация createUser). Идентификатор директории получается запросом directories:

curl -s https://<SERVER>/dopusk/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SERVICE-TOKEN>" \
  -d '{"query": "mutation { createUser(input: {name: \"<USER>\", firstName: \"Иван\", lastName: \"Петров\", password: \"<PASSWORD>\", directory: {id: <DIRECTORY-ID>}}) { id name } }"}'

Изменение пользователя по идентификатору (мутация updateUser) и удаление (мутация deleteUser):

curl -s https://<SERVER>/dopusk/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SERVICE-TOKEN>" \
  -d '{"query": "mutation { updateUser(input: {id: \"<USER-ID>\", blocked: true}) { id blocked } }"}'

curl -s https://<SERVER>/dopusk/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SERVICE-TOKEN>" \
  -d '{"query": "mutation { deleteUser(id: \"<USER-ID>\") }"}'

Для каждой модели операции именуются единообразно: create<Объект>, update<Объект>, delete<Объект> (например, createGroup, updateService, deleteDirectory).

Состав схемы API можно изучить интроспекционным запросом GraphQL — клиентские приложения (Insomnia, Postman, GraphQL Playground) загружают схему автоматически по адресу конечной точки. Один запрос возвращает не более 500 записей, лимит настраивается параметром server.graphql.max-query-rows-count. Для больших справочников используется постраничная выборка offset и limit.