REST API FortiGate — Hướng đi tự động hóa

1. Liên hệ thực tế

Đây là bài cuối cùng của Nhóm 5. Nhìn lại cả chặng đường từ HA, FortiSwitch/FortiAP, FortiManager, FortiAnalyzer, đến Fabric Connector và Automation Stitch, chị Lan tổng kết với anh Nam: "Tất cả những gì em vừa học đều có thể thao tác qua GUI hoặc CLI. Nhưng nếu khách hàng muốn tự động hóa sâu hơn nữa — ví dụ hệ thống ticketing nội bộ của họ tự động tạo Firewall Policy mới mỗi khi có yêu cầu mở port được duyệt — thì cần một cách để phần mềm khác gọi thẳng vào FortiGate, không qua con người click chuột hay gõ lệnh."

Đó chính là REST API — giao diện lập trình cho phép các hệ thống bên ngoài (script tự động hóa, công cụ CI/CD, nền tảng SOAR...) tương tác trực tiếp với cấu hình và dữ liệu giám sát của FortiGate. Bài này giới thiệu cách tạo REST API admin và gọi thử một request cơ bản.

2. Kiến thức cốt lõi

2.1 REST API trên FortiGate là gì

FortiOS REST API cho phép truy vấn và thay đổi cấu hình FortiGate thông qua các request HTTP chuẩn (GET, POST, PUT, DELETE) tới các endpoint tương ứng với từng phần cấu hình — gần như toàn bộ những gì có thể làm qua CLI (config, get, show) đều có endpoint API tương ứng. Đây là nền tảng cho các tài khoản tự động hóa: cấu hình theo lịch, sao lưu tự động, hay giám sát trạng thái từ hệ thống bên ngoài.

2.2 Xác thực bằng Token — phương thức được khuyến nghị

FortiOS REST API dùng xác thực dựa trên token (API token) làm phương thức ưu tiên. Quy trình tạo REST API admin gồm 2 bước:

Bước 1 — Tạo Administrator Profile với quyền hạn phù hợp (áp dụng nguyên tắc least-privilege đã học ở Nhóm 1, không nên cấp super_admin cho tài khoản API trừ khi thực sự cần):

config system accprofile
    edit "api-readonly"
        set scope global
        set secfabgrp read
        set sysgrp read
        set netgrp read
        set fwgrp read
        set loggrp read
    next
end

Bước 2 — Tạo REST API Admin gắn với profile đó, giới hạn thêm bằng Trusted Host để chỉ cho phép gọi API từ dải IP tin cậy:

config system api-user
    edit "api-monitor"
        set comments "Tai khoan API chi doc, dung cho he thong giam sat noi bo"
        set accprofile "api-readonly"
        set vdom "root"
        config trusthost
            edit 1
                set ipv4-trusthost 10.10.20.0 255.255.255.0
            next
        end
    next
end

Sau khi tạo qua GUI (System > Administrators > Create New > REST API Admin), FortiGate sẽ hiển thị API token đúng một lần duy nhất ngay tại thời điểm tạo — cần lưu lại ngay vào nơi lưu trữ bí mật an toàn (ví dụ Vault nội bộ), vì không thể xem lại token này sau đó.

⚠️ Lưu ý: Nguyên tắc least-privilege đặc biệt quan trọng với tài khoản API — vì token một khi bị lộ (ví dụ commit nhầm vào source code) có thể bị lợi dụng gọi API tự động, quy mô lớn hơn nhiều so với một phiên đăng nhập GUI thông thường bị lộ mật khẩu. Luôn kết hợp: profile quyền hạn tối thiểu cần thiết + giới hạn Trusted Host chặt chẽ.

2.3 Gọi thử một request cơ bản

Sau khi có token, gọi API bằng cách đính token vào header Authorization. Ví dụ dùng curl lấy trạng thái hệ thống:

curl -k -H "Authorization: Bearer <API_TOKEN>" \
     "https://10.10.20.1/api/v2/monitor/system/status"

Ví dụ tạo mới một Address Object qua API (tương đương thao tác config firewall address trên CLI):

curl -k -X POST \
     -H "Authorization: Bearer <API_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"name":"api-created-host","subnet":"192.168.50.10 255.255.255.255"}' \
     "https://10.10.20.1/api/v2/cmdb/firewall/address"

Cấu trúc endpoint chia làm 2 nhóm chính: /api/v2/cmdb/... dùng để đọc/ghi cấu hình (tương đương lệnh config), và /api/v2/monitor/... dùng để truy vấn trạng thái/dữ liệu giám sát thời gian thực (tương đương lệnh get/diagnose) — không dùng để thay đổi cấu hình.

