Перейти к содержанию

Организация (юридическое лицо) — руководство по подключению

Дата: 2026-07-04. Область: регистрация организации на платформе eID, управление правами представительства, использование e-Seal (печати организации) и интеграция на стороне RP (электронной услуги). Обоснование дизайна: docs/ORG_AUTH_SIGN_PLAN.md; стандарты: SK ID Solutions SK-CPR-ORG v13.0, ETSI EN 319 412-1/-3/-5.

Основной принцип (эстонская модель): у организации НЕТ учётной записи в приложении, телефона, PIN-кода и порогового ключа. Любое действие организации происходит через три механизма: 1. Вход как организация = физическое лицо входит со своим eID, а RP в реальном времени проверяет его права по реестру представительства (право НЕ в сертификате — оно в реестре). 2. Подписание от имени организации = ЛИЧНЫЙ сертификат PIN2 представителя + маркер onBehalfOf в сессии (сервер уже проверил право). 3. e-Seal (печать) = автоматическая печать на серверном ключе HSM с сертификатом NTRMN- — неинтерактивная (счета, выписки и т. п. прямо из системы).

1. Идентификатор

Элемент Значение
ETSI-идентификатор NTRMN-<национальный регистрационный номер> (ETSI EN 319 412-1 §5.1.4, семантика NTR)
Subject сертификата SERIALNUMBER=<регистрационный номер>, CN/O=<название>, organizationIdentifier(2.5.4.97)=NTRMN-<номер>, C=MN
Выпускающий CA Gerege Organization Issuing CA (L2) — выбирается автоматически через SubjectTypeForEtsi

2. Регистрация организации (оператор/админ)

Вкладка Организации в консоли администратора либо API:

POST /v3/admin/organizations            (org:write)
  {"orgRegister":"1234567","name":"Тест ХХК","nameLatin":"TEST LLC","activate":false}
  • activate:false → создаётся со статусом PENDING; после проверки администратор продвигает её по FSM.
  • FSM: PENDING → VERIFIED → ACTIVE → SUSPENDED/REVOKED (из SUSPENDED можно восстановить; REVOKED — терминальный статус: активные сертификаты печати автоматически отзываются и попадают в OCSP/CRL).
PATCH /v3/admin/organizations/{etsi}    {"status":"ACTIVE"}

3. Права представительства (representation)

Каждый уполномоченный представитель обязан иметь собственный eID (быть зарегистрированным):

POST /v3/admin/organizations/{etsi}/representatives   (org:write)
  {"personEtsi":"PNOMN-…","role":"Гүйцэтгэх захирал","rightType":"ADMIN",
   "source":"MANUAL","evidenceRef":"тушаал №…","validTo":null}
DELETE /v3/admin/organizations/{etsi}/representatives/{id}
  • rightType: ADMIN (создал/привязал организацию — может добавлять и удалять подчинённых подписантов MANAGER) | MANAGER (подписант — не может никого добавлять или удалять).
  • source: REGISTRY (из УБЕГ/DAN — будущая автоматическая синхронизация) | MANUAL (подтверждено документом).
  • Если срок (validTo) истёк, право деактивировано или организация не в статусе ACTIVE, право НЕ появляется в выборках.

4. Интеграция на стороне RP

4.1 Вход как организация

  1. Выполните обычный личный вход пользователя (/v3/authentication/...).
  2. Затем: 
    GET /v3/organization/representations/etsi/{personEtsi}     (RP auth)
→ {"personEtsi":"PNOMN-…","representations":[
     {"orgEtsi":"NTRMN-…","orgName":"…","rightType":"ADMIN","role":"…", …}]}
  3. Покажите в UI выбор «от имени какой организации продолжить» и создавайте сессию в контексте выбранной организации. Права могут меняться день ото дня — проверяйте их в каждой сессии.

4.2 Подписание от имени организации

Добавьте onBehalfOf в запрос на подписание: 

POST /v3/signature/notification/etsi/{personEtsi}
  { …, "onBehalfOf":"NTRMN-1234567" }
- Сервер проверяет право представительства в момент создания сессии: без права — 403; для неидентифицированного (анонимного) пользователя — 403. - На экране подтверждения в телефоне отображается «Вы подписываете от имени X». - В статусе сессии (GET /v3/session/{id}) появляется блок onBehalfOf: {orgEtsi, orgName}; сама подпись остаётся личным сертификатом PIN2 (криптография не меняется). - И ADMIN, и MANAGER могут подписывать от имени организации самостоятельно (на уровне криптографии требования совместной подписи нет); если нужно собрать несколько подписей — это правило RP (как и в Эстонии).

4.3 e-Seal (печать организации)

RP должен обладать разрешением SEAL (в поле permissions при админской регистрации RP, AUTH,SIGN,SEAL); first-party (собственный веб) не ограничен.

