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

Для использования сервиса управления облачной ЭЦП Esign необходимо, чтобы Участник:

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

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

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

Подписание документов ЭЦП доступно для людей, у которых имеется как минимум один из следующих документов:

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

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

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

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

Общее описание процесса подписания документа ЭЦП

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

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

Загрузка документов для подписания

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

Загрузка документа для подписания

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

1) Реализовать формирование запроса отправки документа. Описание используемого для этого метода приведено в https://esign-openapi.npck.kz/#tag/Esign/operation/uploadSignable.

2) Реализовать отправку сформированного запроса и получение в ответ идентификатора документа (id) для последующего его подписания.

Срок хранения загруженного, но не подписанного документа составляет 24 часа с момента загрузки. По истечении 24 часов документ удаляется

Идентификатор загруженного документа используется при последующем запросе подписания документов, а также при получении подписанных документов

Поддерживается подписание электронных документов в форматах PDF, XML, BLOB (документ в виде массива байт)

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

1. Для подписания документов ЭЦП приложение Участника перенаправляет клиента на Сервис управления облачной ЭЦП Esign.

Если в ОС 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.

При этом, в параметре esignScopeData передаются идентификаторы документов, предварительно загруженных Участником (см. шаг 2 общего процесса).

2) Реализовать перенаправление пользователя на полученный URL-адрес для прохождения аутентификации пользователем и последующего подписания документов его ЭЦП.

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

Для подписания документов ЭЦП используется значение esign.

Значение esign, может использоваться совместно со значениями scopes для персональных данных и верификации физического лица (см. подробнее в Рекомендации по реализации интеграции):

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

• 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 минут

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

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

3. Пользователь подписывает документы ЭЦП.

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

Если Пользователь отклоняет подписание документов ЭЦП или происходит ошибка, то Пользователь будет направлен на указанный при запросе URL-адреса для перехода в ЦОИД (на шаге 4) redirectUri, с указанием кода ошибки, по следующему шаблону:

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

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

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

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

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

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

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

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

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

Получение токена

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

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

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

Токен доступа имеет формат JWT (см. RFC 7519)

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

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

Токен доступа необходим Участнику для последующего получения информации о подписанных документах (шаг 9)

Важно! Токен доступа должен сохраняться в тайне и не передаваться в публичный доступ, должен храниться на серверной стороне приложения Участника, и вся обработка, связанная с ним, должна производиться на серверной стороне приложения.

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

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

Получение подписанных документов

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

Получение подписанных документов

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

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

2. Реализовать отправку сформированного запроса и получение перечня подписанных документов.

В ответе предоставляется перечень документов подписанных пользователем, включая: идентификатор документа, его наименование, тип, сам подписанный документ в формате base64, дату и время подписания

Проверка подлинности цифровой подписи

Метод проверки валидности ЭЦП зависит от того, документ какого типа был подписан:

• для документов в формате BLOB (binary linked object) - используется метод, описание которого приведено в https://esign-openapi.npck.kz/#tag/Esign/operation/verifySignedBlob

• для документов в формате PDF - используется метод, описание которого приведено в https://esign-openapi.npck.kz/#tag/Esign/operation/verifySignedPdf

• для документов в формате XML - используется метод, описание которого приведено в https://esign-openapi.npck.kz/#tag/Esign/operation/verifySignedXml