Для разработчиков


# Введение

Сервис SIGEX предоставляет публичный API по протоколу HTTPS на двух портах:

  • 443 - аутентификация пользователей;
  • 10443 - аутентификация информационных систем.

Отличия описаны в разделе Аутентификация пользователей и информационных систем.

Статья Аутентификация по цифровым сертификатам описывает процесс интеграции аутентификации в информационные системы.

# Отправка запросов и интерпретация ответов

Кроме тех случаев, когда это явно указано, запросы сервису следует отправлять в формате JSON (с указанием типа содержимого application/json в заголовке Content-Type), сервис должен вернуть HTTP код 200 и ответ в виде JSON строки. Другой код HTTP свидетельствует о серьезной проблеме при обработке запроса, в этом случае нет смысла пробовать анализировать ответ.

# Известные OIDы применяемые в НУЦ РК

OIDы политик:

  • ‘1.2.398.3.3.2.1’ - ‘Юридическое лицо’
  • ‘1.2.398.3.3.2.2’ - ‘Юридическое лицо - аутентификация’
  • ‘1.2.398.3.3.2.3’ - ‘Физическое лицо’
  • ‘1.2.398.3.3.2.4’ - ‘Физическое лицо - аутентификация’
  • ‘1.2.398.5.19.1.2.2.1.2’ - ‘ЭЦП информационной системы К2’

OIDы использования ключа:

  • ‘1.2.398.3.3.4.1.1’ - ‘Физическое лицо’
  • ‘1.2.398.3.3.4.1.1.1’ - ‘Информационная система физического лица’
  • ‘1.2.398.3.3.4.1.2’ - ‘Юридическое лицо’
  • ‘1.2.398.3.3.4.1.2.1’ - ‘Первый руководитель’
  • ‘1.2.398.3.3.4.1.2.2’ - ‘Право подписи’
  • ‘1.2.398.3.3.4.1.2.3’ - ‘Право подписи финансовых документов’
  • ‘1.2.398.3.3.4.1.2.4’ - ‘Сотрудник отдела кадров’
  • ‘1.2.398.3.3.4.1.2.5’ - ‘Сотрудник организации’
  • ‘1.2.398.3.3.4.1.2.6’ - ‘Информационная система юридического лица’
  • ‘1.2.398.3.3.4.2’ - ‘Полномочия в информационной системе НУЦ РК’
  • ‘1.2.398.3.3.4.2.1’ - ‘Администратор НУЦ РК’
  • ‘1.2.398.3.3.4.2.2’ - ‘Менеджер НУЦ РК’
  • ‘1.2.398.3.3.4.2.3’ - ‘Оператор НУЦ РК’
  • ‘1.2.398.3.3.4.3’ - ‘Метод идентификации пользователя’
  • ‘1.2.398.3.3.4.3.1’ - ‘Идентификация через оператора ЦОН’
  • ‘1.2.398.3.3.4.3.2’ - ‘Удаленная идентификация’
  • ‘1.2.398.3.3.4.3.2.1’ - ‘Идентификация Digital-ID’
  • ‘1.2.398.5.19.1.2.2.1’ - ‘Информационная система К2’

# Аутентификация пользователей и информационных систем

Сервис поддерживает два механизма аутентификации:

  • аутентификация пользователей по цифровым сертификатам НУЦ - этот механизм подходит для тех случаев, когда действия выполнятся от имени пользователей (к примеру просмотр своих подписанных документов или документов сотрудников компании);
  • аутентификация информационных систем двусторонним TLS - этот механизм подходит для автоматизированных сценариев, когда действия должны выполняться не от имени определенных пользователей, а от имени информационной системы (к примеру построение отчетов о подписанных документах по расписанию).

# Аутентификация пользователей по цифровым сертификатам НУЦ

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

  • Система электронного документооборота (ЭДО) может использовать SIGEX как источник данных о цифровых подписях под документами пользователей. В этом случае после входа в свой профиль в ЭДО пользователи могут просматривать и редактировать настройки своего профиля в SIGEX, менять параметры своих подписанных документов в SIGEX. Для выполнения действий ЭДО обращается к сервису SIGEX от имени того пользователя, который запросил выполнение этого действия в ЭДО.
    sequenceDiagram participant B as Браузер пользователя participant D as Сервер ЭДО participant S as SIGEX B->>D: Пользователь запрашивает перечень
    подписей под документом в ЭДО D-->>S: ЭДО запрашивает у SIGEX перечень подписей
    под соответствующим подписанным документом S-->>D: SIGEX формирует ответ для ЭДО D->>B: ЭДО конвертирует данные и
    формирует ответ на запрос пользователя
  • Веб интерфейс информационной системы может взаимодействовать с SIGEX напрямую, а не через свой сервер, это может быть удобно для тех систем, которым не требуется проверять цифровые подписи под электронными документами - к примеру системы обмена сообщениями или CRM системы могут отображать контекстную информацию о документах подписанных цифровой подписью.
    sequenceDiagram participant B as Браузер пользователя participant D as CRM система participant S as SIGEX B->>D: Пользователь открывает профиль клиента D->>B: В профиле клиента CRM система
    приводит перечень договоров с клиентом B-->>S: Браузер пользователя запрашивает
    информацию о подписях под договорами S-->>B: SIGEX предоставляет информацию
    и в профиле автоматически отображается информация о подписях
  • Информационные системы могут внедрять аутентификацию по цифровым сертификатам (к примеру вход в личный кабинет пользователя по цифровому сертификату НУЦ) используя данный механизм аутентификации в режиме внешней аутентификации, преимущества такого подхода:
    • регистрация новых пользователей не обязательна, они могут сразу входить в систему;
    • идентификация пользователей по ИИН;
    • при необходимости привязка к БИН;
    • простая реализация минимизирует вероятность обнаружения уязвимостей.

Аутентификация пользователей по цифровым сертификатам НУЦ основана на подписании пользователем блока случайных данных (nonce) и последующей проверке этой подписи. В том случае, если подпись верна, сервис может быть уверен в том, что пользователь обладает закрытым ключом соответствующим открытому ключу в сертификате (регистрационном свидетельстве) НУЦ.

За данный режим аутентификации отвечают следующие API:

Отличительной особенностью режима внешней аутентификации является то, что в этом режиме сервис SIGEX не устанавливает в своих ответах cookie с JWT токенами содержащими информацию о пользователе прошедшем аутентификацию. Детали приведены в POST /api/auth - аутентификация.

Вводная статья Аутентификация по цифровым сертификатам описывает процесс интеграции аутентификации в информационные системы в режиме внешней аутентификации.

# Аутентификация информационных систем двусторонним TLS

Этот способ аутентификации подходит для тех сценариев, когда действия должны выполняться не от имени определенных пользователей, а от имени информационной системы, к примеру:

  • автоматизированный экспорт подписей из SIGEX в локальную БД;
  • анализ и построение отчетов о документах организации;
  • построение отчетов о действиях сотрудников организации (кто что и когда подписывал).

