Авторизация

API Aitu Passport работает по стандартам OAuth 2.0 и OpenID.

Обратите внимание!

Рекомендуем вам изучить стандарт OAuth2.0 если вы с ним не знакомы.

Ресурсы для изучения OAuth2.0 и OpenId Connect + видео

В графическом виде процесс OAuth2.0 выглядит следующим образом:

Схема процесса OAuth2.0

Авторизация в Aitu Passport

1. Пользователь инициирует процесс авторизации с помощью Aitu Passport, нажимая на соответствующую кнопку или ссылку в приложении Партнера.

2. Приложение Партнера генерирует ссылку с запросом авторизации (см. рисунок 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. Важно! Если у пользователя в 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”: http://localhost:4400/oauth2/auth?response_type=code&client_id=0551da04-dd66-4511-854f-fd7355c56861&scope=openid+idpc_verification&state=bakytgul&redirect_uri=https://www.google.com/&iin=111111111111&locale=ru&iin_signature=Ff441LSRHuBZ1bY1%2F8tFPx6x030rs%2FQhq6REG%2FVmAfHf5nMFWzMHVulta%2B2HSv1%2BVasWBmECPEWI%2F2tnpCLN6xZ4vrcmoOUu6PA33myWnu2JPvQWcXqYcw7mWMGcyIFrntlpmKjh%2FO7fIduaQ3ridrGtmczuouYSrEulc0JwiEI%3D

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.

Детально с процессом получения данных пользователя вы можете ознакомиться в статье "Получение данных Пользователя"

Связанные статьи:

• Список сервисов Aitu Passport (scope)

• Создание сервиса Партнера

• Получение данных Пользователя

Методы процесса авторизации

• /oauth2/auth - метод генерации ссылки-запроса авторизации, получение кода авторизации (рисунок OAuth2.0 Workflow шаг 1)

  • /v1/trusted-phone - метод получения значения параметра otp_confirmation для /oauth2/auth

• /oauth2/token - метод получения токенов (id_token, access_token) по коду авторизации (рисунок OAuth2.0 Workflow шаг 2)