API: аутентификация


Все методы данного раздела следуют общим правилам отправки запросов, интерпретации ответов и обработки ошибок: в штатном режиме сервис возвращает HTTP код 200 и ответ в формате JSON, а при возникновении ошибки — объект с полями message и requestID. Перечень возможных сообщений об ошибках доступен на странице Известные строки.

Коллекции для Postman

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

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

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

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

Попробовать этот API в Postman

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

{
}

Ответ:

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

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

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

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

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

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

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

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

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

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

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

Поддерживается подпись в формате CMS, её можно получить у NCALayer методом sign нового модуля kz.gov.pki.knca.basics.

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 без дополнительного кодирования;
  • external - опциональное поле, позволяет установить режим внешней аутентификации, по умолчанию false.

Ответ:

{
  "userId": "IIN1234567890AB",
  "businessId": "BIN1234567890AB",
  "email": "user@example.com",
  "ca": "certification authority id",
  "automaticallyCreatedUserSettings": {},
  "automaticallyCreatedOrgSettings": {},
  "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, поле может отсутствовать в том случае, если электронная почта не указана (опциональное поле);
  • ca - идентификатор удостоверяющего центра, выпустившего сертификат; переводы доступны в GET /api/strings - перечень известных строк через consts.certificationAuthorities[ca];
  • automaticallyCreatedUserSettings - опциональное поле, присутствует только в том случае, если пользователь (идентифицируется по ИИН) первый раз проходит аутентификацию на сервисе, информирует о том, что сервис создал запись с настройками данного пользователя, содержимое идентично GET /api/settings - получить настройки аутентифицированного пользователя;
  • automaticallyCreatedOrgSettings - опциональное поле, присутствует только в том случае, если сотрудник организации (идентифицируется по БИН) первый раз проходит аутентификацию на сервисе, информирует о том, что сервис создал запись с настройками данной организации, содержимое идентично GET /api/organizationSettings - получить настройки организации аутентифицированного пользователя;
  • 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 адрес с которого выполнялась аутентификация.

Developed by "Mnozhestvo" LLC in 2026