Авторизация
API Aitu Passport работает по стандартам OAuth 2.0 и OpenID.
В графическом виде процесс 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 (state) в redirect_uri, на который будет перенаправлен Пользователь после разрешения доступа к данным на стороне Aitu Passport.
Минимальная длина значения - 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.
Важно! Передача данного параметра предусмотрена для того чтобы облегчить путь пользователя. Значением из данного параметра предзопалняется поле "Номер мобильного телефона" на экране ввода номера мобильного телефона, при этом редактирование номера мобильного телефона доступно! Это значит, что пользователь в процессе работы с AituPassport может указать другой номер мобильного телефона, не тот который передал партнер в параметре phone
Важно! Если у пользователя в Aitu Passport ранее была создана сессия и номер мобильного телефона, полученный в данной сессии, отличается от номера, переданного в параметре phone текущего (нового) запроса авторизации, то сессия, созданная ранее, будет удалена и для пользователя начнется новый процесс авторизации с этапа ввода OTP из SMS.
bin
БИН организации - данный параметр может использоваться для процесса подписания документов ОЭЦП юридического лица (scope ul_sign). В данном случае (scope ul_sign) указывается БИН организации от имени которой сотрудник будет подписывать документ (документы).
iin
Параметр - опциональный, при передаче параметра упрощается UX пользователя и пользователю не нужно будет вводить ИИН на странице авторизации Aitu Passport.
Важно! Передача данного параметра предусмотрена для того чтобы облегчить путь пользователя. Значением из данного параметра предзопалняется поле "ИИН" на экране ввода ИИН-а, при этом редактирование ИИН доступно! Это значит, что пользователь в процессе работы с AituPassport может указать другой ИИН, не тот который передал партнер в параметре iin.
Если вы хотите чтобы у пользователя не было возможности редактировать ИИН, то вместо данного параметра воспользуйтессь параметром iin_signature
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”:
id_user_session
Уникальный идентификатор сессии Пользователя в системе партнера, предназначен для добавления в события для аналитики данных Aitu Passport. Получение системами Партнеров событий для аналитики данных см, статью Получение событий для аналитики данных
3. Пользователю откроется окно Aitu Passport, где он должен дать согласие на предоставление своих данных приложению Партнера. Пользователь проходит авторизацию и идентификацию, при необходимости вводя данные в сервисе Aitu Passport
Обратите внимание, на следующие ограничения:
Срок жизни OTP, для подтверждения номера мобильного телефона - 330 секунд
Максимальное количество ошибок, которое можно допустить при вводе одного OTP - 5 , если они исчерпаны, то нужно запросить новый OTP;
OTP допускается запрашивать раз в две минуты
Количество раз отправки SMS c OTP не ограничено
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}?error={error_code}&error_description={description}&scope={scopes}&cancel_reason={cancel_reason}&cancel_stage={cancel_reason}&cancel_request_id={cancel_request_id}где:
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
Was this helpful?