TOTP.md
Назначение
Непосредственным назначением TOTP сервиса является работа с TOTP кодами. С помощью данного сервиса осуществляется создание TOTP аккаунта, его дезактивация, активация, проверка правильности TOTP кода для заданного пользователя.
Выполняемые функции
- Создание TOTP аккаунта
- Проверка TOTP кода
- Дезактивация TOTP аккаунта
- Активация TOTP аккаунта
- Верификация TOTP URL
Создание TOTP аккаунта (Enroll)
Для выполнения работы данной функции необходимы название аккаунта пользователя и ID пользователя, для которого будет создаваться TOTP аккаунт.
После создания аккаунта выдаётся TOTP URL, который затем можно использовать для привязки к мобильным приложениям генерации TOTP кодов, такие как Google Auth. или Microsoft Auth.
Вместе с URL выдаётся TOTP ID, для возможности привязки TOTP аккаунта внешними сервисами.
Сценарии
- Некорректные выходные данные
- Нет одного из полей или оба поля отсутствуют в теле запроса: 400
- Некорректный USER ID: 500
-
Корректные входные данные
{
"user_id": "USER ID",
"user_name": "ACCOUNT NAME"
}
Выходные
- Удачный результат выполнения операции
{
"totp_id": "TOTP ID",
"totp_secret": "TOTP SECRET",
"totp_url": "TOTP URL"
}
- Внутренние ошибки
{
"status": 500,
"error": "Internal Server Error"
}
- Ошибки входного json или ошибки, связанные с выполнением создания TOTP аккаунта
{
"status": 400,
"error": "Описание ошибки"
}
Проверка TOTP кода (Validate)
Для выполнения работы данной функции необходимы TOTP код и ID пользователя, для которого будет сравниваться TOTP код.
После выполнения операции будет получен положительный ответ или ошибка с ёё описанием.
Сценарии
- Некорректные выходные данные
- Нет одного из полей или оба поля отсутствуют в теле запроса: 400
- Некорректный USER ID: 500
-
Корректные входные данные
{
"user_id": "USER ID",
"totp_code": "TOTP CODE"
}
Выходные
- Удачный результат выполнения операции
{
"status": "OK"
}
- Внутренние ошибки
{
"status": 500,
"error": "Internal Server Error"
}
- Ошибки входного json
{
"status": 400,
"error": "ОПИСАНИЕ ОШИБКИ"
}
- Ошибки, связанные с выполнением проверки TOTP кода
{
"status": "ОПИСАНИЕ ОШИБКИ"
}
Дезактивация TOTP аккаунта (Disable)
Для выполнения работы данной функции необходимы TOTP ID и/или ID пользователя. Если переданы оба ID и указанным TOTP ID не владеет пользователь с USER ID, то такие данные считаются ошибочными. Наиболее приоритетным является TOTP ID, это значит, что при наличии обоих ID поиск будет осуществляться для TOTP ID.
Сценарии
- Некорректные выходные данные
- Нет обоих полей: 400
- Один или оба ID некорректны: 500
-
Корректные входные данные
- Только USER ID
- Не существует TOTP аккаунта для данного ID: 404
- Нет активного TOTP для данного ID: 400
- Есть активный TOTP для данного ID: 200
- Только TOTP ID
- Не существует TOTP аккаунта для данного ID: 404
- Нет активного TOTP для данного ID: 400
- Есть активный TOTP для данного ID: 200
-
Есть оба ID
- Только USER ID
{
"user_id": "USER ID",
"totp_id": "TOTP ID"
}
Выходные
- Удачный результат выполнения операции
{
"status": "OK"
}
- Внутренние ошибки
{
"status": 500,
"error": "Internal Server Error"
}
- Ошибки входного json
{
"status": 400,
"error": "ОПИСАНИЕ ОШИБКИ"
}
- Ошибки, связанные с дезактивацией TOTP
{
"status": "ОПИСАНИЕ ОШИБКИ"
}
Активация TOTP аккаунта (Enable)
Для выполнения работы данной функции необходимы TOTP ID и/или ID пользователя. Если переданы оба ID и указанным TOTP ID не владеет пользователь с USER ID, то такие данные считаются ошибочными. Наиболее приоритетным является TOTP ID, это значит, что при наличии обоих ID поиск будет осуществляться для TOTP ID.
Сценарии
- Некорректные выходные данные
- Нет обоих полей: 400
- Один или оба ID некорректны: 500
-
Корректные входные данные
- Только USER ID
- Не существует TOTP аккаунта для данного ID: 404
- TOTP для данного ID уже активен: 400
- Нет активных TOTP для данного ID: 200
- Только TOTP ID
- Не существует TOTP аккаунта для данного ID: 404
- TOTP для данного ID уже активен: 400
- Нет активных TOTP для владельца данного TOTP ID: 200
-
Есть оба ID
- Только USER ID
{
"user_id": "USER ID",
"totp_id": "TOTP ID"
}
Выходные
- Удачный результат выполнения операции
{
"status": "OK"
}
- Внутренние ошибки
{
"status": 500,
"error": "Internal Server Error"
}
- Ошибки входного json
{
"status": 400,
"error": "ОПИСАНИЕ ОШИБКИ"
}
- Ошибки, связанные с активацией TOTP
{
"status": "ОПИСАНИЕ ОШИБКИ"
}
Верификация TOTP URL (Verify)
Для выполнения работы данной функции необходима TOTP URL. Предоставленная URL будет проверяться на наличие соответствующих полей TOTP, таких как секрет, алгоритм, владелец, период действия TOTP кода, число цифр TOTP кода.
Сценарии
- Некорректные выходные данные
- Нет поля url: 400
-
Корректные входные данные
{
"totp_url": "TOTP URL"
}
Выходные
- Удачный результат выполнения операции
{
"status": "OK"
}
- Внутренние ошибки
{
"status": 500,
"error": "Internal Server Error"
}
- Ошибки входного json
{
"status": 400,
"error": "ОПИСАНИЕ ОШИБКИ"
}
- Ошибки, связанные с верификацией URL
{
"status": "ОПИСАНИЕ ОШИБКИ"
}