API управления пользователями
API для управления пользователями (субъектами доступа) в MULTIFACTOR.
Перед использованием данного API необходимо включить расширенное API в личном кабинете, в разделе "Настройки API" и использовать API Key и API Secret, предоставленные в разделе.
Управление пользователями
Количество пользователей и лицензий
Адрес https://api.multifactor.ru/users/count | метод GET.
Функция для запроса текущей утилизации лицензий в системе MULTIFACTOR.
Пример запроса:
GET https://api.multifactor.ru/users/count
Пример ответа:
{
"model": {
total: 5000, //количество пользователей
limit: 6000 //количество лицензий
},
"success": true,
"message": null
}
Список пользователей
Адрес https://api.multifactor.ru/users | метод GET.
Пример запроса:
GET https://api.multifactor.ru/users
Для поиска конкретного пользователя по логину используйте параметр запроса Identity:
GET https://api.multifactor.ru/users?identity=user@example.com
Для включения в ответ сервера номеров телефонов пользователей (при наличии), используйте параметр запроса withPhones со значением true:
GET https://api.multifactor.ru/users?withPhones=true
Пример ответа:
{
"model": [ //список пользователей
{
"id": "5e3c1058c3a23e55b0579ded", //id пользователя в MULTIFACTOR
"identity": "user@example.com", //логин пользователя в вашей системе
"name": null,
"email": null,
"isEnrolled": true, //второй фактор настроен
"createdAt": "2020-02-06T13:10:48.139Z",
"lastLogin": "2021-06-01T15:42:46.786Z",
"isLocked": false,
"groups": [ //группы, в которых состоит пользователь
"AllUsers",
"Super Admin Web"
],
"authenticators": [ //настроенные способы аутентификации
"Telegram"
],
}
],
"success": true,
"message": null
}
Регистрация пользователя
Адрес https://api.multifactor.ru/users | метод POST.
Пользователи регистрируются автоматически при первом посещении страницы доступа, но также предусмотрен вариант регистрации через API.
Пример запроса:
{
"Identity": "user@example.com", //логин пользователя в вашей системе
"Email": "user@example.com", //e-mail, необязательно
"Phone": null, //телефон, необязательно
"Name": "User Name", //имя, необязательно
"EnrollmentLink": //отправить ссылку для настройки, необязательно
{
"To": "email", //на почту, указанную выше
"Ttl": 90 //со сроком действия 90 минут
},
"Groups": {
"Add": ["Group1 name", "Group2 name"] //добавить пользователя в группы (необязательно)
}
}
Пример ответа: пользователь зарегистрирован
{
"model": {
"id": "5e3c1058c3a23e55b0579ded",
"identity": "user@example.com",
"name": "User Name",
"email": "user@example.com",
"isEnrolled": false,
"createdAt": "2020-03-05T11:55:43.8001916Z",
"lastLogin": null,
"isLocked": false
},
"success": true,
"message": null
}
Изменение данных пользователя
Адрес https://api.multifactor.ru/users/{id} | метод PUT.
- Параметр id — идентификатор пользователя.
Используется для изменении данных, блокировки и разблокировки пользователя.
Пример запроса:
{
"Identity": "user@example.com", //если нужно изменить логин
"Name": "User Name", //если нужно изменить имя
"Email": "user@example.com", //если нужно изменить адрес
"IsLocked": true, //если нужно заблокировать
"Groups": {
"Add": ["Group1 name", "Group2 name"], //если нужно добавить пользователя в группы
"Remove": ["Group3 name", "Group4 name"], //если нужно исключить пользователя из групп (необязательно)
}
}
Пример ответа:
{
"model": {
"id": "5e3c1058c3a23e55b0579ded",
"identity": "user@example.com",
"name": "User Name",
"email": "user@example.com",
"isEnrolled": false,
"createdAt": "2020-03-05T11:55:43.8001916Z",
"lastLogin": null,
"isLocked": true
},
"success": true,
"message": null
}
Удаление пользователя
Адрес https://api.multifactor.ru/users/{id} | метод DELETE.
- Параметр id — идентификатор пользователя.
Пример запроса:
DELETE https://api.multifactor.ru/users/1234567890
Пример ответа:
{
"success": true,
"message": null
}
Ссылка для настройки второго фактора
Адрес https://api.multifactor.ru/users/{id}/enroll | метод POST.
- Параметр id — идентификатор пользователя.
Функция для генерации и отправки на email пользователя ссылки для настройки второго фактора. Если не указать параметр Email, ссылка будет сгенерирована без отправки письма пользователю и возвращена в ответе сервера.
Пример запроса:
{
"Email": "user@example.com", //[опционально] адрес, куда отправить письмо,
"Ttl": 90 //срок действия ссылки (90 минут)
}
Пример ответа:
{
"success": true,
"message": null
}
Управление аутентификаторами
Подключенные способы аутентификации
Адрес https://api.multifactor.ru/users/{id}/authenticators | метод GET.
Параметры:
- id — идентификатор пользователя.
Пример запроса:
GET https://api.multifactor.ru/users/1234567890/authenticators
Пример ответа:
{
"model": {
"Telegram": [
{
"id": "627d3d4f410ae00ede026358",
"name": "User Name"
}
],
"TotpToken": [
{
"id": "627e7ffec027bb87054ea6e3",
"name": "Яндекс.Ключ"
},
{
"id": "627e8041c027bb87054ea6e4",
"name": "Microsoft"
}
],
"HotpToken": [
{
"id": "62829fb2e0270cb2ea95208c",
"name": "YubiKey 1234567"
}
]
},
"success": true,
"message": null
}
Переименование аутентификатора
Адрес https://api.multifactor.ru/users/{id}/authenticators/{type}/{authenticatorid} | метод PUT.
Параметры:
- id — идентификатор пользователя;
- type — способ аутентификации;
- authenticatorid — идентификатор аутентификатора.
Пример запроса:
PUT https://api.multifactor.ru/users/1234567890/authenticators/hotptoken/23456789
Параметры в теле запроса:
{
"Name": "Синий рутокен"
}
Пример ответа:
{
"success": true,
"message": null
}
Удаление аутентификатора
Адрес https://api.multifactor.ru/users/{id}/authenticators/{type}/{authenticatorid} | метод DELETE.
Параметры:
- id — идентификатор пользователя;
- type — способ аутентификации;
- authenticatorid — идентификатор аутентификатора.
Пример запроса:
DELETE https://api.multifactor.ru/users/1234567890/authenticators/telegram/23456789
Пример ответа:
{
"success": true,
"message": null
}
Можно также вызвать данную функцию без указания authenticatorid. В таком случае будут удалены все настроенные аутентификаторы указанного способа.
Пример запроса:
DELETE https://api.multifactor.ru/users/1234567890/authenticators/telegram
Пример ответа:
{
"success": true,
"message": null
}
Регистрация OTP токена
Адрес https://api.multifactor.ru/users/{id}/authenticators/{type} | метод POST.
Параметры:
- id — идентификатор пользователя;
- type — тип токена:
- totptoken — TOTP токен;
- hotptoken — HOTP токен.
Поддерживаемые алгоритмы хэширования:
- TOTP-токен: SHA-1 (6 цифр);
- HOTP-токен: SHA-1, SHA-256, SHA-512 (6 цифр).
Пример запроса:
POST https://api.multifactor.ru/users/1234567890/authenticators/hotptoken
Параметры в теле запроса:
{ //пример регистрации Rutoken OTP
"Name": "Rutoken HOTP", //произвольное название
"Key": "673c7514b68e8f09707cc6a4321aa76673a688d4" //ключ в hex кодировке
}
Еще пример:
{ //пример регистрации YubiKey OTP
"Name": "YubiKey 1234567", //произвольное название
"Key": "9b617117c2a4862f47caf4fb2e4032ac", //ключ в hex кодировке
"PrivateId": "2fc5120aca42" //uid в hex кодировке
}
Пример ответа:
{
"success": true,
"message": null
}
Перемещение OTP токена
Адрес https://api.multifactor.ru/users/{id}/authenticators/{type}/{tokenid} | метод PUT.
Параметры:
- id — идентификатор пользователя;
- type — тип токена:
- totptoken — TOTP токен;
- hotptoken — HOTP токен;
- tokenid — идентификатор токена.
Функция для перемещения OTP токена между пользователями. При перемещении токен открепляется от старого пользователя и прикрепляется в качестве метода аутентификации к целевому пользователю.
Пример запроса:
PUT https://api.multifactor.ru/users/1234567890/authenticators/hotptoken/23456789
Параметры в теле запроса:
{
"user": "1234567890", //идентификатор целевого пользователя
"name": "Белый рутокен" //[опционально] новое название аутентификатора
}
Пример ответа:
{
"success": true,
"message": null
}
Копирование OTP токена
Адрес https://api.multifactor.ru/users/{id}/authenticators/{type}/{tokenId} | метод PATCH.
Параметры:
- id — идентификатор пользователя;
- type — тип токена:
- totptoken — TOTP токен;
- hotptoken — HOTP токен;
- tokenid — идентификатор токена.
Функция для копирования OTP токена исходного пользователя одному или нескольким целевым пользователям. При копировании токен не открепляется у исходного пользователя.
Пример запроса:
PATCH https://api.multifactor.ru/users/1234567890/authenticators/hotptoken/23456789
Параметры в теле запроса:
{
"users": [
"1234567890", //идентификатор целевого пользователя 1
"1234567890" //идентификатор целевого пользователя 2
]
}