Khóa API
Cách tạo, quản lý và sử dụng khóa API để truy cập lập trình vào REST API của VergeOS, bao gồm xác thực, kiểm soát truy cập IP, cài đặt hết hạn và các thực hành bảo mật tốt nhất.
Tổng quan
Các khóa API cung cấp xác thực cho truy cập theo chương trình tới VergeOS REST API và các dịch vụ tích hợp. Mỗi khóa API được gắn với một tài khoản người dùng cụ thể và kế thừa quyền hạn cũng như cấp độ truy cập của người dùng đó. Điều này cho phép các ứng dụng, script và công cụ bên thứ ba tương tác với VergeOS mà không cần các phiên đăng nhập tương tác.
Các mục đích sử dụng phổ biến của khóa API:
Xác thực REST API cho tự động hóa và tích hợp
Truy cập bộ định tuyến AI tương thích OpenAI
Tích hợp công cụ bên thứ ba (giám sát, điều phối, công cụ IaC)
Xác thực pipeline CI/CD
Hiểu về xác thực khóa API
Trong VergeOS, khóa API hoạt động như các Bearer token trong tiêu đề HTTP Authorization. Không giống như token phiên được tạo trong quá trình đăng nhập giao diện người dùng (vốn hết hạn sau khi không hoạt động), khóa API vẫn hợp lệ cho đến ngày hết hạn được cấu hình hoặc khi bị xóa thủ công.
Mỗi khóa API kế thừa tất cả quyền hạn từ tài khoản người dùng được liên kết. Một khóa API được tạo cho người dùng Tenant Admin sẽ có đặc quyền Tenant Admin, trong khi khóa cho System Admin sẽ có quyền truy cập trên toàn hệ thống.
Tạo khóa API
Đi tới Quản lý khóa API
Từ menu chính VergeOS, điều hướng đến Hệ thống > Người dùng
Chọn tài khoản người dùng sẽ sở hữu khóa API
Trong bảng điều khiển người dùng, nhấp vào Khóa API tiện ích để xem các khóa hiện có
Phần Khóa API hiển thị một bảng với:
Tên: Mã định danh mô tả cho từng khóa
Lần đăng nhập gần nhất: Dấu thời gian xác thực gần đây nhất
IP đăng nhập gần nhất: Địa chỉ IP nguồn của lần xác thực gần nhất
Hết hạn: Số ngày còn lại cho đến khi hết hạn
Đã tạo: Dấu thời gian tạo khóa
Tạo khóa API mới
Nhấp vào + Khóa API mới ở cuối bảng Khóa API
Biểu mẫu mở ra với hai bảng: Khóa API (bên trái) và Truy cập (bên phải)
Cấu hình cài đặt khóa API
Tên (Bắt buộc) Nhập mã định danh mô tả cho khóa API. Đặt tên rõ ràng giúp theo dõi và quản lý khóa.
Mô tả (Tùy chọn) Thêm ngữ cảnh bổ sung về mục đích của khóa, người yêu cầu hoặc các hệ thống liên quan.
Loại hết hạn Chọn cách quản lý thời hạn hiệu lực của khóa:
Đặt ngày: Xác định ngày hết hạn cụ thể (khuyến nghị vì lý do bảo mật)
Không bao giờ hết hạn: Tạo khóa vĩnh viễn (hãy thận trọng)
Hết hạn (Khi chọn "Đặt ngày") Sử dụng bộ chọn ngày/giờ để đặt thời điểm khóa sẽ hết hạn. Các thời hạn hết hạn phổ biến là 30, 60 hoặc 90 ngày.
Cấu hình kiểm soát truy cập
Danh sách IP cho phép Hạn chế khóa API chỉ cho các địa chỉ IP hoặc dải CIDR cụ thể. Chỉ các địa chỉ được liệt kê mới có thể xác thực bằng khóa này.
Nhấp vào + (dấu cộng) biểu tượng để thêm một mục
Nhập địa chỉ IP (ví dụ,
192.168.1.100) hoặc dải CIDR (ví dụ,192.168.1.0/24)Chọn hộp kiểm để bật mục này
Thêm các mục bổ sung khi cần
Danh sách IP từ chối Chặn các địa chỉ IP hoặc dải cụ thể khỏi việc sử dụng khóa này trong khi vẫn cho phép tất cả các địa chỉ khác.
Nhấp vào + (dấu cộng) biểu tượng để thêm một mục
Nhập địa chỉ IP hoặc dải CIDR cần chặn
Chọn hộp kiểm để bật mục này
Lưu và truy xuất khóa API
Xem lại tất cả cài đặt để đảm bảo chính xác
Nhấp vào Gửi để tạo khóa API
Một cửa sổ bật lên hiển thị khóa API đã tạo với hai tùy chọn:
Sao chép: Nhấp để sao chép toàn bộ chuỗi khóa vào bộ nhớ tạm
Lưu: Nhấp để tải khóa xuống dưới dạng một
.PAKtệp (Khóa API được bảo vệ)
Chỉ hiển thị một lần
Khóa API đầy đủ chỉ được hiển thị tại thời điểm tạo. Sau khi bạn đóng cửa sổ bật lên này, không thể truy xuất lại khóa đầy đủ. Nếu bạn mất khóa, bạn phải xóa nó và tạo khóa mới.
Sau khi lưu trữ an toàn khóa, hãy đóng cửa sổ bật lên. Khóa API mới sẽ xuất hiện trong bảng Khóa API.
Quản lý các khóa API hiện có
Chỉnh sửa khóa API
Trong bảng Khóa API, xác định vị trí khóa bạn muốn sửa đổi
Nhấp vào Chỉnh sửa biểu tượng (bút chì) bên cạnh tên khóa
Cập nhật cài đặt (tên, mô tả, hết hạn, danh sách IP)
Nhấp vào Gửi để lưu các thay đổi
Xóa khóa API
Trong bảng Khóa API, xác định vị trí khóa bạn muốn xóa
Nhấp vào Xóa biểu tượng (thùng rác) bên cạnh tên khóa
Xác nhận việc xóa
Thu hồi ngay lập tức
Xóa khóa API sẽ ngay lập tức thu hồi toàn bộ quyền truy cập. Bất kỳ ứng dụng hoặc script nào đang sử dụng khóa đã xóa sẽ không thể xác thực.
Sử dụng khóa API
Định dạng xác thực
Khóa API được dùng trong tiêu đề HTTP Authorization dưới dạng Bearer token:
Yêu cầu API mẫu
Lưu trữ biến môi trường
Vì lý do bảo mật, hãy tải khóa API từ biến môi trường thay vì viết cứng chúng:
Các cân nhắc về bảo mật
Hãy xem khóa API như mật khẩu Khóa API cung cấp xác thực đầy đủ với tư cách người dùng được liên kết. Hãy bảo vệ chúng cẩn thận như mật khẩu.
Sử dụng hạn chế IP Cấu hình Danh sách IP cho phép bất cứ khi nào có thể để giới hạn nơi khóa có thể được sử dụng. Điều này làm giảm đáng kể rủi ro nếu một khóa bị lộ.
Đặt ngày hết hạn Tránh dùng khóa vĩnh viễn khi có thể. Việc hết hạn định kỳ buộc phải xoay vòng khóa và giới hạn khoảng thời gian phơi nhiễm.
Theo dõi việc sử dụng khóa Thường xuyên xem lại các trường "Lần đăng nhập gần nhất" và "IP đăng nhập gần nhất" để phát hiện các mẫu truy cập bất thường.
Xóa các khóa không dùng Xóa các khóa API không còn cần thiết để giảm thiểu bề mặt tấn công của bạn.
Khắc phục sự cố
Xác thực khóa API thất bại
Xác minh rằng khóa được đưa vào đúng cách trong tiêu đề Authorization dưới dạng Bearer token. Kiểm tra xem có khoảng trắng thừa hoặc bị cắt ngắn không.
Bị từ chối truy cập từ khóa hợp lệ
Kiểm tra các danh sách IP cho phép/từ chối. IP nguồn của bạn có thể không được phép, hoặc có thể nằm trong danh sách từ chối.
Khóa đã hết hạn
Kiểm tra cột "Hết hạn" trong bảng Khóa API. Tạo khóa mới nếu khóa cũ đã hết hạn.
Không thể truy xuất khóa bị mất
Không thể khôi phục khóa API sau khi cửa sổ bật lên tạo ban đầu đã bị đóng. Hãy xóa khóa bị mất và tạo khóa mới.
Tài nguyên liên quan
Tài liệu VergeOS REST API - Tài liệu tham khảo API và các endpoint đầy đủ
Cập nhật lần cuối
Nội dung này có hữu ích không?