В случае использования этого механизма, с точки зрения SIGEX информационная система будет действовать от имени организации, а не какого-то определенного ее представителя.

Данный механизм аутентификации доступен на отдельном порту https://sigex.kz:10443 и требует предоставления клиентского сертификата https://ru.wikipedia.org/wiki/HTTPS#Идентификация_клиента. Практически все API, доступные на стандартном порту https://sigex.kz, без изменений доступны и тут. Исключение составляют API аутентификации по цифровым сертификатам НУЦ, тут они не работают.

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

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

  • опционально самостоятельно сгенерировать клиентский TLS сертификат для информационной системы (это можно сделать автоматически в следующем пункте);
  • добавить сертификат информационной системы в настройках организации в необходимые этой информационной системе списки контроля доступа;
  • на сервере информационной системы в качестве URL для доступа к API SIGEX использовать https://sigex.kz:10443;
  • настроить использование двустороннего TLS при взаимодействии с API SIGEX на сервере информационной системы с использованием указанного ранее сертификата и соответствующего закрытого ключа.

Поддерживаемые протоколы:

  • TLS 1.3.

Допустимые длины ключей:

  • RSA не короче 2048 бит;
  • ECDSA не короче 224 бит.

# Контроль доступа

Определены следущие типы прав доступа:

  • просмотр информации о документе;
  • просмотр/изменение настроек документа;
  • перечисление документов;
  • просмотр/изменение настроек организации;
  • просмотр/изменение настроек пользователя.

Полномочия первого руководителя всегда присутствуют во всех блоках контроля доступа настроек организации (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя). Таким образом первый руководитель всегда имеет доступ к документам и настройкам организации.

Просмотр информации о документе

Документ может быть публично доступным, либо с ограниченным доступом, это определяет параметр private в настройках документа (см. POST /api/{id}/settings - изменение настроек документа).

В том случае, если документ является публично доступным (private: false), то доступ к информации о нем может получить любой кто знает идентификатор документа.

В том случае, если доступ к документу ограничен (private: true), то доступ к информации о нем могут получить:

Просмотр/изменение настроек документа

Просматривать и изменять настройки документа могут:

  • пользователи, прошедшие аутентификацию по сертификату НУЦ физического лица, чьи подписи с использованием сертификата физического лица присутствуют под документом;
  • пользователи, прошедшие аутентификацию по сертификату НУЦ юридического лица, чьи подписи с использованием сертификата того же самого юридического лица присутствуют под документом;
  • сотрудники той же организации, подпись сотрудника которой присутствует под документом, но только после прохождения аутентификации по сертификату НУЦ юридического лица и при условии того, что в сертификате, использованном для аутентификации, присутствует полномочие, указанное в блоке documentsSettings настроек этой организации (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя);
  • те информационные системы, которые прошли аутентификацию по двустороннему TLS и чьи сертификаты указаны в блоке documentsSettings настроек этой организации (POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя).

Перечисление документов

API перечисления документов (GET /api/?from=xxx&until=yyy&organization=true - перечисление документов аутентифицированного пользователя) с помощью параметра organization позволяет указывать какие документы следует перечислять:

  • Документы пользователя (их возможно перечислять после прохождения аутентификации по сертификату НУЦ физического, либо юридического лица) - это документы, подписанные пользователем, как физическим лицом, либо представителем юридического лица. То есть это все те документы, которые подписывал пользователь не зависимо от того, подписывал он их сертификатом физического лица или сертификатом юридического лица.
  • Документы юридического лица (их возможно перечислять после прохождения аутентификации по сертификату НУЦ юридического лица, либо информационной системой по двустороннему TLS) - это документы, подписанные сотрудниками той же организации, что пользователь или информационная система.

Во втором случае следует установить organization=true в запросе.

При перечислении документов пользователя сервис будет возвращать те документы, которые были подписаны прошедшим аутентификацию пользователем.

При перечислении документов юридического лица сервис будет возвращать документы соответствующей организации, но при условии что:

Просмотр/изменение настроек организации

Просматривать и изменять настроки организации могут:

Просмотр/изменение настроек пользователя

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

# Сообщения об ошибках

При возникновении ошибок все методы API возвращают сообщение об ошибке следующего формата:

{
  "message": "Request processing error",
  "requestID": 1570108542768139099
}
  • message - текст сообщения об ошибке на английском языке;
  • requestID - идентификатор запроса.

