Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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

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

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

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

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

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

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

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

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

Рекомендация: отображение инструкции перед началом биометрии

Перед запуском процесса биометрической аутентификации рекомендуется отобразить пользователю инструкцию с визуальными примерами и текстовыми пояснениями. Это поможет обеспечить корректное прохождение биометрии и повысить процент успешных распознаваний. Основные рекомендации для пользователя

  • Лицо должно быть хорошо освещено. Избегайте резкого света и теней на лице.

  • Не должно быть яркого света за спиной. Например, открытого окна или лампы позади.

  • Держите устройство ровно и не двигайтесь. Камера должна быть расположена на уровне лица

  • В кадре не должно быть других лиц. Лицо должно быть единственным объектом в кадре.

Пример интерфейса

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

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

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

  2. При отправке запроса на аутентификацию личности - ЦОИД осуществляет проверку соответствия номера телефона и ИИН в базе пользователей ЦОИД, а также в Базе мобильных граждан (БМГ) в случае, если указанный номер в запросе уже привязан к другому ИИН в базе пользователей ЦОИД. В случае формирования ошибки "PHONE_BELONGS_TO_ANOTHER_IIN_IN_BMG" процедура аутентификации не проводится. В данном случае Участнику необходимо отобразить пользователю страницу с уведомлением о том, что указанный номер телефона зарегистрирован за другим ИИН, а также предоставить рекомендацию об обновлении данных в БМГ.

    Рекомендации по тексту уведомления:

    "Введенный номер телефона закреплен за другим ИИН. Пожалуйста, обновите номер телефона в Базе мобильных граждан, обратившись в единый контакт-центр 1414 на портале egov.kz"

Пример для отображения в случае если номер телефона привязан к другому ИИН

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

Если в ОС Android при проведении liveness-сессии не отображается изображение клиента (см. пример на Если в ОС 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-адреса для перенаправления пользователя в ЦОИД:

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

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

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

Подписание документов ЭЦП:

  • esign - подписания документов ЭЦП (подробнее о подписании см. Сервис управления облачной ЭЦП Esign), может использоваться совместно со значениями scopes для персональных данных и верификации физического лица

  • antifraud - доступ к информации о том, не числится ли пользователь в реестре лиц, причастных к мошенническим операциям. Статусы могут быть:

Статусы antifraud
Код статуса
Название
Описание

GREY

Подозреваемый мошенник

Субъект выявлен в рамках мошеннических операций без подтверждения. Усиленная проверка, возможная приостановка операций и мониторинг.

BLACK

Мошенник

Подтверждённое мошенничество. Отказ в операциях, блокировка в рамках законодательства.

DROPPER

Дроппер

Лицо, предоставившее реквизиты или счёт третьим лицам. Ограничение расходных операций, выяснение источников средств.

VICTIM

Пострадавший

Информационная категория для фиксации пострадавшей стороны. Ограничения не применяются.

WITNESS

Свидетель

Лицо, ранее фигурировавшее в инциденте, но не подтвердившее участие. Используется для разблокировки и исключения из списков.

WHITE_LIST

Белый список

Субъекты, которые не должны попадать под блокирующие категории: БВУ, финансовые организации, маркетплейсы, торговые магазины и др.

POTENCIAL_VICTIM

Потенциальная жертва

Лица, которые могут быть атакованы мошенниками.

DRUG_GREY

Подозреваемый наркопреступник

Подозрение выявлено финансовой организацией по наркотической тематике. Ограничение операций, регистрация инцидента.

DRUG_CEPI_GREY

Подозреваемый наркопреступник (ССЭП)

Подозрение по линии ССЭП/СЭР. Ограничение операций, ожидание результатов проверки.

PYRAMID_GREY

Подозреваемый участник финансовой пирамиды

Подозрение выявлено финансовой организацией. Ограничение операций, регистрация инцидента.

PYRAMID_CEPI_GREY

Подозреваемый участник финансовой пирамиды (ССЭП)

Подозрение по материалам ССЭП. Ограничение операций, мониторинг.

CASINO_GREY

Подозреваемый казино / букмекеры

Подозрение в операциях в пользу онлайн-казино или букмекеров, выявленное финансовой организацией.

CASINO_CEPI_GREY

Подозреваемый казино / букмекеры (ССЭП)

Подозрение по линии ССЭП. Ограничение операций, ожидание результатов проверки.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Срок действия access_token зависит от того, какие данные запрашиваются (scope):

  • Для аутентификации личности клиента через FinID (openid, iin, first_name и т.д.) — 12 часов.

  • Для работы с облачной ЭЦП (esign, organization_esign) — 5 минут.

  • Для получения информации о банковских счетах клиента (через Межбанковскую систему обмена информацией по открытым программным интерфейсам (Open API)) (accounts, account_balance, account_transactions) — 30 дней.

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

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

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

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

Пример данных токена - id_token:

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

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

PreviousОписание клиентского путиNextОписание объектов

Last updated