Авторизация в сервисе подключаемой ВКС
Интеграция ИС ЗЯ с внешними системами, которой, в данном случае, является ИС ВКС, требует соблюдения предопределённых параметров безопасности. Авторизация осуществляется по логину и паролю, которые выдаются техническими специалистами ВКС. На основе пары логин-пароль формируется access_token и возвращается в качестве полезной нагрузки. Аутентификация для работы с сервисом, в дальнейшем, производится по нему. Значение времени жизни токена устанавливается на стороне ИС КС и не регламентируется со стороны ИС Золотого Яблока. При реализации механизма авторизации на стороне ИС КС необходимо самостоятельно определить минимально допустимый срок действия токена, достаточный для обеспечения стабильного выполнения интеграционных запросов. Полученный токен должен передаваться в каждом запросе к защищенным эндпоинтам в соответствии со схемой аутентификации Bearer Token, в HTTP-заголовке Authorization в следующем формате:
Authorization: Bearer <access_token>
Требование к URL
Эндпоинт должен быть опубликован по защищенному протоколу HTTPS. URL эндпоинта должен соответствовать следующей структуре пути: /api/v1/auth/login.
Допускается использование любого доменного имени, принадлежащего ИС КС. Полный URL формируется ИС КС и должен иметь следующий формат: https://<domain>/api/v1/auth/login
Требования к токену
Криптографическая функция - SHA256. Параметры пароля:
- буквы в верхнем и нижнем регистре
- цифры
- спецсимволы
- > 12 символов
На основе пары логин/пароль формируется JWT-токен. Это т.н. access токен. Параметры:
- время жизни - устанавливается на стороне ИС КС (минимально допустимый срок);
- подписание:
- secret key – криптостойкий ключ (набор символов, в кол-ве 32+);
- алгоритм - SHA256;
- издатель (Issuer) - <название вкс>
- потребитель (Audience) - goldapple
- валидация:
- времени жизни
- подписи
- полей Issuer и Audience
Основная информация
| Тип метода запроса | POST |
|---|---|
| Путь/URL | /api/v1/auth/login |
| Описание | Метод для аутентификации Единого АПИ Золотого яблока в ИС Курьерской службы |
| Направление | Запрос выполняется ИС Золотого Яблока. Ответ предоставляется курьерской службой. |
Запрос
Обязательные заголовки
| Параметр | Тип данных | Обязательность | Описание | Комментарий |
|---|---|---|---|---|
| Host | string | 1 | Хост Единого АПИ ЗЯ | Заполняется "subdomain.domain zone". |
| Content-Type | string | 1 | Тип содержимого запроса | Заполняется "application/json" |
Полезная нагрузка
| Параметр | Тип данных | Обязательность | Описание |
|---|---|---|---|
| username | string | 1 | Имя пользователя (логин), выданный Курьерской Службой |
| password | string | 1 | Пароль для аутентификации, выданный Курьерской Службой |
Пример запроса
{
"username": "Goldapple_UAPI",
"password": "*************"
}
Ответ
Коды ответов и сообщений
| Код | Статус | Сообщение | Причина |
|---|---|---|---|
| 200 | OK | Success response | Всё прошло успешно |
| 400 | Bad Request | Missing or inappropriate required parameters | Не переданы обязательные поля.В теле ответа должны быть указаны наименования полей, не прошедших валидацию, в произвольном формате строкой. |
| 500 | Internal Server Error | Server unavailable | Сервер недоступен |
Параметры успешного ответа
| Параметр | Тип данных | Обязательность | Описание |
|---|---|---|---|
| access_token | string | 1 | Access-token, выдаваемый по паре логин и пароль. |
| expires_in | string | 1 | Время жизни токена, указанное в секундах. |
Пример успешного ответа
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"expires_in": "2592000"
}
Параметры неуспешного ответа
| Параметр | Тип данных | Обязательность | Описание |
|---|---|---|---|
| error | string | 1 | Человекочитаемое сообщение об ошибке |
Неуспешный ответ
{
"error": "Missing or inappropriate required parameters"
}