# Перечень возможных сообщений об ошибках

  • “Unexpected error” - “непредвиденная ошибка”, подобное сообщение сигнализирует о неизвестной нам проблеме на сервере;
  • “Failed to parse JSON” - “не удалось разобрать JSON запрос”, JSON запрос был закодирован не корректно, проверьте код формирования запроса;
  • “Invalid JSON request structure” - “не корректная структура JSON запроса”, в запросе отсутствуют какие-то необходимые поля, либо присутствуют лишние;
  • “This signature has already been submitted” - “данная подпись уже была зарегистрирована”, сервис не поддерживает регистрацию одной и той же подписи несколько раз, в том случае, если необходимо повторно подписать документ, подпись можно вычислить повторно с помощью метода createCMSSignatureFromBase64 NCALayer, бинарно это будет другая подпись;
  • “Document not found” - “документ не найден”, идентификатор документа указан не верно;
  • “Invalid document identifier” - “не корректный идентификатор документа”, формат идентификатора документа не корректен (не соответствуют длина, либо содержимое);
  • “Invalid signature identifier” - “не корректный идентификатор подписи”, формат идентификатора подписи не корректен (не соответствуют длина, либо содержимое);
  • “Invalid signature export format” - “не корректный формат экспорта”, запрошенный формат экспорта не поддерживается сервисом;
  • “Failed to parse signature” - “не удалось разобрать подпись”, данные подписи были повреждены, либо не правильно закодированы;
  • “Invalid signature” - “не корректная подпись”, подпись разобрать удалось, но ее состав не соответствует ожидаемому, вероятно подпись была получена не поддерживаемым способом;
  • “Bad signer certificate” - “плохой сертификат подписавшего”, для подписания был использован плохой сертификат (просрочен, либо выпущен по не поддерживаемому шаблону, либо это сертификат для аутентификации);
  • “Request body too large” - “размер запроса слишком велик”, сервис накладывает ограничения на размер определенных запросов;
  • “Invalid URL query parameter” - “не корректный URL параметр запроса”, передан непредусмотренный URL параметр, либо не передан необходимый;
  • “Invalid HTTP request headers” - “не корректный заголовок запроса”, передан некорректный заголовок;
  • “Invalid API route” - “не корректный маршрут”, запрос отправлен на не поддерживаемый маршрут;
  • “Invalid HTTP request method” - “не корректный HTTP метод”, запрос отправлен с использованием не поддерживаемого HTTP метода;
  • “Document digests are not known” - “хеши документа не известны”, свидетельствует о не завершенной регистрации документа в системе;
  • “Invalid document” - “не корректный документ”, свидетельствует о том, что переданный на проверку документ не является тем, который был подписан (произошла либо подмена, либо модификация документа);
  • “Document digests are already known” - “хеши документа уже известны”, свидетельствует о повторной попытке закончить регистрацию документа;
  • “Signature does not correspond to the document” - “подпись не соответствует документу”, свидетельствует о попытке зарегистрировать подпись к документу к которому она не относится (то есть был зарегистрирован некий документ с первой подписью, вторая регистрируемая подпись была вычислена не от оригинального документа);
  • “OCSP server problem” - “проблема с OCSP сервером”, произошла какая-то проблема связанная с получением статуса сертификата по протоколу OCSP от сервера НУЦ;
  • “Failed to build certificate chain” - “не удалось построить цепочку сертификатов”, свидетельствует о проблеме с сертификатом, использованном для подписания документа, вероятно он не был выпущен НУЦ;
  • “Invalid certificate status” - “не корректный статус сертификата”, сертификат, использованный для подписания, отозван, либо OCSP сервер НУЦ вернул не корректный статус сертификата;
  • “TSP server problem” - “проблема с TSP сервером”, произошла какая-то проблема связанная с получением метки времени (TSP) от сервера НУЦ.
  • “Signature contains invalid TSP time stamp” - “подпись содержит поврежденную или не корректную метку времени TSP”, метка времени в проверяемой подписе отличается от метки, хранимой в базе данных сервиса. Также данная ошибка может возвращаться в том случае когда проверяемая подпись не содержит метку времени, но включает в себя OCSP квитанцию.
  • “Signature contains invalid OCSP data” - “подпись содержит поврежденные или не корректные данные OCSP”, проверяемая подпись содержит квитанцию OCSP отличающуюся от хранимой в базе данных сервиса. Также данная ошибка может возвращаться в случаях, когда либо формат данных о статусе отзыва сертификата (значение атрибута CMS revocation-values) отличается от принятого в системе, либо проверяемая подпись не содержит квитанцию OCSP, но включает в себя TSP метку времени.
  • “Invalid authentication nonce” - “не верный nonce аутентификации”, свидетельствует о том что nonce, использованный при попытке аутентификации, либо не был получен от сервиса, либо просрочен, либо уже был использован.
  • “Authentication required” - “требуется аутентификация”, эту ошибку сервис вернет при попытке обратиться к требующим аутентификации API не пройдя аутентификацию.
  • “User does not represent an organization” - “пользователь не является представителем организации”, эту ошибку сервис вернет при попытке поиска документов организации пользователем без достаточных прав, в частности в том случае когда его сертификат не содержит БИН в имени владельца или в сертификате не указаны необходимые полномочия.
  • “One of the provided notification email addresses is in invalid format” - “не корректный формат одрого из адресов электронной почты для отправки уведомлений”, при регистрации нового документа был указан адрес электронной почты не корректного формата.
  • “Too many notification email addresses provided” - “указано слишком много адресов электронной почты для рассылки уведомлений”, при регистрации нового документа было указано слишком много адресов электронной почты.
  • “Invalid format of provided document settings” - “некорректный формат объекта настроек документа”, структура объекта настроек документа не верна.
  • “Signature type is not supported” - “не поддердживаемый тип подписи”, указанный тип подписи не поддерживается сервисом.
  • “QR code versions lower than 11 are not allowed” - “версии QR кодов ниже 11 не поддерживаются”, эту ошибку сервис вернет при попытке формирования QR кодов версии ниже 11.
  • “Signer certificate expired or not yet valid” - “срок действия сертификата уже истек, либо еще не наступил”, уведомляет о проблеме со сроком действия сертификата субъекта подписавшего документ.
  • “Not enough authorities” - “недостаточно полномочий”, уведомляет о том, что при проверке контроля доступа было выявлено что в сертификате, использованном для аутентификации, отсутствуют полномочия, необходимые для выполнения запрошенного действия.
  • “One of the provided authority OIDs is in invalid format” - “некорректный формат одного из переданных в запросе OID”, эту ошибку возвращают API изменения настроек, может быть вызвана тем, что в настройках был указан OID не корректного формата.
  • “Not enough TLS certificates” - “недостаточно TLS сертификатов”, эту ошибку возвращают API изменения настроек, она говорит о том, что в массиве tlsCertificatesList были переданы не все сертификаты в данный момент зарегистрированные сервисом.
  • “One of the provided TLS certificates can not be used for authentication” - “один из TLS сертификатов не может быть использован для аутентификации”, эту ошибку возвращают API изменения настроек, она говорит о том, что в массиве tlsCertificatesList были передан сертификат выпущенные по неподдерживаемому алгоритму, либо с неподдерживаемой длиной ключа.
  • “TLS certificate used for authentication was disabled” - “TLS сертификат, использованный для аутентификации, отключен”, с этой ошибкой можно столкнуться при выполнении аутентификации информационных систем по двустороннему TLS, она говорит о том, что используемый клиентский сертификат отключен в настройках организации.
  • “One of the provided certificate indices is invalid” - “один из индексов сертификатов не верен”, эту ошибку возвращают API изменения настроек, она говорит о том, что один из индексов приведенных в tlsCertificatesIndices не корректен.
  • “Already authenticated with TLS certificate” - “аутентификация уже выполнена по TLS сертификату”, эту ошибку сервис вернет при попытке выполнения аутентификации по сертификату НУЦ после выполнения аутентификации по двустороннему TLS.
  • “Document signatures limit reached” - “превышено ограничение на количество подписей”, может возникнуть при попытке добавить подпись к документу, у которого установлено ограничение на количество подписей.
  • “Document has more signatures than new limit” - “количество подписей под документом превышает устанавливаемое ограничение”, эту ошибку возвращает API настроек документа при попытке установить ограничение на количество подписей превышающее количество зарегистрированных подписей.
  • “Signature does not conform to document settings requirements” - “подпись не удовлетворяет требованиям в настройках документа”, может возникнуть при попытке добавить подпись к документу с настроенными требованиями к подписям.

# Методы API


# POST /api - регистрация нового документа в системе

Важно! Регистрация документа не будет завершена до успешного вызова POST /api/{id}/data.

В рамках регистрации нового документа и его первой подписи будет выполнена проверка подписи а так же, в случае их отсутствия, сбор данных OCSP и TSP для этой подписи.

Сервис допускает регистрацию двух типов подписей:

  • CMS - можно получить у NCALayer методом createCMSSignatureFromBase64;
  • XML - можно получить у NCALayer методом signXml, но с некоторыми оговорками (см. ниже).

