Рекомендации по реализации интеграции

Для использования сервиса аутентификации личности клиента FinID необходимо, чтобы Участник:

1. Прошел процедуру регистрации на Портале АО «НПК» (см. подробнее в Регистрация и вход)

2. Подал заявку на подключение к ЦОИД (см. подробнее в Подключение к ЦОИД)

3. Зарегистрировал приложение Участника (см. подробнее в Управление API и приложениями)

Аутентификацию могут пройти люди, у которых имеется как минимум один из следующих документов:

• удостоверение личности гражданина РК

• паспорт гражданина РК

• вид на жительство иностранца в РК

• удостоверение лица без гражданства (казахстанского образца)

Общее описание процесса:

Общая диаграмма взаимодействия

1. Пользователь инициирует получение услуги в приложении Участника, для которой требуется проведение аутентификации личности.

2. Для проведения двухфакторной аутентификации приложение Участника перенаправляет пользователя на Cервис аутентификации личности клиента FinID.

Если в ОС Android при проведении liveness-сессии не отображается изображение клиента (см. пример на рисунке ниже), то потенциальным решением проблемы может являться применение следующих параметров:

webView.settings.allowContentAccess = true; webView.settings.mediaPlaybackRequiresUserGesture = false; webView.settings.domStorageEnabled = true

WebKit в Android, позволяет видео компонентам запускаться только по действию пользователя, при этом для корректной работы сервисов ЦОИД камера запускается программными средствами (autoplay), WebKit блокирует данное действие и выдает ошибку. Чтобы избежать этого, необходимо в компоненте webView указать данную настройку.

Пример отсутствия доступа к контенту для WebView

В IOS необходимо использовать SafariWebView. WKWebView не поддерживается.

Перенаправления пользователя для прохождения аутентификации

Для перенаправления пользователя для прохождения аутентификации Участнику необходимо:

1) Реализовать получение URL-адреса для перенаправления Клиента. Описание метода «Получить URL-адрес для перенаправления клиента д» (POST /v1/auth/generate-user-url) приведено в https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrl.

Примечание: Метод получения URL-адрес для перенаправления клиента POST /oauth2/generate-user-url (см. https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrlDeprecated) является устаревшим, рекомендуется перейти на использование метода POST /v1/auth/generate-user-url (см. https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrl).

2) Реализовать перенаправление пользователя на полученный URL-адрес.

То какая услуга ЦОИД должна быть предоставлена определяется значениями, указанными в параметре scopes при запросе URL-адреса для перенаправления пользователя в ЦОИД:

Получение персональных данных:

• iin - доступ к ИИН пользователя

• full_name - доступ к ФИО пользователя

• first_name - доступ к имени пользователя

• last_name - доступ к фамилии пользователя

• middle_name - доступ к отчеству пользователя

• date_of_birth - доступ к дате рождения пользователя

• place_of_birth - доступ к месту рождения пользователя (описание объекта в 1. Структура объекта «place_of_birth» (место рождения))

• gender - доступ к полу пользователя (описание объекта см. в 4. Структура объектов «country», «district», «region», «gender», «nationality», «document_issue_place», «document_type»)

• nationality - доступ к национальности пользователя (описание объекта см. в 4. Структура объектов «country», «district», «region», «gender», «nationality», «document_issue_place», «document_type»)

• registration_address - доступ к адресу регистрации пользователя (описание объекта см. в 3. Структура объекта «registration_address» (адрес регистрации))

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

• document_type - доступ к типу документа, удостоверяющего личность пользователя (описание объекта см. в 4. Структура объектов «country», «district», «region», «gender», «nationality», «document_issue_place», «document_type»)

• document_issue_date - доступ к информации о дате выдачи документа, удостоверяющего личность пользователя

• document_expiry_date - доступ к дате истечения срока действия документа, удостоверяющего личность пользователя

• document_issue_place - доступ к информации о том, кем был выдан документ, удостоверяющий личность пользователя (описание объекта см. в 4. Структура объектов «country», «district», «region», «gender», «nationality», «document_issue_place», «document_type»)

Верификация физического лица:

• openid - если необходима только верификация личности пользователя (без предоставления доступа к персональным данным), то в параметре scopes должно быть указано только значение openid

Примечание: Описание объектов см. в Описание объектов

Время действия URL-адреса для перенаправления (время «жизни») составляет 15 минут

3. Пользователю отображается форма аутентификации ЦОИД. Пользователь проходит двухфакторную аутентификацию личности.

4. Пользователь должен дать согласие на доступ к его данным для приложения Участника.

Пользователь может отклонить согласие на доступ к его данным.

Если Пользователь отклоняет согласие на доступ к его данным или происходит ошибка, то Пользователь будет перенаправлен на указанный на шаге 2 redirectUri, с указанием кода ошибки, по следующему шаблону:

[redirectUri]?errorCode=[error code]&state=[state]

В таком случае процесс завершается, код авторизации не предоставляется.

5. После того, как Пользователь выполнит все действия на стороне ЦОИД, осуществляется его возврат в приложение Участника.

Если аутентификация Пользователя проходит успешно и он дает согласие на доступ к его данным, то Пользователь перенаправляется обратно в приложение Участника (на указанный в запросе redirectUri) с одноразовым кодом авторизации (code), по следующему шаблону:

[redirectUri]?code=[authorization code]&state=[state]

Код авторизации является одноразовым.

Время действия кода авторизации (время «жизни») составляет 300 секунд

Редирект из webview в случае SafariWebView нужно перехватывать через диплинк (deeplink)

6. Приложение Участника получает результат аутентификации, используя полученный на предыдущем шаге код авторизации.

Получение результата аутентификации

Для получения результата аутентификации Участнику необходимо:

1) Реализовать формирование запроса получения результата аутентификации клиента, используя полученный код авторизации. Описание используемого для этого метода приведено в https://auth-openapi.npck.kz/#tag/Auth/operation/getOauthToken.

2) Реализовать отправку сформированного запроса и получение результата аутентификации клиента.

В результате успешной аутентификации предоставляется идентификационный токен (в формате JWT, см. RFC 7519), в котором, в том числе, в полезной нагрузке (payload) содержатся персональные данные, если они были запрошены, в соответствии с запрошенными областями действия (scopes).

Примечание: Дополнительно доступен метод получения списка публичных ключей для проверки токена (см. https://auth-openapi.npck.kz/#tag/Auth/operation/wellKnown).

Дополнительно доступен опциональный метод интроспекции токена (см описание https://auth-openapi.npck.kz/#tag/Auth/operation/oauth2Introspect). Данный метод используется для проверки того, активен или истек ли конкретный токен, а также для получения связанных с токеном метаданных.

При получении результата аутентификации в параметре access_token (в формате JWT) , кроме всего прочего, в поле sid (session id) содержится идентификатор сессий пользователя, в рамках которой была проведена аутентификация.

Рекомендуется сохранить на своей стороне значение sid. Используя это значение, можно будет получить информацию о сессии аутентификации пользователя (количество попыток прохождения livness-проверки, количество отправленных СМС-кодов, результат и т.д.) .