gerege.mn — eID Gerege интеграц (auth · sign · push)¶

gerege.mn-ийг eID Gerege-тэй RP болгож холбон нэвтрэлт (authentication), цахим гарын үсэг (signature)-ийг App2App (same-device) болон Push (cross-device) урсгалаар авах гарын авлага. Wire protocol нь Smart-ID нийцтэй (ACSP_V2).

Ерөнхий RP заавар: RP_INTEGRATION.md. Энэ файл нь gerege.mn-ий бодит тохиргоо + copy-paste жишээ.

0. gerege.mn RP тохиргоо (бүртгэгдсэн)¶

Талбар	Утга
relyingPartyUUID	`43a7bda9-0d68-4324-9ec1-3fc6dd8e4edf`
relyingPartyName	`gerege.mn`
API secret (Bearer)	`rp_sk_…` — оператороос авна, `$GEREGE_RP_SECRET` env-д хадга (серверт зөвхөн SHA-256 hash)
RP-API base	`https://rp-api.eidmongolia.mn/v3`
Callback host allowlist	`gerege.mn`, `www.gerege.mn` (App2App буцах URL заавал эдгээрийн нэг)
App deep-link scheme	`geregesmartid://approve?sessionId=…`
Discovery	`GET https://rp-api.eidmongolia.mn/.well-known/eid`

Дуудлага бүрд: - Header: Authorization: Bearer $GEREGE_RP_SECRET - Body: relyingPartyUUID, relyingPartyName, certificateLevel (QUALIFIED), signatureProtocol (ACSP_V2)

1. Нэвтрэлт — App2App (same-device, нэг утсан дээр браузер + апп)¶

Хэрэглэгч gerege.mn-д утсаараа орж байгаа үед: session үүсгэ → аппыг deep-link-ээр нээ → хэрэглэгч PIN-ээр баталгаажуул → апп callback руу буцаана → session-ий үр дүнг poll хий.

1.1 Session эхлүүлэх (`initialCallbackUrl`-тэй)¶

curl -sS -X POST https://rp-api.eidmongolia.mn/v3/authentication/device-link/anonymous \
  -H "Authorization: Bearer $GEREGE_RP_SECRET" -H "Content-Type: application/json" \
  -d '{
    "relyingPartyUUID": "43a7bda9-0d68-4324-9ec1-3fc6dd8e4edf",
    "relyingPartyName": "gerege.mn",
    "certificateLevel": "QUALIFIED",
    "signatureProtocol": "ACSP_V2",
    "initialCallbackUrl": "https://gerege.mn/auth/eid/callback?state=<csrf>",
    "interactions": [{"type":"displayTextAndPIN","displayText60":"gerege.mn нэвтрэх"}]
  }'

Хариу:

{ "sessionID": "…", "sessionToken": "…", "sessionSecret": "…",
  "deviceLinkBase": "https://eidmongolia.mn/dl", "vc": "2025" }

⚠️ initialCallbackUrl-ийн host нь allowlist-д (gerege.mn/www.gerege.mn) байх ёстой — эс бөгөөс сервер түүнийг чимээгүй хасна (open-redirect/phishing хамгаалалт). Сервер зөвхөн host + query-г хадгалж, path-ыг /auth/eid/callback болгон force-normalize хийдэг тул RP буцах хуудсаа энэ замд байршуулна. vc (4 оронтой код)-ийг gerege.mn дэлгэцэнд харуулж, хэрэглэгч утсан дээрхтэй тулгаж болно.

1.2 Аппыг нээх (deep-link)¶

Хариунд ирсэн sessionID-аар браузераас аппыг нээнэ:

geregesmartid://approve?sessionId=<sessionID>

Апп нээгдэж, хэрэглэгч PIN1 (нэвтрэх түлхүүр)-ээр баталгаажуулна. Дараа нь апп таны initialCallbackUrl руу буцаана.

1.3 Үр дүнг poll хийх → [§4]¶

2. Нэвтрэлт — Push (cross-device: хэрэглэгч өөр төхөөрөмж/компьютер дээр)¶

Хэрэглэгчийг РД/иргэний дугаар/document-ээр нь мэдэж байвал утас руу нь push илгээнэ.

# ETSI (PNOMN-<civilId>) эсвэл шууд регистр/иргэний дугаараар push (сервер төрлийг таньна)
curl -sS -X POST https://rp-api.eidmongolia.mn/v3/authentication/notification/etsi/PNOMN-<civilId> \
  -H "Authorization: Bearer $GEREGE_RP_SECRET" -H "Content-Type: application/json" \
  -d '{
    "relyingPartyUUID": "43a7bda9-0d68-4324-9ec1-3fc6dd8e4edf",
    "relyingPartyName": "gerege.mn",
    "certificateLevel": "QUALIFIED",
    "signatureProtocol": "ACSP_V2",
    "interactions": [{"type":"displayTextAndPIN","displayText60":"gerege.mn нэвтрэх"}]
  }'
# → { "sessionID": "…", "vc": { "type":"alphaNumeric4", "value":"2422" } }