CMS подписи не должны включать в себя подписанных данных (последний параметр createCMSSignatureFromBase64 и createCAdESFromBase64 следует устанавливать в false), в одном CMS допускается наличие только одной подписи (то есть одного SignerInfo).

Сервис допускает наличие данных TSP (метка времени) в неподписываемом атрибуте CMS signature-time-stamp со значением, содержащим метку времени. Допускается наличие только одной метки времени.

Сервис допускает наличие данных OCSP (статус сертификата) в неподписываемом атрибуте CMS revocation-values со значением, содержащим в поле RevocationValues.ocspVals[0] OCSP квитанцию со статусом сертификата подписавшего. Допускается наличие только одной квитанции.

Под XML подписью сервис подразумевает только ту часть XML, которая содержит данные о подписи - то есть только элемент <ds:Signature xmlns:ds=“http://www.w3.org/2000/09/xmldsig#">. В том случае, если подпись была сформирована с помощью вызова signXml утилиты NCALayer, то корректное извлечение необходимого элемента и оформление его в соответствии с https://www.w3.org/TR/xmldsig-core1 ложится на плечи разработчика.

Так же при регистрации нового документа можно запросить отправку уведомлений по электронной почте нескольким получателям. Эта функция может быть полезна в том случае, если документ должен быть подписан несколькими лицами - первый подписавший таким образом может запросить отправку уведомлений всем остальным. В сервисе реализовано ограничение на количество адресов. Отправка уведомлений сервисом осуществляется после завершения регистрации документа вызовом POST /api/{id}/data.

Запрос (Content-Type необходимо установить в application/json):

{
  "title": "document title",
  "description": "document description",
  "signType": "cms",
  "signature": "base64_encoded_cms",
  "emailNotifications": {
    "to": ["user@example.com","other@example.com"],
  },
  "settings": {
    "private": false,
    "signaturesLimit": 2,
    "switchToPrivateAfterLimitReached": true,
    "unique": ["iin"],
    "signersRequirements": [
      {
        "iin": "IIN112233445566"
      }
    ]
  }
}
  • title - заголовок документа;
  • description - описание документа;
  • signType - опциональное поле, тип регистрируемой подписи, поддерживается два строковых значения "cms" и "xml", по умолчанию "cms";
  • signature - в случае CMS это должна быть закодированная в base64 подпись, в случае XML - текстовое представление XML;
  • emailNotifications - опциональный параметр, объект настроек для отправки уведомлений о подписании документа, в данный момент поддерживается только поле to которое должно быть массивом адресов электронной почты;
  • settings - опциональное поле, объект настроек документа, описание приведено в POST /api/{id}/settings - изменение настроек документа.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm"
}
  • documentId - уникальный идентификатор зарегистрированного документа.

# POST /api/{id}/data - фиксация значений хешей документа

  • {id} - идентификатор документа.

Сервис SIGEX не хранит подписанных документов и ему необходим какой-то способ определить относятся ли две подписи к одному и тому же документу. В том случае, когда алгоритмы подписей идентичны, это просто - в подписях присутствуют хеши документа и достаточно требовать их идентичности. В том же случае, если алгоритмы подписей отличаются, то и значения хешей не будут совпадать, так как они вычисляются по разным алгоритмам.

Отличаться алгоритмы подписей могут в том случае, когда один и тот же документ подписывают юридическое лицо (НУЦ выпускает в этом случае сертификаты ГОСТ 34.310-2004) и физическое лицо (НУЦ выпускает сертификаты RSA).

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

Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream.

В качестве тела запроса следует передать оригинальный документ.

В случае XML подписи необходимо передать XML документ именно в том виде в котором он подписывался, а так же выполнить все указанные в XML подписи трансформации - сервис не будет каким-либо обрабом обрабатывать поступающие данные, он будет хешировать их “как есть”. Больше информации можно найти в стандарте https://www.w3.org/TR/xmldsig-core1.

В том случае, если при регистрации документа было указано поле emailNotifications с не пустым списокм получателей, то сервис попробует отправить уведомления получателям по электронной почте. В том случае, если размер документа не большой (ограничение определяется почтовой системой), то сервис прикрепит документ к отправляемым уведомлениям. О том, был ли прикреплен документ к отправленным уведомлениям, сигрализирует значение поля emailNotifications.attached в ответе.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "digests": {
    "oid": "base64_encoded_digest_value",
    "otherOid": "base64_encoded_digest_value",
  },
  "emailNotifications": {
    "attached": true,
    "message": "Failed to send  notification"
  },
  "automaticallyCreatedUserSettings":
  {
    "userId": "IIN123456789012",
    "emailNotificationsEnabled": true,
    "email": "email@GMAIL.COM",
    "modifiedAt": 1586167317737
  }
}
  • documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
  • digests - объект, содержащий вычисленные значения хешей;
  • emailNotifications - опциональное поле, присутствует только в том случае, если при регистрации документа было указано аналогичное поле с не пустым списком получателей, его поле attached говорит о том, был ли прикреплен документ к отправленным уведомлениям, поле message присутствует только в том случае, если в процессе отправки уведомлений произошла ошибка и описывает эту ошибку;
  • automaticallyCreatedUserSettings - опциональное поле, присутствует только в том случае, если пользователь (идентифицируется по ИИН) первый раз регистрирует свою подпись на сервисе, информирует о том, что сервис создал запись с настройками данного пользователя, содержимое идентично GET /api/settings.

# GET /api/{id}?lastSignId=X - получение данных о зарегистрированном документе

  • {id} - идентификатор документа;
  • lastSignId=X - опционально, последний идентификатор подписи после которого нужно возвращаться подписи.

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

Алгоритм получения всех подписей:

  1. получить первый блок подписей не указывая lastSignId;
  2. получить следующий блок подписей установив lastSignId=signId из последнего элемента массива подписей;
  3. повторять до тех пор пока сервис не вернет пустой массив.

Ответ:

{
  "title": "document title",
  "description": "document description",
  "emailNotifications": {
    "to": ["user@example.com","other@example.com"],
  },
  "settings": {
    "private": false,
    "signaturesLimit": 2,
    "switchToPrivateAfterLimitReached": true,
    "unique": ["iin"],
    "signersRequirements": [
      {
        "iin": "IIN112233445566"
      }
    ]
  },
  "signaturesTotal": 2,
  "signatures": [
  ],
}
  • title - заголовок документа;
  • description - описание документа;
  • emailNotifications - информация о том, кому была запрошена отправка уведомлений при регистрации первой подписи;
  • settings - объект настроек документа, описание приведено в POST /api/{id}/settings - изменение настроек документа;
  • signaturesTotal - общее количество подписей документа;
  • signatures - массив объектов с данными о подписях документа.

Структура объекта данных подписи:

