Аюулгүй байдал ба key эргэлт

gov-pay channel-api-д хандах гол credential нь таны партнёрийн X-API-Key. Энэ key алдагдвал таны нэрийн өмнөөс нэхэмжлэл унших, төлбөр илгээх боломжтой болно. Тиймээс доорх дүрмийг чанд баримтлана уу.

X-API-Key зөвхөн server талд

X-API-Key-г зөвхөн өөрийн сервер дотроос ашиглана. Хэзээ ч browser болон мобайл апп-аас шууд gov-pay руу дуудалт хийхдээ key-ийг оруулж болохгүй.

Зөв бүтэц:

[Мобайл / Web client]
        │  (таны өөрийн auth: session/JWT)
        ▼
[Таны backend]  ──  X-API-Key  ──▶  gov-pay channel-api

• Key-г сервер талын орчны хувьсагч (environment variable) эсвэл secrets manager-т хадгал. Source code дотор hardcode хийхгүй.
• Client (апп/browser)-ээс зөвхөн таны өөрийн backend руу хандана. Таны backend дотроос л gov-pay руу X-API-Key-тэй проксидоно.

Орчин тус бүрд (Sandbox / Production) key өөр байна. Орчны талаар Орчин хуудаснаас үзнэ үү.

Key-г лог-д бичихгүй

X-API-Key, webhook secret, болон бусад нууц утгыг application log, request log, error tracking (Sentry гэх мэт), APM trace-д бичихгүй.

• HTTP request/response logging идэвхтэй бол header-ийн X-API-Key-г маск хийх (жишээ нь ***) эсвэл бүрэн хасах тохиргоо хий.
• Алдаа log хийхдээ бүтэн request-ийг хэвлэхээс зайлсхий. Зөвхөн шаардлагатай талбарыг үлдээ.
• Screenshot, дэмжлэгийн тикет, чат-д key-ийг хуулж буулгахгүй.

HTTPS заавал

Бүх дуудалт зөвхөн HTTPS-ээр явна. gov-pay-ийн Sandbox болон Production base URL-ууд https:// эхэлдэг.

• Local dev (http://localhost:5600/api/v1)-ийг зөвхөн өөрийн машин дээр хөгжүүлэлтэд ашиглана. Дотоод сүлжээнд ч plain HTTP-ээр key дамжуулахгүй.
• TLS certificate шалгалтыг (certificate verification) идэвхгүй болгож болохгүй. verify=false маягийн тохиргоо нь key-г man-in-the-middle халдлагад нээж өгнө.

Base URL-ууд бүгд /api/v1 угтвартай. Дэлгэрэнгүйг Орчин хуудаснаас үзнэ үү.

X-API-Key эргэлт (rotation)

Key-г тогтмол хугацаанд эргэлтэд оруулах, мөн алдагдсан гэж сэжиглэвэл шууд солих нь зүйтэй. gov-pay key-г өөрөө self-service-ээр шинэчлэх боломжгүй тул процесс нь gov-pay-тэй холбогдохыг шаардана.

Эргэлтийн зөвлөмж дараалал (downtime-гүй):

1. gov-pay-тэй холбогдож шинэ key захиалах. Хуучин key түр зэрэгцэн идэвхтэй байх хугацаа (overlap) тохиролц.
2. Шинэ key-г secrets manager / env-д байршуул. Кодоо эсвэл config-оо шинэ key руу шилжүүл.
3. Шинэ key-ээр шалга. GET /reports/summary зэрэг энгийн endpoint дуудаж 200 хариу авч баталгаажуул.
4. Бүх трафикийг шинэ key руу шилжүүлснийг баталгаажуул. Хуучин key-ийн ашиглалт зогссоныг log-оор нягтал.
5. gov-pay-аар хуучин key-г идэвхгүй болгуул. Үүний дараа хуучин key-ээр дуудвал 401 (буруу key) буцна.

Алдагдсан гэж сэжиглэвэл overlap-гүйгээр хуучин key-г шууд идэвхгүй болгуулах нь дээр — энэ үед богино зуурын downtime-ийг хүлээн зөвшөөрнө.

Гэрчилгээний алдаатай холбоотой хариуны кодуудыг Алдааны кодууд хуудаснаас үзнэ үү:

• 401 — key байхгүй эсвэл буруу (идэвхгүй болсон хуучин key мөн адил).
• 403 — партнёр идэвхгүй.

Webhook secret-ийг эргэлтэд оруулах

Webhook бүртгэхдээ secret өгдөг бөгөөд gov-pay энэ secret-ээр хүргэлт бүрийн биеийг HMAC-SHA256-аар гарын үсэглэж X-GovPay-Signature header-т илгээдэг. Энэ secret-ийг мөн адил нууцлан хадгалж, эргэлтэд оруулна.

• Secret-г зөвхөн бүртгэх үед буцаадаг. GET /webhooks нь secret буцаахгүй (зөвхөн id, url, events, active, createdAt). Тиймээс secret-г бүртгэх үед нь аюулгүй хадгалж ав.
• Secret-г server талд хадгалж, зөвхөн ирсэн webhook-ийн гарын үсэг шалгахад ашиглана. Хаана ч log хийхгүй.

Webhook secret эргэлтийн дараалал:

1. Шинэ secret-тэй webhook бүртгэ — POST /webhooks body-д url, шинэ secret, events[] өгнө. Энэ нь шинэ webhook үүсгэнэ.
2. Хүлээн авагч талдаа хоёр secret-ийг хоёуланг нь зэрэг хүлээн зөвшөөр — шилжилтийн хугацаанд ирсэн event-ийн гарын үсгийг хуучин эсвэл шинэ secret аль алинаар нь шалгаж, аль нэг нь таарвал хүчинтэйд тоол.
3. Хуучин webhook-г устга — DELETE /webhooks/{id} (soft delete, { ok: true }). Үүний дараа зөвхөн шинэ secret-ийн гарын үсэгтэй event ирнэ.
4. Хүлээн авагчдаа зөвхөн шинэ secret-ийг үлдээ.

Webhook-ийн ерөнхий зарчмыг Webhook хуудаснаас үзнэ үү.

Хураангуй