Аутентификация и контроль доступа

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

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

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

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

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

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

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

• POST /api/auth - аутентификация, подготовительный этап - получение блока случайных данных
• POST /api/auth - аутентификация
• POST /api/auth - сброс аутентификации - не используется в режиме внешней аутентификации
• GET /api/auth - текущее состояние аутентификации - не используется в режиме внешней аутентификации

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

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

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

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

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

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

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

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

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

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

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

• TLS 1.3.

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

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

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

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

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

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

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

Доступ к подписанным данным документа предоставляется аналогично доступу к информации о документе, но с ограничением - он возможен только аутентифицированным пользователям и информационным системам (за исключением специального режима активируемого с помощью publicDuringPreregistration и publicWhileLessThanSignatures, в этом случае аутентификация не требуется).

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

Аналоичный режим работает в том случае, если для publicWhileLessThanSignatures установлено значение больше нуля не зависимо от того, была выполнена регистрация или предрегистрация.

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

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

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

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

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

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

Перечисление документов юридического лица:

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

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

Изменение настроек пакета документов

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

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

• Пакеты документов пользователя (их возможно перечислять после прохождения аутентификации по сертификату физического, либо юридического лица) - это пакеты документов в настройках которых пользователь указан в packageAccess как физическое лицо или сотрудник юридического лица.
• Пакеты документов юридического лица (их возможно перечислять после прохождения аутентификации по сертификату юридического лица, либо информационной системой по двустороннему mTLS) - это пакеты документов в настроках которых в packageAccess указан БИН юридического лица, а так же зарегистрированные информационными системами этой же организации.

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

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

Перечисление пакетов документов юридического лица:

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

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

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

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

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