{
  "userId": "IIN1234567890AB",
  "businessId": "BIN1234567890AB",
  "subject": "SERIALINUMBER=IIN1234567890AB, CN=User",
  "signAlgorithm": "1.2.840.113549.1.1.11",
  "policyIds": ["OID.0","OID.1"],
  "extKeyUsages": ["OID.0","OID.1"],
  "storedAt": 1568809427182,
  "signId": 1,
  "signType": "cms"
}
  • userId - ИИН подписавшего;
  • businessId - БИН подписавшего, доступен только в случае использования сертификата юридического лица;
  • subject - имя владельца (Subject) сертификата;
  • signAlgorithm - OID алгоритма подписи;
  • policyIds - массив OID-ов политик использования сертификата подписавшего;
  • extKeyUsages - массив OID-ов расширенного использования ключа;
  • storedAt - время сохранения подписи в системе (миллисекунд с UNIX Epoch);
  • signId - уникальный идентификатор подписи в системе;
  • signType - тип подписи, поддерживается два строковых значения "cms" и "xml".

# POST /api/{id} - добавление подписи к документу

  • {id} - идентификатор документа.

В рамках регистрации новой подписи будет выполнена проверка подписи а так же, в случае их отсутствия, сбор данных OCSP и TSP для этой подписи.

Сервис допускает регистрацию двух типов подписей:

  • CMS - можно получить у NCALayer методом createCMSSignatureFromBase64;
  • XML - можно получить у NCALayer методом signXml, но с некоторыми оговорками (см. ниже).

CMS подписи не должны включать в себя подписанных данных (последний параметр createCMSSignatureFromBase64 и createCAdESFromBase64 следует устанавливать в false), в одном CMS допускается наличие только одной подписи (то есть одного SignerInfo).

Сервис допускает наличие данных TSP (метка времени) в неподписываемом атрибуте CMS signature-time-stamp со значением, содержащим метку времени. Допускается наличие только одной метки времени.

Сервис допускает наличие данных OCSP (статус сертификата) в неподписываемом атрибуте CMS revocation-values со значением, содержащим в поле RevocationValues.ocspVals[0] OCSP квитанцию со статусом сертификата подписавшего. Допускается наличие только одной квитанции.

Под XML подписью сервис подразумевает только ту часть XML, которая содержит данные о подписи - то есть только элемент <ds:Signature xmlns:ds=“http://www.w3.org/2000/09/xmldsig#">. В том случае, если подпись была сформирована с помощью вызова signXml утилиты NCALayer, то корректное извлечение необходимого элемента и оформление его в соответствии с https://www.w3.org/TR/xmldsig-core1 ложится на плечи разработчика.

Запрос (Content-Type необходимо установить в application/json):

{
  "signType": "cms",
  "signature": "base64_encoded_cms"
}
  • signType - опциональное поле, тип регистрируемой подписи, поддерживается два строковых значения "cms" и "xml", по умолчанию "cms";
  • signature - в случае CMS это должна быть закодированная в base64 подпись, в случае XML - текстовое представление XML.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "automaticallyCreatedUserSettings":
  {
    "userId": "IIN123456789012",
    "emailNotificationsEnabled": true,
    "email": "email@GMAIL.COM",
    "modifiedAt": 1586167317737
  }
}
  • documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
  • automaticallyCreatedUserSettings - опциональное поле, присутствует только в том случае, если пользователь (идентифицируется по ИИН) первый раз регистрирует свою подпись на сервисе, информирует о том, что сервис создал запись с настройками данного пользователя, содержимое идентично GET /api/settings.

# POST /api/{id}/verify - проверка подписей

  • {id} - идентификатор документа.

Данный метод выполнит следующее:

  • удостоверится в том, что сохраненные в системе подписи являются подписями именно под переданным документом (то есть что не произошло подмены или изменения документа);
  • выполнит проверку каждой подписи на момент ее регистрации в системе используя сохраненные данные OCSP и TSP.

Запрос должен содержать HTTP заголовок Content-Type=application/octet-stream.

В качестве тела запроса следует передать оригинальный документ.

В случае XML подписи необходимо передать XML документ именно в том виде в котором он подписывался, а так же выполнить все указанные в XML подписи трансформации - сервис не будет каким-либо обрабом обрабатывать поступающие данные, он будет хешировать их “как есть”. Больше информации можно найти в стандарте https://www.w3.org/TR/xmldsig-core1.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm"
}
  • documentId - идентификатор документа, должен быть идентичен переданному идентификатору.

# GET /api/{id}/signature/{signId}?signFormat=X - экспорт одной подписи документа

  • {id} - идентификатор документа;
  • {signId} - идентификатор подписи;
  • signFormat=X - опционально, формат экспорта, по умолчанию 0.

Поддерживаются следующие форматы экспорта:

  • 0 (по умолчанию) - CMS с интегрированными меткой времени (TimeStampToken, CMS атрибут с OID 1.2.840.113549.1.9.16.2.14) и квитанцией OCSP (BasicOCSPResponse, CMS атрибут с OID-ом 1.2.840.113549.1.9.16.2.24);
  • 1 - оригинальный CMS, принятый в систему при добавлении подписи.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "signId": 1,
  "signType": "cms",
  "signFormat": 0,
  "signature": "base64_encoded_cms"
}
  • documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
  • signId - уникальный идентификатор подписи в системе;
  • signType - тип подписи, поддерживается два строковых значения "cms" и "xml";
  • signFormat - формат подписи;
  • signature - в случае CMS это закодированная в base64 подпись, в случае XML - текстовое представление XML.

# GET /api/{id}/signature/{signId}/qr?signFormat=X&qrVersion=25&qrLevel=M - экспорт подписи в виде набора QR кодов

  • {id} - идентификатор документа;
  • {signId} - идентификатор подписи;
  • signFormat=X - опционально, формат экспорта, по умолчанию 0;
  • qrVersion=25 - опционально, версия QR кода (размер), по умолчанию 25, версии ниже 11 не поддерживаются, детали тут https://www.qrcode.com/en/about/version.html;
  • qrLevel=M - опционально, уровень коррекции ошибок (ECC), по умолчанию M, детали тут https://www.qrcode.com/en/about/version.html.

Поддерживаются следующие форматы экспорта:

  • 0 (по умолчанию) - CMS с интегрированными меткой времени (TimeStampToken, CMS атрибут с OID 1.2.840.113549.1.9.16.2.14) и квитанцией OCSP (BasicOCSPResponse, CMS атрибут с OID-ом 1.2.840.113549.1.9.16.2.24);
  • 1 - оригинальный CMS, принятый в систему при добавлении подписи.