POST /v3/seal/certificate/{orgEtsi}    — выпуск ключа и сертификата печати (или через админа:
                                          POST /v3/admin/organizations/{etsi}/seal-certificate)
GET  /v3/seal/certificate/{orgEtsi}    — активный сертификат (для валидации)
POST /v3/seal/{orgEtsi}                — проставление печати:
  {"digest":"<base64 SHA-256/384/512>"} → {"signature":{"value","signatureAlgorithm"},
                                            "cert":{"value","certificateLevel"},"sealedAt"}
  • Неинтерактивно и синхронно — без PIN и push (модель e-Seal от SK).
  • Если организация не в статусе ACTIVE либо сертификат отозван/заменён — 409 (fail-closed).
  • Профиль сертификата (SK-CPR-ORG): KeyUsage = только nonRepudiation; EKU отсутствует; QCStatements = QcCompliance + QcType=eseal; политика QCP-l. При SMARTID_SEAL_QSCD=true (реальный QSCD/HSM) добавляется QcSSCD, политика QCP-l-qscd, уровень QSCD.

4.4 Управление подписантами со стороны RP (самообслуживание)

Представитель с правом ADMIN может добавлять и удалять подписантов MANAGER своей организации прямо из UI RP (консоль администратора не требуется). Каждый эндпойнт требует RP auth и разрешение ORG_LINK_WRITE; {actingPersonEtsi} должен быть представителем этой организации с правом ADMIN (иначе 403). {orgRegister} = национальный регистрационный номер организации.

GET    /v3/organization/signers/{orgRegister}/etsi/{actingPersonEtsi}
       → текущие подписанты (в статусе verified/pending)
POST   /v3/organization/signers/{orgRegister}/etsi/{actingPersonEtsi}
       {"signerRegNo":"<РД добавляемого гражданина>","role":"Нягтлан бодогч"}
       — добавляемое право ВСЕГДА MANAGER (`rightType` игнорируется); гражданину отправляется
         sign-push с запросом подтверждения.
DELETE /v3/organization/signers/{orgRegister}/etsi/{actingPersonEtsi}?signer=<РД>
POST   /v3/organization/signers/{orgRegister}/etsi/{actingPersonEtsi}/resend?signer=<РД>
       — повторная отправка sign-push неподтверждённому подписанту.

Латинское название организации (ICAO/latin — то, что попадает в сертификат) может изменять только ADMIN:

PUT /v3/organization/name-latin/{orgRegister}/etsi/{actingPersonEtsi}
    {"nameLatin":"TEST LLC"}

РД (signerRegNo) — регистрационный номер, регистр не важен (поиск в нижнем регистре); nameLatin соответствует канону ICAO, поэтому хранится в верхнем регистре (Идентификаторы).

4.5 Проверка отзыва

  • OCSP: POST /ocsp — единая точка; респондер сам выбирает Personal/Organization CA по хешу издателя в запросе.
  • CRL: GET /crl (Personal CA), GET /crl/org (Organization CA).
  • Discovery: GET /.well-known/eid — перечислены эндпойнты организации и печати.

5. Конфигурация (сервер)

Env Значение
SMARTID_HSMPROXY_ORG_KEY_LABEL Метка ключа HSM для Organization issuing CA (если пусто — fallback на Personal CA)
SMARTID_HSMPROXY_ORG_ISSUING_CERT Сертификат Organization issuing CA (путь к PEM)
SMARTID_SEAL_QSCD true = листовой ключ e-Seal в HSM (QSCD; QcSSCD+QCP-l-qscd). Требует CA-провайдер hsmproxy и учётные данные (иначе fail-fast). false = программные ключи печати (QUALIFIED). Церемония: docs/PKI_CA_ONBOARDING.md
SMARTID_SEAL_KEY_PREFIX Префикс метки ключа печати в HSM (по умолчанию eseal-; метка = префикс + регистрационный код)

6. Аудит

Все действия попадают в audit_events: ORG_REGISTER, ORG_STATUS, ORG_REP_ADD/REMOVE, ORG_REP_LOOKUP (какой RP чьё право проверял), ORG_ONBEHALF (OK/DENIED), SEAL_CERT_ISSUE, ORG_SEAL (OK/DENIED).

7. Ограничения / дальнейшие шаги

  • API реестра юридических лиц УБЕГ/DAN не подключён — представительство пока заводится из источника MANUAL (по документу); после открытия API будет добавлена синхронизация REGISTRY (фаза 0/1).
  • Если в staging не настроен org CA, сертификат печати выпускается Personal CA (fallback caFor) — в продакшене Organization CA обязателен (список задач cutover в deploy/README.md).
  • Юридический статус e-Seal (аналог «электронной печати» eIDAS в законодательстве Монголии) предстоит уточнить с юристами (ORG_AUTH_SIGN_PLAN §4).