🔄 Khác biệt version FortiOS: Tham số peer-auth/peer-group (xác thực bổ sung bằng certificate phía client) trong config system api-user chỉ xuất hiện từ FortiOS 7.4 trở lên. Trên FortiOS 7.0, việc bảo vệ tài khoản API chủ yếu dựa vào token + Trusted Host như trình bày ở trên, chưa có lớp xác thực certificate bổ sung này.

2.4 Vì sao không nên dùng tài khoản admin GUI thông thường cho tích hợp API

Một số đội kỹ thuật mới làm quen thường tiện tay dùng chung tài khoản admin GUI (kèm mật khẩu) cho cả việc gọi API tự động hóa. Đây không phải thực hành khuyến nghị: tài khoản REST API Admin (config system api-user) được thiết kế riêng cho mục đích tự động hóa, tách bạch rõ với tài khoản đăng nhập GUI của con người, giúp dễ dàng thu hồi/xoay vòng (rotate) token riêng lẻ mà không ảnh hưởng tới quyền truy cập GUI của quản trị viên thật, đồng thời dễ truy vết log hành động nào đến từ hệ thống tự động, hành động nào do con người thao tác trực tiếp.

3. Hỏi & Đáp

API token có thời hạn sử dụng không, hay dùng mãi mãi cho tới khi bị xóa thủ công?

Về mặc định, API token gắn với tài khoản api-user sẽ có hiệu lực cho tới khi quản trị viên chủ động xóa hoặc tạo lại tài khoản đó. Với môi trường yêu cầu bảo mật cao, nên có quy trình định kỳ xoay vòng (rotate) token theo chính sách nội bộ, tương tự cách quản lý mật khẩu tài khoản admin thông thường.

Nhóm endpoint /api/v2/monitor/ có thể dùng để thay đổi cấu hình được không?

Không nên và về thiết kế không phải mục đích chính của nhóm này — /api/v2/monitor/ dành cho việc truy vấn trạng thái/dữ liệu thời gian thực (tương đương get/diagnose trên CLI). Muốn thay đổi cấu hình (tương đương config), phải dùng nhóm endpoint /api/v2/cmdb/.

Có bắt buộc phải giới hạn Trusted Host cho tài khoản REST API không?

Không bắt buộc về mặt kỹ thuật (FortiGate vẫn cho tạo tài khoản API không giới hạn Trusted Host), nhưng đây là khuyến nghị bảo mật quan trọng nên tuân thủ — nếu không giới hạn, bất kỳ ai có được token đều có thể gọi API từ bất kỳ đâu trên Internet (nếu giao diện quản trị có public), thay vì chỉ giới hạn trong dải IP nội bộ tin cậy của hệ thống tự động hóa.

4. Quiz

Câu 1: Phương thức xác thực nào được FortiOS REST API khuyến nghị sử dụng?

• A. Mật khẩu GUI thông thường
• B. Token-based authentication
• C. RADIUS
• D. Không cần xác thực

Câu 2: Endpoint dạng /api/v2/cmdb/firewall/address tương ứng với loại thao tác nào trên CLI?

• A. get/diagnose
• B. execute reboot
• C. config
• D. diagnose debug

Câu 3: Vì sao nên tạo riêng tài khoản api-user thay vì dùng chung tài khoản admin GUI cho tích hợp tự động hóa?

• A. Vì tài khoản admin GUI không hỗ trợ đăng nhập
• B. Vì tách bạch giúp dễ thu hồi/xoay vòng quyền truy cập và truy vết log riêng biệt
• C. Vì tài khoản admin GUI không có quyền cấu hình firewall address
• D. Vì REST API chỉ hoạt động với tài khoản có tên bắt đầu bằng "api"

👉 Đáp án

Câu 1: B FortiOS REST API dùng xác thực dựa trên token (token-based authentication) làm phương thức được khuyến nghị, thay vì dùng trực tiếp mật khẩu tài khoản GUI thông thường.

Câu 2: C Nhóm endpoint /api/v2/cmdb/... dùng để đọc và ghi cấu hình, tương đương với việc sử dụng lệnh config trên CLI — trong khi /api/v2/monitor/... mới tương ứng với get/diagnose.

Câu 3: B Tách riêng tài khoản REST API Admin giúp dễ dàng thu hồi hoặc xoay vòng token mà không ảnh hưởng quyền truy cập GUI của quản trị viên thật, đồng thời giúp truy vết rõ ràng hành động nào đến từ hệ thống tự động, hành động nào do con người thao tác.

📚 Bài viết thuộc khóa học FortiGate của VNExperts

🧭 Điều hướng