Авторизация
Last updated
Last updated
API Aitu Passport работает по стандартам OAuth 2.0 и OpenID.
Обратите внимание!
Рекомендуем вам изучить стандарт OAuth2.0 если вы с ним не знакомы.
Ресурсы для изучения OAuth2.0 и OpenId Connect + видео
В графическом виде процесс OAuth2.0 выглядит следующим образом:
Пользователь инициирует процесс авторизации с помощью Aitu Passport, нажимая на соответствующую кнопку или ссылку в приложении Партнера.
Приложение Партнера генерирует ссылку с запросом авторизации (см. рисунок OAuth2.0 Workflow шаг 1) и перенаправляет Пользователя по данной ссылке в Aitu Passport. С методом генерации ссылки-запроса авторизации можно ознакомиться здесь. Важные моменты при формировании параметров для ссылки-запроса авторизации:
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}?error={error_code}&error_description={description}. Описание ошибок см, здесь
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)
| Параметр | Обратите внимание что: |
|---|---|
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.
Важно! Если у пользователя в Aitu Passport ранее была создана сессия и номер мобильного телефона, полученный в данной сессии, отличается от номера, переданного в параметре phone текущего (нового) запроса авторизации, то сессия, созданная ранее, будет удалена и для пользователя начнется новый процесс авторизации с этапа ввода OTP из SMS.
Внимание!
срок жизни SMS кода 300 секунд;
максимальное количество попыток ввода одного отправленного кода 5, если они исчерпаны нужно запросить новый код;
код допускается запрашивать раз в две минуты;
общее количество запроса 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”:
