POST /api/auth - аутентификация, подготовительный этап - получение блока случайных данныхАутентификация основана на подписании пользователем блока случайных данных полученных от сервиса. Подготовительный этап заключается в передаче сервису запроса на новый блок случайных данных.
Важно! Каждый блок случйных данных может быть использован только один раз и имеет ограниченный срок действия.
Вопросы интеграции аутентификации по цифровым сертификатам в информационные системы освещен в заметке Аутентификация по цифровым сертификатам
Попробовать этот API в Postman
Запрос (Content-Type необходимо установить в application/json):
{
}
Ответ:
{
"nonce": "base64_encoded_nonce"
}
nonce - блок случайных данных в base64.POST /api/auth - аутентификацияДля выполнения аутентификации необходимо передать сервису цифровую подпись ранее полученного блока случайных данных. В том случае, если проверка подписи сервисом пройдет успешно, пользователь будет идентифицирован по данным содержащемся в его сертификате.
Поддерживается два режима работы:
В режиме внутренней аутентификации для хранения информации об аутентификации используется cookie (Secure, HttpOnly и SameSite=Strict) с именем jwt в котором хранятся данные о прошедшем аутентификацию пользователе в формате JWT. Полезная нагрузка JWT токена содержит информацию, необходимую для идентификации пользователя.
При обращении к защищенным API сервис проверяет наличие в заголовках запроса cookie jwt и на основании данных в JWT токене принимает решение об авторизации.
В рамках обработки всех API выполняется проверка оставшего времени жизни JWT токена в cookie jwt и, при необходимости, его обновление. Новый JWT токен передается в ответе в cookie jwt.
Так же в режиме внутренней аутентификации в SIGEX будет создан профиль с настройками нового пользователя.
В режиме внешней аутентификации никаких cookie не устанавливается и профилей не создается, сторонняя информационная система получает ответ с данными сертификата которые она может использовать для авторизации (принятия решения о предоставлении пользователю прав доступа в систему).
Вопросы интеграции аутентификации по цифровым сертификатам в информационные системы освещен в заметке Аутентификация по цифровым сертификатам
Поддерживаются два типа подписей:
JS библиотека с открытым исходным кодом https://github.com/sigex-kz/ncalayer-js-client поддерживает все эти варианты.
CMS подписи поддерживаются в DER и PEM кодировках.
Попробовать этот API в Postman
Запрос (Content-Type необходимо установить в application/json):
{
"nonce": "base64_encoded_nonce",
"signature": "signature",
"external": true
}
nonce - блок случайных данных в base64 полученный от сервиса на подготовительном этапе;signature - в случае CMS это должна быть подпись в кодировке DER дополнительно закодированная в base64, либо в кодпировке PEM без дополнительного кодирования, в случае XML - текстовое представление XML;external - опциональное поле, позволяет установить режим внешней аутентификации, по умолчанию false.Ответ:
{
"userId": "IIN1234567890AB",
"businessId": "BIN1234567890AB",
"email": "user@example.com",
"subject": "SERIALINUMBER=IIN1234567890AB,CN=User",
"subjectStructure": [
[
{
"oid": "2.5.4.5",
"name": "SERIALINUMBER",
"valueInB64": false,
"value": "IIN1234567890AB"
}
],
[
{
"oid": "2.5.4.3",
"name": "CN",
"valueInB64": false,
"value": "User"
}
]
],
"subjectAltName": "rfc822Name=user@example.com",
"subjectAltNameStructure": [
{
"type": "rfc822Name",
"value": "user@example.com"
}
],
"signAlgorithm": "1.2.840.113549.1.1.11",
"keyStorage": "1.2.398.3.3.5.1.1",
"policyIds": ["OID.0","OID.1"],
"extKeyUsages": ["OID.0","OID.1"],
"certificateValidFrom": 1535622190000,
"certificateValidUntil": 1630120980000
}
userId - ИИН пользователя прошедшего аутентификацию;businessId - БИН пользователя прошедшего аутентификацию, доступен только в случае использования сертификата юридического лица;email - адрес электронной почты из subject, либо из subjectAltName, поле может отсутствовать в том случае, если электронная почта не указана (опциональное поле);subject - имя владельца (Subject) сертификата сформированное в соответствии с RFC 4514;subjectStructure - структурированное представление имени владельца (Subject) сертификата;subjectAltName - альтернативное имя владельца сертификата в соответствии с RFC 4514 (опциональное поле);subjectAltNameStructure - структурированное представление альтернативного имени владельца сертификата (опциональное поле);signAlgorithm - OID алгоритма подписи;keyStorage - OID типа хранилища (опциональное поле);policyIds - массив OID-ов политик использования сертификата;extKeyUsages - массив OID-ов расширенного использования ключа;certificateValidFrom - начало срока действия сертификата;certificateValidUntil - окончание срока действия сертификата.Структурированное представление имени владельца (Subject) сертификата - это массив, содержащий набор RDN, каждый из которых, в свою очередь, является массивом аттрибутов. Представление основывается на структуре поля Subject сертификата, описанного в RFC 5280.
Каждый атрибут представлен в виде объекта:
{
"oid": "2.5.4.3",
"name": "CN",
"valueInB64": false,
"value": "User CommonName",
}
oid - объектный идентификатор типа атрибута;name - тестовое представление типа атрибута в соответствии со структурами регистрационных свидетельств (сертификатов) описанных в документе “Правила применения регистрационных свидетельств НУЦ РК” доступного на портале НУЦ РК в разделе Документация;valueInB64 - флаг, определяющий является ли значение в поле value строкой, либо base64 представлением бинарных данных;value - значение атрибута, значения некоторых атрибутов не могут быть представлены в текстовом виде, в этом случае в это поле будет записано base64 представление бинарного значения атрибута и valueInB64 будет установлен в true.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 - аутентификация.
GET /api/authLog - журнал аутентификацииВозвращает информацию о последних зарегистрированных событиях аутентификации выполнившего вход пользователя.
Ответ:
{
"userId": "IIN012345678901",
"businessId": "BIN9876543212098",
"eventsTotal": 3,
"events": []
}
userId - ИИН выполнившего вход пользователя;businessId - БИН организации, чьим сотрудником является выполнивший вход пользователь, доступен только в случае использования для аутентификации сертификата сотрудника юридического лица;eventsTotal - количество событий в журнале;events - массив объектов описывающих события аутентификации.Структура объекта описывающего событие аутентификации:
{
"authAt": 1585827107000,
"serialNumber": "4beb939d4fb14b047f3bcddf3881eb2ff9acbeb5",
"issuer": "CN=ҰЛТТЫҚ КУӘЛАНДЫРУШЫ ОРТАЛЫҚ (GOST) 2022,C=KZ",
"ip": "1.1.1.1"
}
authAt - время регистрации события аутентификации в миллисекундах с UNIX Epoch;serialNumber - серийный номер сертификата, использованного для аутентификации;issuer - DN имя издателя сертификата, использованного при аутентификации;ip - IP адрес с которого выполнялась аутентификация.Портал SIGEX использует файлы cookie и другие технологии хранения данных в браузере только для персонализации пользовательского опыта: отображения уведомлений, напоминаний и подсказок, а так же хранения некоторых настроек. Мы не используем этих технологий для слежения за своими пользователями, сбора о них информации или отображения рекламы и не предоставляем подобных возможностей третим сторонам. Детали изложены в Политике конфиденциальности.
Мы проводим вебинары про электронные документы, ЭЦП и юридическую значимость.