Рекомендации по реализации интеграции
Для использования сервиса биометрической верификации необходимо, чтобы Участник:
1. Прошел процедуру регистрации на Портале АО «НПК» (см. подробнее в Регистрация и авторизация в Портале НПК)
2. Подал заявку на подключение к ЦОИД (см. подробнее в Подключение к ЦОИД)
3. Зарегистрировал приложение Участника (см. подробнее в Пользователям API (добавление и использование приложения))
Верификацию могут пройти люди, у которых имеется как минимум один из следующих документов:
удостоверение личности гражданина РК
паспорт гражданина РК
вид на жительство иностранца в РК
удостоверение лица без гражданства (казахстанского образца)
Рекомендация: отображение инструкции перед началом биометрии
Перед запуском процесса биометрической аутентификации рекомендуется отобразить пользователю инструкцию с визуальными примерами и текстовыми пояснениями. Это поможет обеспечить корректное прохождение биометрии и повысить процент успешных распознаваний. Основные рекомендации для пользователя
Лицо должно быть хорошо освещено. Избегайте резкого света и теней на лице.
Не должно быть яркого света за спиной. Например, открытого окна или лампы позади.
Держите устройство ровно и не двигайтесь. Камера должна быть расположена на уровне лица
В кадре не должно быть других лиц. Лицо должно быть единственным объектом в кадре.
Общее описание процесса:
Пользователь инициирует получение услуги в приложении Участника, для которой требуется проведение верификация личности.
При отправке запроса на аутентификацию личности - ЦОИД осуществляет проверку соответствия номера телефона и ИИН в базе пользователей ЦОИД, а также в Базе мобильных граждан (БМГ) в случае, если указанный номер в запросе уже привязан к другому ИИН в базе пользователей ЦОИД. В случае формирования ошибки "PHONE_BELONGS_TO_ANOTHER_IIN_IN_BMG" процедура аутентификации не проводится. В данном случае Участнику необходимо отобразить пользователю страницу с уведомлением о том, что указанный номер телефона зарегистрирован за другим ИИН, а также предоставить рекомендацию об обновлении данных в БМГ.
Рекомендации по тексту уведомления:
"Введенный номер телефона закреплен за другим ИИН. Пожалуйста, обновите номер телефона в Базе мобильных граждан, обратившись в единый контакт-центр 1414 на портале egov.kz"
Для проведения верификации приложение Участника перенаправляет пользователя на сервис биометрической верификации.
Если в ОС Android при проведении liveness-сессии не отображается изображение клиента (см. пример на рисунке ниже), то потенциальным решением проблемы может являться применение следующих параметров:
webView.settings.allowContentAccess = true; webView.settings.mediaPlaybackRequiresUserGesture = false; webView.settings.domStorageEnabled = true
WebKit в Android, позволяет видео компонентам запускаться только по действию пользователя, при этом для корректной работы сервисов ЦОИД камера запускается программными средствами (autoplay), WebKit блокирует данное действие и выдает ошибку. Чтобы избежать этого, необходимо в компоненте 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
Подписание документов ЭЦП:
esign - подписания документов ЭЦП (подробнее о подписании см. Сервис управления облачной ЭЦП Esign), может использоваться совместно со значениями scopes для персональных данных и верификации физического лица
Примечание: Описание объектов см. в Описание объектов
Время действия URL-адреса для перенаправления (время «жизни») составляет 15 минут
Пользователю отображается форма верификации ЦОИД. Пользователь проходит верификацию личности.
Пользователь должен дать согласие на доступ к его данным для приложения Участника.
Пользователь может отклонить согласие на доступ к его данным.
Если Пользователь отклоняет согласие на доступ к его данным или происходит ошибка, то Пользователь будет перенаправлен на указанный на шаге 2 redirectUri, с указанием кода ошибки, по следующему шаблону:
[redirectUri]?errorCode=[error code]&state=[state]
В таком случае процесс завершается, код авторизации не предоставляется.
После того, как Пользователь выполнит все действия на стороне ЦОИД, осуществляется его возврат в приложение Участника.
Если верификация Пользователя проходит успешно и он дает согласие на доступ к его данным, то Пользователь перенаправляется обратно в приложение Участника (на указанный в запросе redirectUri) с одноразовым кодом авторизации (code), по следующему шаблону:
[redirectUri]?code=[authorization code]&state=[state]
Код авторизации является одноразовым.
Время действия кода авторизации (время «жизни») составляет 300 секунд
Редирект из webview в случае SafariWebView нужно перехватывать через диплинк (deeplink)
Приложение Участника получает результат верификации , используя полученный на предыдущем шаге код авторизации.
Получение результата верификации
Для получения результата верификации Участнику необходимо:
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) Реализовать отправку сформированного запроса и получение результата верификации клиента.
В результате успешной верификации предоставляется идентификационный токен (в формате 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-проверки, результат и т.д.) .
Last updated