Авторизация
API Aitu Passport работает по стандартам OAuth 2.0 и OpenID.
Обратите внимание!
Рекомендуем вам изучить стандарт OAuth2.0 если вы с ним не знакомы.
Ресурсы для изучения OAuth2.0 и OpenId Connect + видео
В графическом виде процесс OAuth2.0 выглядит следующим образом:
Авторизация в Aitu Passport
Пользователь инициирует процесс авторизации с помощью Aitu Passport, нажимая на соответствующую кнопку или ссылку в приложении Партнера.
Приложение Партнера генерирует ссылку с запросом авторизации (см. рисунок OAuth2.0 Workflow шаг 1) и перенаправляет Пользователя по данной ссылке в Aitu Passport. С методом генерации ссылки-запроса авторизации можно ознакомиться здесь. Важные моменты при формировании параметров для ссылки-запроса авторизации:
| Параметр | Обратите внимание что: |
|---|---|
redirect_uri | Значение, указанное в параметре redirect_uri в ссылке авторизации, должно быть идентично значению (одному из значений), указанному в параметре Redirect URI сервиса Партнера. Создание сервиса и описание параметра Redirect URI см. в статье "Создание сервиса Партнера" |
scope | В параметре scope должны быть указаны сервисы Aitu Passport, которые предоставят соответствующие данные Пользователя, приложению Партнера, информацию о сервисах см., в статье "Список сервисов Aitu Passport (scope)" |
state | Параметр может использоваться клиентом для поддержания состояния между запросом и ответом. Заданный state будет добавлен в качестве query parameter ( Минимальная длина значения - 8 символов. |
otp_confirmation | Параметр - опциональный. Может использоваться только теми Партнерами, у которых в договоре на предоставление услуг Aitu Passport указано, что проверку номера мобильного телефона Пользователя Партнер осуществляет самостоятельно. В случае, если в запросе авторизации будет передан данный параметр, то на стороне Aitu Passport Пользователь пропустит шаг ввода OTP. Значение для данного параметра предоставляет метод api/v1/trusted-phone. Описание метода см. здесь Внимание! Период жизни значения параметра otp_confirmation, полученного в методе api/v1/trusted-phone равен 60 минут. По истечению данного периода, значение для параметра otp_confirmation нужно получать заново. |
phone | Параметр - опциональный, при передаче параметра упрощается UX пользователя и пользователю не нужно будет вводить номер мобильного телефона на странице авторизации Aitu Passport. Формат передачи +7XXXXXXXXXX, где Х - это цифры 0-9. Важно! Если у пользователя в Aitu Passport ранее была создана сессия и номер мобильного телефона, полученный в данной сессии, отличается от номера, переданного в параметре phone текущего (нового) запроса авторизации, то сессия, созданная ранее, будет удалена и для пользователя начнется новый процесс авторизации с этапа ввода OTP из SMS. Внимание!
|
bin | БИН организации - данный параметр может использоваться для процесса подписания документов ОЭЦП юридического лица (scope ul_sign). В данном случае (scope ul_sign) указывается БИН организации от имени которой сотрудник будет подписывать документ (документы). |
iin_signature | Подписанный ИИН, передается в том случае если в настройках сервиса указан параметр "Публичный RSA ключ", на стороне системы партнера проведены работы по получению закодированного ИИН (значения для параметра iin_signature) и для сервиса, менеджером проекта включена настройка "Обязательный параметр iin_signature" Пример как получить параметр iin_signature: Зайти на сайт https://8gwifi.org/RSAFunctionality?rsasignverifyfunctions=rsasignverifyfunctions&keysize=1024 Скопировать из поля “Public Key” ключ и вставить его в поле “Публичный RSA ключ” в https://clients.passport.test.supreme-team.tech/ и нажать кнопку “Сохранить” Ввести в поле “ClearText Message” ИИН и выбрать алгоритм “SHA256withRSA”, находящийся в разделе “RSA Signature Algorithms”. Скопировать подписанный ИИН из поля “Signature Output” Перейти на сайт https://www.urlencoder.org/, вставить подписанный ИИН и нажать кнопку “ENCODE”. Скопировать закодированный подписанный ИИН. К oauth ссылке добавить параметры “iin” и “iin_signature” со значением закодированного подписанного ИИН Пример ссылки авторизации с параметрами “iin” и “iin_signature”: |
3. Пользователю откроется окно Aitu Passport, где он должен дать согласие на предоставление своих данных приложению Партнера. Пользователь проходит авторизацию и идентификацию, при необходимости вводя данные в сервисе Aitu Passport
4. После того, как Пользователь выполнит все действия на стороне Aitu Passport, Aitu Passport перенаправит Пользователя на ресурс, указанный в ссылке авторизации в параметре redirect_uri.
Если Пользователь подтвердил предоставление данных приложению Партнера, то Aitu Passport создаст одноразовый код авторизации. После генерации одноразового кода авторизации, Aitu Passport перенаправит Пользователя на ресурс, указанный в параметре redirect_uri ссылки авторизации, при этом, в качестве параметров будет указан код авторизации. Шаблон ответа Aitu Passport:
{redirect_uri}?code={code}&state={state}Если Пользователь в процессе авторизации нажал на кнопку "Отменить" или произошла другая ошибка, то Aitu Passport перенаправит Пользователя на ресурс, указанный в параметре redirect_uri ссылки авторизации, при этом, в качестве параметров будут указаны данные ошибки.
Шаблон ответа с ошибкой, зафиксированной Aitu Passport:
где:
redirect_uri - адрес uri, указанный в запросе авторизации в параметре redirect_uri. Параметр передается всегда
error - код ошибки. Параметр передается всегда
error_description - описание ошибки, список описаний ошибок см, здесь. Параметр передается всегда
scope - данные из параметра scope, переданные в запросе авторизации. Параметр передается всегда
cancel_reason - код ошибки, которая была зафиксирована последней в сессии пользователя перед принудительным завершением сессии. Передается только в том случае, если была зафиксирована ошибка. Опциональный параметр. Список ошибок, возвращаемых в параметре cancel_reason см., тут
cancel_stage - код этапа до которого дошел пользователь перед принудительным завершением сессии. Опциональный параметр.
cancel_request_id - уникальный идентификатор сессии. Опциональный параметр
5. Приложение Партнера, после получения кода авторизации (code) формирует запрос на получение токенов (access_token, id_token)., см. рисунок OAuth2.0 Workflow шаг 2. Для получения токена вызывается метод api/v1/oauth/token. Описание метода см. здесь
Внимание!
Получение токенов и все действия с токенами должны производится исключительно в серверной части приложения Партнера, так как для получения токенов требуется указывать секрет (client_secret).
Секрет (client_secret) запрещено хранить в клиентской части приложения!
Внимание!
Обменять код авторизации (code) на токены (access_token, id_token) можно только один раз! Период жизни кода авторизации (code) равен 5 мин
6. Aitu Passport генерирует токены (access_token, id_token) и возвращает их в ответе метода api/v1/oauth/token. Описание ответа метода см. здесь
Период жизни токена авторизации (access_token) равен 30 дней
7. Приложение Партнера, после получения access_token может отправлять запросы к Aitu Passport на получение бинарных данных Пользователя, перечисленных в параметре scope запроса авторизации, см. рисунок OAuth2.0 Workflow шаг 3. Все текстовые данные передаются в id_token.
Детально с процессом получения данных пользователя вы можете ознакомиться в статье "Получение данных Пользователя"
Связанные статьи:
Методы процесса авторизации
/oauth2/auth - метод генерации ссылки-запроса авторизации, получение кода авторизации (рисунок OAuth2.0 Workflow шаг 1)
/v1/trusted-phone - метод получения значения параметра otp_confirmation для /oauth2/auth
/oauth2/token - метод получения токенов (id_token, access_token) по коду авторизации (рисунок OAuth2.0 Workflow шаг 2)
Last updated