Формирование набора QR кодов осуществляется по следующему алгоритму:

  • Подпись в запрошенном представлении упаковывается в ZIP архив методом DEFLATE. Имя файла, содержащегося в архиве формируется как {signId}.{signType}, то есть имя файла - это идентификатор подписи, а расширение - тип подписи (в текущей реализации "xml" или "cms").
  • Формируется base64 представление ZIP архива.
  • Base64 представление разбивается на части, каждая часть упаковывается в описанную ниже JSON структуру. Размер каждой части определяется исходя из параметров запроса qrVersion (версия) и qrLevel (уровень коррекции ошибок).
  • Полученные JSON структуры кодируются в изображения, QR коды, в формате PNG.
  • Из набора изображений формируется массив qrCodes который является частью ответа, изображения в нем закодированы в base64.

JSON структура части подписи:

{
  "documentId": "Nzxn6JCumwKKhEv4",
  "signId": 9,
  "signType": "xml",
  "total": 7,
  "index": 1,
  "data": "part_of_archived_and_base64_encoded_signature"
}

где:

  • documentId - идентификатор документа;
  • signId - уникальный идентификатор подписи в системе;
  • signType - тип подписи, поддерживается два строковых значения "cms" и "xml";
  • total - общее количество частей;
  • index - индекс данной части;
  • data - строка, часть base64 представления ZIP архива.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "signId": 1,
  "signType": "cms",
  "signFormat": 0,
  "qrCodes": [
    "base64_encoded_png_with_qr_code_part1",
    ...
    "base64_encoded_png_with_qr_code_partn"
  ]
}
  • documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
  • signId - уникальный идентификатор подписи в системе;
  • signType - тип подписи, поддерживается два строковых значения "cms" и "xml";
  • signFormat - формат подписи;
  • qrCodes - массив строк каждая из которых содержит закодированное в base64 изображение в формате PNG с закодированным QR кодом.

# POST /api/{id}/settings - изменение настроек документа

  • {id} - идентификатор документа.

Отправка нового объекта с настройками документа. Все поля объекта опциональны, то есть можно указывать только те настройки, которые должны отличаться от настройек по умолчанию.

Все текущие настройки документа будут перезаписаны. Даже в том случае, если в передаваемом новом объекте настроек какая-то настройка отсутствует, будет использовано значение по умолчанию.

Запрос (Content-Type необходимо установить в application/json):

{
  "private": false,
  "signaturesLimit": 2,
  "switchToPrivateAfterLimitReached": true,
  "unique": ["iin", "bin"],
  "signersRequirements": [
    {
      "iin": "IIN112233445566"
    },
    {
      "bin": "BIN112233445566",
      "authorities": ["OID1", "OID2"],
    },
    {
      "bin": "BIN112233445566",
      "iin": "IIN112233445566"
    },
    {
      "bin": "BIN112233445566",
      "authorities": ["OID1", "OID2"],
      "iin": "IIN112233445566"
    }
  ]
}
  • private - опциональное поле, определяет ограничен ли доступ к документу (см. Аутентификация пользователей и информационных систем), либо он является общедоступным документом, по умолчанию false;
  • signaturesLimit - опциональное поле, ограничение на разрешенное количество подписей под документом (0 - не ограничено), по умолчанию 0;
  • switchToPrivateAfterLimitReached - опциональное поле, определяет должен ли сервис автоматически переключить настройку private в true после того, как будет зарегистрировано signaturesLimit подписей, по умолчанию false;
  • unique - опциональное поле, массив требований к уникальности, может включать в себя константы "iin" и "bin", константы ограничивают возможность регистрации подписей с идентичными ИИН и БИН, по умолчанию [] (то есть ограничения отсутствуют);
  • signersRequirements - опциональное поле, массив требований к подписям, в том случае, если он не пуст, каждая регистрируемая подпись перед регистрацией должна быть проверена на соответствие требованиям (должна удовлетворить хотя бы одному элементу массива - объединяются через ИЛИ), по умолчанию [] (то есть требования отсутствуют).

Требования signersRequirements - это объекты со следующими опциональными полями (необходимо одно любое поле):

{
  "bin": "BIN112233445566",
  "authorities": ["OID1", "OID2"],
  "iin": "IIN112233445566"
}
  • bin - опциональное поле, в сертификате в подписи должен присутствовать соответствующий БИН;
  • authorities - опциональное поле, в сертификате в подписи должно присутствовать одно из указанных полномочий;
  • iin - опциональное поле, в сертификате в подписи должен присутствовать соответствующий ИИН.

В том случае, если указано несколько полей, то они ужесточают друг друга (объединяются через И).

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm"
}
  • documentId - идентификатор документа, должен быть идентичен переданному идентификатору.

# GET /api/{id}/settingsAudit?lastEventId=X - аудит изменений настроек документа

  • {id} - идентификатор документа;
  • lastEventId=X - опционально, последний идентификатор записи после которого нужно возвращаться записи.

Возвращает журнал изменений настроек документа.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "eventsTotal": 3,
  "events": []
}
  • documentId - идентификатор документа, должен быть идентичен переданному идентификатору;
  • eventsTotal - количество изменений зарегистрированных в системе;
  • events - массив объектов описывающих изменения.

Структура объектов описывающих изменения:

{
  "eventId": 1,
  "original": {},
  "modified": {},
  "modifiedBy": "IIN123456789",
  "modifiedByDigest": "XXXXXXXXXXXXXXX",
  "modifiedAt": 1586167317737
}
  • eventId - идентификатор события;
  • original - настройки до изменения;
  • modified - настройки после изменения;
  • modifiedBy - кем были произведены изменения, ИИН;
  • modifiedByDigest - хеш клиентского сертификата в том случае, если изменение было выполненой от имени информационной системы;
  • modifiedAt - момент изменения в миллисекундах с UNIX Epoch.

# POST /api/exported - получение идентификаторов документа и подписи по ранее экспортированной подписи документа

В передаваемой подписи допускается наличие метки времени TSP (signature-time-stamp) и квитанции OCSP (revocation-values). Важно чтобы метка времени и квитанция, в том случае, если они присутствуют, были именно теми же, которые зарегистрированы в сервисе. Это обусловлено тем, что метка времени и квитанция фиксируют момент подписания и, в том случае, если были получены другие метка времени и квитанция, эти данные не будут совпадать с теми, которые зарегистрированы в сервисе.

В частности поддерживаются подписи полученные следующими способами:

  • через API SIGEX с помощью запроса GET /api/{id}/signature/{signId};
  • методом createCMSSignatureFromBase64 NCALayer - такая подпись содержит метку времени, но не содержит квитанцию OCSP;
  • методом createCAdESFromBase64 NCALayer - такая подпись не содержит ни метки времени, ни квитанции OCSP.

Запрос (Content-Type необходимо установить в application/json):

{
  "signType": "cms",
  "signature": "base64_encoded_cms"
}
  • signType - опциональное поле, тип регистрируемой подписи, поддерживается два строковых значения "cms" и "xml", по умолчанию "cms";
  • signature - в случае CMS это должна быть закодированная в base64 подпись, в случае XML - текстовое представление XML.

