> For the complete documentation index, see [llms.txt](https://docs.npck.kz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.npck.kz/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/rekomendacii-po-realizacii-integracii.md). # Рекомендации по реализации интеграции {% hint style="info" %} Для использования сервиса аутентификации личности клиента FinID необходимо, чтобы Участник: 1\. Прошел процедуру регистрации на Портале АО «НПК» (см. подробнее в [Регистрация и авторизация в Портале НПК](https://docs.npck.kz/rabota-s-testovym-okruzheniem-is-npk/rabota-s-testovym-portalom-npk/registraciya-i-avtorizaciya-v-portale-npk)) 2\. Подал заявку на подключение к ЦОИД (см. подробнее в [5.1 Подключение к ЦОИД](/registraciya-i-avtorizaciya/5.-podacha-zayavki-na-podklyuchenie-k-servisam/5.1-podklyuchenie-k-coid.md)) 3\. Зарегистрировал приложение Участника (см. подробнее в [Пользователям API (добавление и использование приложения)](https://docs.npck.kz/rabota-s-testovym-okruzheniem-is-npk/rabota-s-testovymi-servisami/polzovatelyam-api-dobavlenie-i-ispolzovanie-prilozheniya)) {% endhint %} {% hint style="warning" %} Аутентификацию могут пройти люди, у которых имеется как минимум один из следующих документов: * удостоверение личности гражданина РК * паспорт гражданина РК * вид на жительство иностранца в РК * удостоверение лица без гражданства (казахстанского образца) {% endhint %} ## Рекомендация: отображение инструкции перед началом биометрии Перед запуском процесса биометрической аутентификации **рекомендуется отобразить пользователю инструкцию** с визуальными примерами и текстовыми пояснениями. Это поможет обеспечить корректное прохождение биометрии и повысить процент успешных распознаваний.\ **Основные рекомендации для пользователя** * **Лицо должно быть хорошо освещено.**\ Избегайте резкого света и теней на лице. * **Не должно быть яркого света за спиной.**\ Например, открытого окна или лампы позади. * **Держите устройство ровно и не двигайтесь.**\ Камера должна быть расположена на уровне лица * **В кадре не должно быть других лиц.**\ Лицо должно быть единственным объектом в кадре.

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

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

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

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

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

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

3. Для проведения двухфакторной аутентификации приложение Участника перенаправляет пользователя на Cервис аутентификации личности клиента FinID. {% hint style="warning" %} Если в ОС Android при проведении liveness-сессии не отображается изображение клиента (см. пример на Если в ОС Android при проведении liveness-сессии не отображается изображение клиента (см. пример на рисунке ниже), то потенциальным решением проблемы может являться применение следующих параметров: *webView\.settings.allowContentAccess = true; webView\.settings.mediaPlaybackRequiresUserGesture = false; webView\.settings.domStorageEnabled = true* WebKit в Android, позволяет видео компонентам запускаться только по действию пользователя, при этом для корректной работы сервисов ЦОИД камера запускается программными средствами (autoplay), WebKit блокирует данное действие и выдает ошибку. Чтобы избежать этого, необходимо в компоненте webView указать данную настройку. {% endhint %}

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

{% hint style="warning" %} В IOS необходимо использовать SafariWebView. WKWebView не поддерживается. {% endhint %}
Перенаправления пользователя для прохождения аутентификации Для перенаправления пользователя для прохождения аутентификации Участнику необходимо: 1\) Реализовать получение URL-адреса для перенаправления Клиента. Описание метода «Получить URL-адрес для перенаправления клиента д» (POST /v1/auth/generate-user-url) приведено в . *Примечание: Метод получения URL-адрес для перенаправления клиента POST /oauth2/generate-user-url (см.* [*https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrlDeprecated*](https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrlDeprecated)*) является устаревшим, рекомендуется перейти на использование метода POST /v1/auth/generate-user-url (см.* [*https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrl*](https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrl)*).* 2\) Реализовать перенаправление пользователя на полученный URL-адрес.
{% hint style="info" %} Услуга, предоставляемая ЦОИД, определяется значениями, указанными в параметре scopes при формировании запроса на получение URL-адреса для перенаправления пользователя в ЦОИД: *Получение персональных данных:* * iin - доступ к ИИН пользователя * full\_name - доступ к ФИО пользователя * first\_name - доступ к имени пользователя * last\_name - доступ к фамилии пользователя * middle\_name - доступ к отчеству пользователя * date\_of\_birth - доступ к дате рождения пользователя * place\_of\_birth - доступ к месту рождения пользователя (описание объекта в [Описание объектов](/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov.md#ref130980979)) * gender - доступ к полу пользователя (описание объекта см. в [Описание объектов](/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov.md#toc165886969)) * nationality - доступ к национальности пользователя (описание объекта см. в [Описание объектов](/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov.md#toc165886969)) * registration\_address - доступ к адресу регистрации пользователя (описание объекта см. в [/pages/01xK7ZFhDPTSZqD3IIxW#id-3.-struktura-obekta-registration\_address-adres-registracii](https://docs.npck.kz/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/pages/01xK7ZFhDPTSZqD3IIxW#id-3.-struktura-obekta-registration_address-adres-registracii "mention")) * document\_number - доступ к информации о номере документа, удостоверяющего личность пользователя * document\_type - доступ к типу документа, удостоверяющего личность пользователя (описание объекта см. в [Описание объектов](/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov.md#toc165886969)) * document\_issue\_date - доступ к информации о дате выдачи документа, удостоверяющего личность пользователя * document\_expiry\_date - доступ к дате истечения срока действия документа, удостоверяющего личность пользователя * document\_issue\_place - доступ к информации о том, кем был выдан документ, удостоверяющий личность пользователя (описание объекта см. в [Описание объектов](/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov.md#toc165886969)) *Верификация физического лица:* * openid - если необходима только верификация личности пользователя (без предоставления доступа к персональным данным), то в параметре scopes должно быть указано только значение openid *Подписание документов ЭЦП:* * esign **-** подписания документов ЭЦП (подробнее о подписании см. [Сервис управления облачной ЭЦП Esign](/servisy-coid/servis-upravleniya-oblachnoi-ecp-esign.md)), может использоваться совместно со значениями 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 | Подозреваемый казино / букмекеры (ССЭП) | Подозрение по линии ССЭП. Ограничение операций, ожидание результатов проверки. |
*Примечание: Описание объектов см. в* [Описание объектов](/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/opisanie-obektov.md) {% endhint %} {% hint style="warning" %} Время действия URL-адреса для перенаправления (время «жизни») составляет 15 минут {% endhint %} 4. Пользователю отображается форма аутентификации ЦОИД. Пользователь проходит двухфакторную аутентификацию личности. 5. Пользователь должен дать согласие на доступ к его данным для приложения Участника. {% hint style="info" %} Пользователь может отклонить согласие на доступ к его данным. Если Пользователь отклоняет согласие на доступ к его данным или происходит ошибка, то Пользователь будет перенаправлен на указанный на шаге 2 **redirectUri**, с указанием кода ошибки, по следующему шаблону: `[redirectUri]?errorCode=[error code]&state=[state]` В таком случае процесс завершается, код авторизации не предоставляется. {% endhint %} 6. После того, как Пользователь выполнит все действия на стороне ЦОИД, осуществляется его возврат в приложение Участника. {% hint style="info" %} Если аутентификация Пользователя проходит успешно и он дает согласие на доступ к его данным, то Пользователь перенаправляется обратно в приложение Участника (на указанный в запросе *redirectUri*) с одноразовым кодом авторизации (code), по следующему шаблону: `[redirectUri]?code=[authorization code]&state=[state]` {% endhint %} {% hint style="warning" %} Код авторизации является одноразовым. Время действия кода авторизации (время «жизни») составляет 300 секунд {% endhint %} {% hint style="warning" %} Редирект из webview в случае SafariWebView нужно перехватывать через диплинк (deeplink) {% endhint %} 7. Приложение Участника получает результат аутентификации, используя полученный на предыдущем шаге код авторизации.
Получение результата аутентификации Для получения результата аутентификации Участнику необходимо: 1\) Реализовать формирование запроса получения результата аутентификации клиента, используя полученный код авторизации. Описание используемого для этого метода приведено в . {% hint style="info" %} Срок действия `access_token` зависит от того, какие данные запрашиваются (scope): * Для аутентификации личности клиента через FinID (`openid`, `iin`, `first_name` и т.д.) — **12 часов**. * Для работы с облачной ЭЦП (`esign`, `organization_esign`) — **5 минут**. * Для получения информации о банковских счетах клиента (через Межбанковскую систему обмена информацией по открытым программным интерфейсам (Open API)) (`accounts`, `account_balance`, `account_transactions`) — **30 дней**. {% endhint %} 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/wellKnown)*).* *Дополнительно доступен метод получения* электронного документа по результатам проведения биометрической идентификации (см. ). *Дополнительно доступен опциональный метод интроспекции токена (см описание* [*https://auth-openapi.npck.kz/#tag/Auth/operation/oauth2Introspect*](https://auth-openapi.npck.kz/#tag/Auth/operation/oauth2Introspect)*). Данный метод используется для проверки того, активен или истек ли конкретный токен, а также для получения связанных с токеном метода* Пример данных токена - **id\_token:** ```json { "active": true, "sub": "1234567890123", "document_number": "{\"document_number\":\"040100767\"}", "gender": "{\"gender\":{\"code\":\"1\",\"nameRu\":\"Мужской\",\"nameKz\":\"Ер\"}}", "openid": "{\"user_id\":379678}", "date_of_birth": "{\"date_of_birth\":\"1900-04-24\"}", "iss": "https://auth.npck.kz", "last_name": "{\"last_name\":\"ИВАНОВ\"}", "middle_name": "{\"middle_name\":\"ИВАНОВИЧ\"}", "sid": "07afcc54-5eb6-405d-b419-ab2b96b76e47", "iin": "{\"iin\":\"1234567890123\"}", "place_of_birth": "{\"place_of_birth\":{\"country\":{\"code\":\"398\",\"nameRu\":\"КАЗАХСТАН\",\"nameKz\":\"ҚАЗАҚСТАН\"},\"district\":{\"code\":\"1910\",\"nameRu\":\"АЛМАТЫ\",\"nameKz\":\"АЛМАТЫ\"},\"region\":{\"code\":\"1910264\",\"nameRu\":\"БОСТАНДЫКСКИЙ\",\"nameKz\":\"БОСТАНДЫҚ\"},\"foreignData\":{\"districtName\":null,\"regionName\":null},\"city\":\"-\",\"birthTeCodeAR\":null}}", "aud": [ "8e7179f7-ff5a-4342-a790-a5d2ec8ea658" ], "document_expiry_date": "{\"document_expiry_date\":\"2026-05-12\"}", "full_name": "{\"full_name\":\"ИВАНОВ ИВАН ИВАНОВИЧ\"}", "nationality": "{\"nationality\":{\"code\":\"001\",\"nameRu\":\"РУССКИЙ\",\"nameKz\":\"ОРЫС\"}}", "azp": "8e7179f7-ff5a-4342-a790-a5d2ec8ea658", "auth_time": 1761201137593, "document_issue_place": "{\"document_issue_place\":{\"code\":\"002\",\"nameRu\":\"МИНИСТЕРСТВО ВНУТРЕННИХ ДЕЛ РК\",\"nameKz\":\"ҚР ІШКІ ІСТЕР МИНИСТРЛІГІ\"}}", "registration_address": "{\"registration_address\":{\"country\":{\"code\":\"398\",\"nameRu\":\"КАЗАХСТАН\",\"nameKz\":\"ҚАЗАҚСТАН\"},\"district\":{\"code\":\"1910\",\"nameRu\":\"АЛМАТЫ\",\"nameKz\":\"АЛМАТЫ\"},\"region\":{\"code\":\"1910262\",\"nameRu\":\"АУЭЗОВСКИЙ\",\"nameKz\":\"ӘУЕЗОВ\"},\"foreignData\":{\"districtName\":null,\"regionName\":null},\"city\":null,\"street\":\"МИКРОРАЙОН Аксай-15\",\"building\":\"20\",\"corpus\":null,\"flat\":\"8\",\"beginDate\":\"2018-04-25T00:00:00.000+00:00\",\"endDate\":null,\"status\":{\"code\":\"1\",\"nameRu\":\"Зарегистрирован\",\"nameKz\":\"Тіркелді\",\"changeDate\":\"2013-11-29T17:36:46.000+00:00\"},\"invalidity\":{\"code\":\"0\",\"nameRu\":\"Зарегистрирован\",\"nameKz\":\"Тіркелді\",\"changeDate\":\"2013-11-29T17:36:46.000+00:00\"},\"arCode\":\"1201300109160222\"}}", "document_issue_date": "{\"document_issue_date\":\"2016-05-13\"}", "exp": 1761203091, "iat": 1761201291, "first_name": "{\"first_name\":\"ИВАН\"}", "document_type": "{\"document_type\":{\"code\":\"002\",\"nameRu\":\"УДОСТОВЕРЕНИЕ РК\",\"nameKz\":\"ҚР ЖЕКЕ КУӘЛІГІ\"}}", "client_id": "8e7179f7-ff5a-4342-a790-a5d2ec8ea658" } ```
{% hint style="info" %} При получении результата аутентификации в параметре access\_token (в формате JWT) , кроме всего прочего, в поле sid (session id) содержится идентификатор сессий пользователя, в рамках которой была проведена аутентификация. Рекомендуется сохранить на своей стороне значение sid. Используя это значение, можно будет получить информацию о сессии аутентификации пользователя (количество попыток прохождения livness-проверки, количество отправленных СМС-кодов, результат и т.д.) . {% endhint %}