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ừ

Khoá API 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á/bí mật trên máy chủ của bạn (biến môi trường, kho bí mật). Không nhúng vào app di động, trang web chạy ở trình duyệt, kho mã hay log.

2. Phạm vi tối thiểu

Mỗi khoá/ứng dụng chỉ làm đúng các phạm vi được cấp; gọi ngoài phạm vi là 403.
Người tạo khoá, người cài ứng dụng chỉ cấp được phạm vi chính họ đang có — không leo quyền qua khoá.
Không có phạm vi đ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ó chữ ký

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 thử lại.
Bí mật whsec_… hiện một lần lúc tạo/xoay. Mã mẫu Node.js / Python →

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

Khoá API: chủ trại thu hồi ở Quản lý › Khoá API — lời gọi sau đó 401 ngay.
Webhook: Xoay bí mật ở Quản lý › Webhook — bí mật cũ hết hiệu lực.
Ứng dụng: trại gỡ ở Quản lý › Ứng dụng — không lấy được token mới; token đang có hết hạn trong tối đa 15 phút.
Nghi lộ khoá/bí mật: 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á.
Chỉ thử trên sandbox https://api-dev.nextfarm.vn — không thử trên dữ liệu trại thật.
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á/bí mật nằm trong kho bí mật — không trong mã nguồn, không in ra log
☐ Chỉ xin đúng phạm vi cần
☐ Kiểm chữ ký + timestamp mọi tin webhook, bỏ trùng theo X-Nextfarm-Delivery, trả 2xx trong 10 giây
☐ Xử lý 401 (khoá thu hồi/hết hạn) · 403 (thiếu phạm vi) · 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 sandbox https://api-dev.nextfarm.vn