Ответ:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "signId": 1
}
  • documentId - уникальный идентификатор документа;
  • signId - уникальный идентификатор подписи.

# POST /api/auth - аутентификация, подготовительный этап - получение блока случайных данных

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

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

Вопросы интеграции аутентификации по цифровым сертификатам в информационные системы освещен в заметке Аутентификация по цифровым сертификатам

Запрос (Content-Type необходимо установить в application/json):

{
}

Ответ:

{
  "nonce": "base64_encoded_nonce"
}
  • nonce - блок случайных данных в base64.

# POST /api/auth - аутентификация

Для выполнения аутентификации необходимо передать сервису цифровую подпись ранее полученного блока случайных данных. В том случае, если проверка подписи сервисом пройдет успешно, пользователь будет идентифицирован по данным содержащемся в его сертификате.

Поддерживается два режима работы:

  • внутренняя аутентификация для нужд сервиса SIGEX;
  • внешняя аутентификация для нужд сторонней информационной системы.

В режиме внутренней аутентификации для хранения информации об аутентификации используется cookie (Secure, HttpOnly и SameSite=Strict) с именем jwt в котором хранятся данные о прошедшем аутентификацию пользователе в формате JWT. Полезная нагрузка JWT токена совпадает с ответом данного API.

При обращении к защищенным API сервис проверяет наличие в заголовках запроса cookie jwt и на основании данных в JWT токене принимает решение об авторизации.

В рамках обработки всех API выполняется проверка оставшего времени жизни JWT токена в cookie jwt и, при необходимости, его обновление. Новый JWT токен передается в ответе в cookie jwt.

Так же в режиме внутренней аутентификации в SIGEX будет создан профиль с настройками нового пользователя.

В режиме внешней аутентификации никаких cookie не устанавливается и профилей не создается, сторонняя информационная система получает ответ с данными сертификата которые она может использовать для авторизации (принятия решения о предоставлении пользователю прав доступа в систему).

Вопросы интеграции аутентификации по цифровым сертификатам в информационные системы освещен в заметке Аутентификация по цифровым сертификатам

Запрос (Content-Type необходимо установить в application/json):

{
  "nonce": "base64_encoded_nonce",
  "signature": "base64_encoded_cms",
  "external": true
}
  • nonce - блок случайных данных в base64 полученный от сервиса на подготовительном этапе;
  • signature - закодированная в base64 подпись nonce, ее можно получить у NCALayer методом createCAdESFromBase64;
  • external - опциональное поле, позволяет установить режим внешней аутентификации, по умолчанию false.

Ответ:

{
  "userId": "IIN1234567890AB",
  "businessId": "BIN1234567890AB",
  "subject": "SERIALINUMBER=IIN1234567890AB, CN=User",
  "signAlgorithm": "1.2.840.113549.1.1.11",
  "policyIds": ["OID.0","OID.1"],
  "extKeyUsages": ["OID.0","OID.1"]
}
  • userId - ИИН пользователя прошедшего аутентификацию;
  • businessId - БИН пользователя прошедшего аутентификацию, доступен только в случае использования сертификата юридического лица;
  • subject - имя владельца (Subject) сертификата;
  • signAlgorithm - OID алгоритма подписи;
  • policyIds - массив OID-ов политик использования сертификата;
  • extKeyUsages - массив OID-ов расширенного использования ключа.

# POST /api/auth - сброс аутентификации

Технически сброс аутентификации заключается в возврате cookie с именем jwt с пустым значением, атрибутом Max-Age установленным в 0 и атрибутом Expires содержащим дату до текущей даты. Ожидаемая реакция совместимого браузера заключается в удалении cookie с именем jwt из локального хранилища.

Запрос (Content-Type необходимо установить в application/json):

{
  "logout": true
}
  • logout - должно быть установлено в true.

Ответ:

{
}

# GET /api/auth - текущее состояние аутентификации

В случае том случае, если аутентификация пройдена и в заголовках запроса присутствовал cookie jwt, то ответ будет идентичен тому, который возвращает POST /api/auth - аутентификация.


  • from=xxx - с какого момента следует искать документы, значение следует указывать в миллисекундах с UNIX Epoch;
  • until=yyy - до какого момента следует искать документы, значение следует указывать в миллисекундах с UNIX Epoch;
  • organization=true - опциональный параметр, определяет следует ли искать документы физического лица или организации, по умолчанию false.

Ответ сервиса зависит от значения organization:

  • false - в этом случае сервис вернет документы которые подписывал аутентифицированный пользователь (как физическое лицо либо как представитель юридического лица);
  • true - в том случае, если пользователь прошел аутентификацию с помощью сертификата представителя организации (юридического лица) и у него в сертификате присутствуют полномочия указанные в настройках организации, то метод вернет перечень документов, которые подписывали любые представители этой организации.

Сервис будет возвращать документы сортированными в порядке убывания даты их регистрации, то есть сначала самые новые.

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

  1. получить первый блок документов установив желаемые from=xxx и until=yyy;
  2. получить следующий блок докментов установив until=storedAt из последнего элемента массива документов;
  3. повторять до тех пор пока сервис не вернет пустой массив.

Ответ:

{
  "documentsTotal": 3,
  "documents": []
}
  • documentsTotal - количество документов удовлетворяющих запросу;
  • documents - массив объектов документов.

Структура объекта данных документа:

{
  "documentId": "lQsqLBaS4nQAIIMm",
  "storedAt": 11111111111,
  "title": "document title",
  "description": "document description"
}
  • documentId - уникальный идентификатор документа;
  • storedAt - момент регистрации документа в системе (миллисекунд с UNIX Epoch).;
  • title - заголовок документа;
  • description - описание документа.

# GET /api/settings - получить настройки аутентифицированного пользователя

Ответ:

{
  "userId": "IIN123456789012",
  "emailNotificationsEnabled": true,
  "email": "user@example.com",
  "modifiedAt": 1585827107000
}
  • userId - ИИН пользователя;
  • emailNotificationsEnabled - флаг указывающий включена ли отправка уведомлений по электронной почте для данного пользователя;
  • email - электронный адрес пользователя, поле может содержать пустую строку ("");
  • modifiedAt - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch. В случае, если настройки ранее не были сохранены, то поле содержит 0.

# POST /api/settings - сохранить настройки аутентифицированного пользователя

Запрос (Content-Type необходимо установить в application/json):

{
  "emailNotificationsEnabled": false,
  "email": "otheruser@example.com"
}
  • emailNotificationsEnabled - новое значение флага указывающего включена ли отправка уведомлений по электронной почте для данного пользователя;
  • email - новый электронный адрес пользователя, разрешено передавать пустую строку ("");

Ответ:

{
  "userId": "IIN123456789012",
  "modifiedAt": 1585827107000
}
  • userId - ИИН пользователя;
  • modifiedAt - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch.

