← Tài liệu

Bảo mật khi tích hợp Nextfarm

Những gì Nextfarm bảo đảm, và những gì hệ thống của bạn phải làm để dữ liệu trại an toàn.

1. Chứng từ

  • API key nfk_… và client_secret (nfs_…) chỉ hiện một lần lúc tạo. Nextfarm chỉ lưu bản băm SHA-256 — mất là tạo khoá mới, không ai lấy lại được.
  • Token ứng dụng (OAuth) sống 15 phút, không có refresh token — hết thì xin lại.
  • Giữ khoá/secret trên máy chủ của bạn (environment variable, kho secret). Không nhúng vào app di động, trang web chạy ở trình duyệt, kho mã hay log.

2. Scope tối thiểu

  • Mỗi khoá/ứng dụng chỉ làm đúng các scope được cấp; gọi ngoài scope là 403.
  • Người tạo khoá, người cài ứng dụng chỉ cấp được scope chính họ đang có — không leo quyền qua khoá.
  • Không có scope điều khiển thiết bị; khoá không vào được quản trị người dùng/quyền. Ghi chỉ ở vài tuyến (khai lô thu hoạch, thêm/sửa dòng sổ).
  • Xin đúng phần cần — trại dễ cho phép hơn, và lộ khoá thì thiệt hại nhỏ hơn.

3. Webhook có signature

  • X-Nextfarm-Signature = sha256= + hex của HMAC-SHA256(bí_mật, timestamp + "." + thân_tin). Tính trên thân tin nguyên bản, so sánh bằng hàm hằng thời gian.
  • Từ chối tin có X-Nextfarm-Timestamp lệch quá 5 phút — chống phát lại tin cũ.
  • Bỏ trùng theo X-Nextfarm-Delivery — Nextfarm có thể giao lại một tin khi retry.
  • Secret whsec_… hiện một lần lúc tạo/xoay. Mã mẫu Node.js / Python →
  • Mỗi tin còn kèm header chuẩn Standard Webhooks (webhook-id · webhook-timestamp · webhook-signature) — kiểm bằng thư viện standardwebhooks có sẵn thay vì tự viết. Cách dùng →

4. Đường truyền

  • Chỉ HTTPS. Địa chỉ nhận webhook phải là https:// tới máy chủ công khai; địa chỉ nội bộ (localhost, 10.x, 172.16–31.x, 192.168.x, 169.254.x…) bị chặn cả lúc lưu lẫn lúc gửi.
  • Webhook không theo chuyển hướng (3xx tính là hỏng) và chờ tối đa 10 giây.
  • Có giới hạn tần suất theo trại: gặp 429 thì đọc Retry-After rồi gọi lại, đừng dồn dập.

5. Xoay và thu hồi

  • API key: chủ trại thu hồi ở Hệ thống › API key — lời gọi sau đó 401 ngay.
  • Webhook: Xoay secret ở Hệ thống › Webhook — secret cũ vẫn ký kèm thêm 24 giờ (header X-Nextfarm-Signature-Previous + signature thứ hai trong webhook-signature) để bên nhận kịp đổi.
  • Ứng dụng: trại gỡ ở Hệ thống › Ứng dụng, đổi scope, hoặc NextFarm đình chỉ app — token đang có bị chặn ngay. Đối tác xoay App Secret ở Ứng dụng của tôi › App settings › App Secret: secret cũ dùng thêm 24 giờ.
  • Nghi lộ khoá/secret: thu hồi hoặc xoay trước, điều tra sau.

6. Báo lỗ hổng

  • Gửi mô tả + cách tái hiện tới [email protected], tiêu đề bắt đầu bằng [Bảo mật]. Vui lòng không công bố trước khi Nextfarm xác nhận đã vá.
  • Thử trên Developer workspace của bạn (miễn phí, có trang trại mẫu, không gửi gì ra ngoài) — không thử ghi trên trại thật của khách.
  • Câu hỏi tích hợp thông thường cũng gửi [email protected].

Danh sách kiểm trước khi lên thật

Lệnh mẫu
☐ Khoá/secret nằm trong kho secret — không trong mã nguồn, không in ra log
☐ Chỉ xin đúng scope cần
☐ Verify signature + timestamp mọi tin webhook, bỏ trùng theo X-Nextfarm-Delivery, trả 2xx trong 10 giây
☐ Lệnh ghi: gửi Idempotency-Key riêng cho mỗi bản ghi; mất phản hồi thì gửi lại CÙNG mã, không tạo mã mới
☐ Xử lý 401 (khoá thu hồi/hết hạn) · 403 (thiếu scope) · 429 (đợi Retry-After)
☐ Token ứng dụng: xin lại khi hết 15 phút, không lưu lâu
☐ Đã chạy thử trọn luồng trên trại thử của bạn