По сертификату (obsolete)

Важно

Данный способ аутентификации через auth.sid будет поддерживаться для реализованных интеграций. Для новых интеграций нужно использовать аутентификацию по протоколу OpenId Connect.

../_images/По-серту.jpg

Важно

Аутентификация по сертификату двухшаговая.

1. Инициализация:

  • Пользователь присылает объект идентификации - сертификат (cert). Сервер идентифицирует его и находит нужный userID.

  • Для userID генерируется случайное значение - rnd. Сервер шифрует rnd (получаем enc(rnd)) на сертификат пользователя и отправляет ему.

Запрос:

POST /auth/v5.13/authenticate-by-cert?free=value&apiKey=value

Где:

  • free - булевый флаг, который говорит проверять или нет валидность сертификата (true - не проверять, по умолчанию - false);

  • apiKey - api-key (obsolete).

Тело запроса:

сертификат в PEM-формате.

Ответ:

  • EncryptedKey - зашифрованная случайная строка. Возвращается в кодировке Base-64. Для корректной расшифровки требуется декодировать ее из Base-64.

  • Link - объект, который описывает ссылку для подтверждения запроса аутентификации:

    • Link.Rel - описание ссылки,

    • Link.Href - адрес ссылки.

Коды ответов:

  • 200(OK) - запрос выполнен успешно.

  • 400(Bad Request) - отсутствуют необходимые параметры.

  • 403(Forbidden).

  • 406(Not Acceptable), причин может быть несколько:

    • один из сертификатов цепочки имеет неверную подпись;

    • истек либо не наступил срок действия сертификата;

    • цепочка сертификатов основана на не доверенном корневом сертификате.

  • 500(InternalServerError).

2. Подтверждение:

  • Пользователь, получив enc(rnd), расшифровывает его (получаем dec(enc(rnd))) и отправляет результат серверу.

  • Если dec(enc(rnd)) равен rnd, то сервер возвращает auth.sid

Запрос:

POST /auth/v5.13/approve-cert?thumbprint=value&apiKey=value

Где:

  • thumbprint - отпечаток сертификата, используемого для аутентификации;

  • apiKey - api-key (obsolete).

Тело запроса:

расшифрованный сертификатом пользователя EncryptedKey в байтах.

Ответ:

  • Sid - идентификатор сессии auth.sid (obsolete).

  • RefreshToken - ключ, необходимый для продления созданной сессии.

Коды ответов:

  • 200(OK) - запрос выполнен успешно.

  • 400(Bad Request) - отсутствует thumbprint.

  • 403(Forbidden).

  • 500(InternalServerError).

3. Продление сессии

При истечении времени жизни auth.sid необходимо его обновить, это можно сделать двумя способами:

  • пройти заново предыдущие два шага аутентификации по сертификату;

  • воспользоваться запросом ниже.

Запрос:

POST /sessions/v5.13/sessions/refresh?auth.sid=value&refresh-token=value&api-key=value

Где:

  • auth.sid - обновляемая сессия;

  • refresh-token - токен, соответствующий обновляемой сессии;

  • api-key - api-key (obsolete).

Ответ:

  • Sid - идентификатор сессии auth.sid (obsolete).

  • RefreshToken - ключ, необходимый для продления созданной сессии.

Коды ответов:

  • 200(OK) - запрос выполнен успешно.

  • 400(Bad Request) - отсутствует thumbprint.

  • 403(Forbidden) - неподходящий api-key или refresh-token.

  • 500(InternalServerError).

  • 503(ServiceUnavailable) - внутренние сервисы не отвечают.

Примечание

  • Для удобства проверки у rnd будет префикс равный userID.

  • rnd живет 10 минут.

  • У каждого пользователя один свой уникальный rnd.

  • После успешной аутентификации rnd удаляется.

  • enc(rnd) передается в формате PKCS#7.

  • Время жизни auth.sid 30 дней.

  • Время жизни refresh-token 45 дней.

  • Отдельно отметим, что продление сессии (п.3) происходит в отдельном location работы с сессиями.

  • После продления сессии (п.3) auth.sid и refresh-token старой сессии становятся недействительными.