# GET /api/settingsAudit?lastEventId=X - аудит изменений настроек пользователя

  • lastEventId=X - опционально, последний идентификатор записи после которого нужно возвращаться записи.

Возвращает журнал изменений настроек пользователя.

Ответ:

{
  "userId": "IIN112233445566",
  "eventsTotal": 3,
  "events": []
}
  • userId - ИИН пользователя;
  • eventsTotal - количество изменений зарегистрированных в системе;
  • events - массив объектов описывающих изменения.

Структура объектов описывающих изменения:

{
  "eventId": 1,
  "original": {},
  "modified": {},
  "modifiedAt": 1586167317737
}
  • eventId - идентификатор события;
  • original - настройки до изменения;
  • modified - настройки после изменения;
  • modifiedAt - момент изменения в миллисекундах с UNIX Epoch.

# GET /api/organizationSettings - получить настройки организации аутентифицированного пользователя

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

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

Ответ:

{
  "tlsCertificatesList": [
    {
      "description": "First certificate",
      "body": "PEM-ENCODED-CERT-1",
      "disabled": false
    },
    {
      "description": "Second certificate",
      "body": "PEM-ENCODED-CERT-2",
      "disabled": false
    },
    {
      "description": "Third certificate",
      "body": "PEM-ENCODED-CERT-3",
      "disabled": true
    },
  ],

  "documentsAccess": {
    "authorities": ["OID1", "OID2"],
    "tlsCertificatesIndices": [0]
  },
  "documentsList": {
    "authorities": ["OID1", "OID2"],
    "tlsCertificatesIndices": [0, 1]
  },
  "documentsSettings": {
    "authorities": ["OID1", "OID2"],
    "tlsCertificatesIndices": [1]
  },
  "organizationSettings": {
    "authorities": ["OID1", "OID2"],
    "tlsCertificatesIndices": [1]
  }
}
  • tlsCertificatesList - массив клиентских сертификатов информационных систем;
  • documentsAccess - контроль доступа к документам организации;
  • documentsList - контроль доступа к перечислению документов организации;
  • documentsSettings - контроль доступа к редактированию настроек документов организации;
  • organizationSettings - контроль доступа к просмотру и редактированию настроек организации.

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

  • description - описание;
  • body - сертификат в формате PEM, то есть строка;
  • disabled - флаг помечающий сертификат как отключенный.

Объекты контроля доступа определяют требования к доступу к тому или иному функционалу и имеют следующую структуру:

  • authorities - массив, определяет полномочия, наличие одного из которых достаточно для предоставления доступа;
  • tlsCertificatesIndices - массив индексов сертификатов из tlsCertificatesList, определяет по каким сертификатам разрешен доступ.

# POST /api/organizationSettings - сохранить настройки организации аутентифицированного пользователя

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

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

Запрос (Content-Type необходимо установить в application/json):

{
  "tlsCertificatesList": [
    {
      "description": "First certificate",
      "body": "PEM-ENCODED-CERT-1",
      "disabled": false
    },
    {
      "description": "Second certificate",
      "body": "PEM-ENCODED-CERT-2",
      "disabled": false
    },
    {
      "description": "Third certificate",
      "body": "PEM-ENCODED-CERT-3",
      "disabled": true
    },
  ],

  "documentsAccess": {
    "authorities": ["OID1", "OID2"],
    "tlsCertificatesIndices": [0]
  },
  "documentsList": {
    "authorities": ["OID1", "OID2"],
    "tlsCertificatesIndices": [0, 1]
  },
  "documentsSettings": {
    "authorities": ["OID1", "OID2"],
    "tlsCertificatesIndices": [1]
  },
  "organizationSettings": {
    "authorities": ["OID1", "OID2"],
    "tlsCertificatesIndices": [1]
  }
}
  • tlsCertificatesList - массив клиентских сертификатов информационных систем;
  • documentsAccess - контроль доступа к документам организации;
  • documentsList - контроль доступа к перечислению документов организации;
  • documentsSettings - контроль доступа к редактированию настроек документов организации;
  • organizationSettings - контроль доступа к просмотру и редактированию настроек организации.

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

  • description - описание;
  • body - сертификат в формате PEM, то есть строка;
  • disabled - флаг помечающий сертификат как отключенный.

Объекты контроля доступа определяют требования к доступу к тому или иному функционалу и имеют следующую структуру:

  • authorities - массив, определяет полномочия, наличие одного из которых достаточно для предоставления доступа;
  • tlsCertificatesIndices - массив индексов сертификатов из tlsCertificatesList, определяет по каким сертификатам разрешен доступ.

Ответ:

{
  "businessId": "BIN123456789012",
  "modifiedAt": 1585827107000
}
  • userId - БИН организации;
  • modifiedAt - дата последнего сохранения (изменения) настроек в миллисекундах с UNIX Epoch.

# GET /api/organizationSettingsAudit?lastEventId=X - аудит изменений настроек организации

  • lastEventId=X - опционально, последний идентификатор записи после которого нужно возвращаться записи.

Возвращает журнал изменений настроек организации.

Ответ:

{
  "businessId": "BIN112233445566",
  "eventsTotal": 3,
  "events": []
}
  • businessId - БИН организации;
  • eventsTotal - количество изменений зарегистрированных в системе;
  • events - массив объектов описывающих изменения.

Структура объектов описывающих изменения:

{
  "eventId": 1,
  "original": {},
  "modified": {},
  "modifiedBy": "IIN123456789",
  "modifiedByDigest": "XXXXXXXXXXXXXXX",
  "modifiedAt": 1586167317737
}
  • eventId - идентификатор события;
  • original - настройки до изменения;
  • modified - настройки после изменения;
  • modifiedBy - кем были произведены изменения, ИИН;
  • modifiedByDigest - хеш клиентского сертификата в том случае, если изменение было выполненой от имени информационной системы;
  • modifiedAt - момент изменения в миллисекундах с UNIX Epoch.

# GET /api/organizationPermissions - получить права аутентифицированного пользователя в разрезе его организации

Ответ:

{
  "documentsAccess": true,
  "documentsList": true,
  "documentsSettings": true,
  "organizationSettings": true
}
  • documentsAccess - имеет ли текущий аутентифицированный пользователь доступ к документам организации;
  • documentsList - имеет ли текущий аутентифицированный пользователь право перечислять документы организации;
  • documentsSettings - имеет ли текущий аутентифицированный пользователь право менять настройки документов организации;
  • organizationSettings - имеет ли текущий аутентифицированный пользователь право менять настройки организации.

# GET /api/version - версия сервиса

Ответ:

{
  "version":"vX.X.X",
  "buildTimeStamp":"XXXXXXXXXX"
}
  • version - версия сервиса;
  • buildTimeStamp - время сборки сервиса в секундах с UNIX Epoch.