vc.value-г gerege.mn дэлгэцэнд харуул — хэрэглэгч утсандаа ирсэн push-ийн кодтой тулгаж баталгаажуулна. document/{documentNumber} (төхөөрөмжийн UUID)-аар ч push илгээж болно.

3. Цахим гарын үсэг (Signature) — PIN2, non-repudiation¶

Баримтын SHA-256 digest (base64)-ийг утас руу PIN2 (гарын үсгийн түлхүүр)-ээр зуруулна. Утас нь signed digest-ээс VC-г тооцдог тул хэрэглэгчийн харж буй код = гарын үсэг зурагдах агуулга (WYSIWYS).

3.1 Push-аар (cross-device)¶

DIGEST=$(sha256sum document.pdf | cut -d' ' -f1 | xxd -r -p | base64)
curl -sS -X POST https://rp-api.eidmongolia.mn/v3/signature/notification/document/<documentNumber> \
  -H "Authorization: Bearer $GEREGE_RP_SECRET" -H "Content-Type: application/json" \
  -d "{
    \"relyingPartyUUID\": \"43a7bda9-0d68-4324-9ec1-3fc6dd8e4edf\",
    \"relyingPartyName\": \"gerege.mn\",
    \"certificateLevel\": \"QUALIFIED\", \"signatureProtocol\": \"ACSP_V2\",
    \"digest\": \"$DIGEST\", \"hashType\": \"SHA256\",
    \"interactions\": [{\"type\":\"displayTextAndPIN\",\"displayText60\":\"gerege.mn гарын үсэг\"}]
  }"
# ETSI-ээр: /signature/notification/etsi/PNOMN-<civilId>

3.2 App2App-аар (same-device)¶

POST /v3/signature/device-link/document/{documentNumber} — body-д digest, hashType, initialCallbackUrl (gerege.mn), дараа нь geregesmartid://approve?sessionId=…-аар аппыг нээнэ.

3.3 Дууссаны дараа — PAdES PDF (сонголт)¶

Poll endResult=OK болмогц эх PDF-ийг stamp хийж, баталгаажуулалтын хуудас + RFC 3161 timestamp (PAdES-T) шингээсэн PDF татаж авна:

curl -sS -X POST "https://rp-api.eidmongolia.mn/v3/signature/stamp/<sessionID>?fileName=document.pdf" \
  -H "Authorization: Bearer $GEREGE_RP_SECRET" --data-binary @document.pdf -o signed.pdf

Verify: https://eidmongolia.mn/verify/<sessionID> (нийтийн; QR-д мөн).

4. Session-ий үр дүнг poll хийх (long-poll)¶

curl -sS "https://rp-api.eidmongolia.mn/v3/session/<sessionID>?timeoutMs=120000" \
  -H "Authorization: Bearer $GEREGE_RP_SECRET"

- state=RUNNING — үргэлжилж байна (дахин poll) - state=COMPLETE + result.endResult=OK → - signature.value — detached ECDSA гарын үсэг (signature.signatureAlgorithm=ecdsa-with-SHA256) - cert.value — иргэний X.509 (auth эсвэл sign), cert.certificateLevel - state=COMPLETE + бусад result.endResult (USER_REFUSED, TIMEOUT, WRONG_VC…) → татгалзсан

Auth баталгаажуулалт (gerege.mn тал): буцсан cert-ийг eID Gerege root CA-д гинжилж (OCSP: discovery doc-ийн endpoints.ocsp), rpChallenge (илгээсэн бол) гарын үсэгт багтсаныг шалгана.

5. Аюулгүй байдлын шаардлага (gerege.mn тал)¶

initialCallbackUrl заавал https:// + allowlist host (gerege.mn/www.gerege.mn). Бусад host чимээгүй хасагдана.
state (CSRF) параметрийг callback URL-д оруулж, буцахад тулгана.
API secret-ийг backend-д л хадга (browser-т ил гаргахгүй). RP-API дуудлага сервер-серверийн.
VC кодыг хэрэглэгчид харуулж, утасныхтай тулгуулах нь fisher-in-the-middle-ээс сэргийлнэ.
Poll-ийн session TTL 10 мин (SMARTID_SESSION_TTL_SECONDS).

6. Урсгалын товч диаграм (App2App нэвтрэлт)¶

gerege.mn (browser)         eID Gerege RP-API              eID Gerege app (утас)
  │  POST device-link/anonymous  │                                │
  │  (+ initialCallbackUrl)  ───▶ │  session үүсгэ (callback     │
  │  ◀── sessionID, vc            │  allowlist-аар шалга)         │
  │  geregesmartid://approve?sessionId=… ───────────────────────▶ │  апп нээгдэнэ
  │                               │                                │  PIN1 → threshold auth
  │                               │  ◀──── commit/prove/finish ─── │
  │  ◀───────── callback: https://gerege.mn/auth/eid/callback?state=… ── │  (буцна)
  │  GET session/{id} (poll) ───▶ │                                │
  │  ◀── COMPLETE, endResult=OK, cert ─│                          │

Жишээ ажиллаж буй клиент: web/src/lib/rpclient.ts (TypeScript), эсвэл sdk/typescript/ SDK.