Аутентификация¶
Настоятельно рекомендуется для вашей же безопасности при реализации автоматической работы по API создавать для этих целей отдельный саблогин с максимально ограниченными правами и использовать для его работы ключ API или JWT-токены !
Аутентификация по логину и паролю¶
Полученный в ответ идентификатор сессии должен передаваться во всех последующих запросах (кроме запросов "ping" и "login", в которых он игнорируется) как описано ниже.
Время жизни сессии несколько часов. Рекомендуется завершать явным вызовом "logout".
В случае окончания времени действия сессии вы получите ответ об ошибке аутентификации, а запрошенное действие не будет выполнено.
Для продолжения работы будет необходимо:
-
Получить новую сессию (автоматически или заново, запросив логины и пароль у пользователя),
-
Повторить заново вызов, на котором произошла ошибка аутентификации, так как он не был выполнен.
ответ
{
<общие поля>
,"session" : "номер сессии"
,"login" : "общий логин для которого выдана аутентификация"
,"sublogin" : "личный логин для которого выдана аутентификация"
}
Полученный в ответ идентификатор сессии должен передаваться во всех последующих запросах (кроме запросов "ping" и "login", в которых он игнорируется) или в самом запросе:
или в HTTP заголовке Authorization:
Двухфакторная аутентификация по логину и паролю¶
Второй фактор - код из смс.
Предварительно, требуется установить саблогину способ аутентификации "2fasms" и номер телефона через вызов sys.user.set/sys.user.create
Аутентификация начинается обычным вызовом login
однако ответ содержит inactive : 1 и 2fa
{
<общие поля>
,"session" : "номер сессии"
,"login" : "общий логин для которого выдана аутентификациия"
,"sublogin" : "личный логин для которого выдана аутентификация"
,"inactive" : 1 -- выданная сессия не активна
,"2fa" : {
"via" : "2fasms" -- требуется 2FA через смс
,"ttl" : 180 -- срок валидности кода из смс
,"trys" : 3 -- количество попыток ввода
}
}
Для продолжения требуется указать код из смс в вызове login.2fa
{
"action" : "login.2fa"
,"session" : "......" -- сессия из ответа login
,"2fa" : {
"via" : "2fasms" -- значение 2fa.via из ответа login
,"secret" : "xxxx" -- код из смс. строка.
}
}
ответ
{
"session" : "номер сессии" -- активная сессия
,"login" : "общий логин для которого выдана аутентификация"
,"sublogin" : "личный логин для которого выдана аутентификация"
}
Дальнейшее использования полученной активной сессии аналогично описанному ранее.
Аутентификация через OpenID¶
Требуется настроить параметры вашего сервера OpenID через службу поддержки.
Параметры едины для всех саблогинов.
Конктрентый саблогин выбирается по email полученному из OpenID - установите его сабологину через sys.user.set
Если такой email имеет не один саблогин, то аутентификация не удастся.
Права саблогина настраиваются по прежнему тут через API - они не берутся из OpenID.
При окончании срока действия сессии необходимо опять получить redirect_url и отправить туда пользователя
ответ
{
... прочие поля....
"inactive" : 1, <--- !
"session" : "неактивная сессия",
"via" : "openid", <----- !
"2fa" : {
"ttl" : 180, -- срок действия сессии без активации
"redirect_url" : "url" -- куда отправить пользователя для продолжения
}
}
После ухода на redirect_url пользователь пообщавшись с сервером OpenID окажется в интерфейсе с уже активной сессией.
Аутентификация по ключу api¶
Создайте заранее ключ api для саблогина вызовом sys.user.apikey.create.
Аутентификация заканчивается c окончанием вызова и завершения вызовом "logout" не требует.
Процессы, порождённые асинхронными вызовами, продолжат работать до их естественного завершения.
Для использования ключа api укажите его:
- или в самом запросе:
- или в HTTP заголовке Authorization:
Аутентификация c JWT¶
Требования к токену:
-
соответствие RFC 7519https://datatracker.ietf.org/doc/html/rfc7519
-
поддерживаются алгоритмы RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512
-
содержимое полезной нагрузки учитываемое при аутентификации
{
"account" : "код аккаунта"
,"sublogin" : "саблогин" -- не обязательно
,"exp" : целое число -- обязателен. timestamp момента окончания действия. использование интервалов менее 5 минут снизит эффективность работы
,"nbf" : целое число -- не обязательно, проверяется при наличии
}
-
после генерации пары приватный-публичный ключ сообщите Службе поддержки публичный ключ в формате PEM для внесения в настройки
-
провереный пример генерации пары RSA-ключей:
- для работы с api генерируйте jwt с использованием своего приватного ключа и предпочитаемого exp
Для использования jwt-токены укажите его:
- или в самом запросе:
Передаётся в параметре apikey с приставкой "jwt:'
- или в HTTP заголовке Authorization:
Окончание работы¶
Текущая сессия становится не действительной:
ответ:
Логины и пароли в ссылках¶
Многие вызовы api могут получать данные, осуществляя доступ по http(s)/ftp(s) к сторонним серверам.
Хорошей практикой будет требовать логин-пароль при доступе к таким данным.
Однако использование стандартной для такого случая схемы записи ссылки с указанием логина-пароля прямо в ней
хоть и, разумеется, поддерживается, но не является полностью безопасным. Например, при работе нескольких сотрудников с аккаунтом, все они смогут увидеть логин-пароль, если он указан в действиях по расписанию или в отложенных выпусках.
Создайте один раз объект "Внешняя аутентификация" (вызов authext.create, type = 0, login = "метка для памяти", "token" = "логин:пароль") и используйте его номер в ссылках в виде: