Các phương pháp quản lý khóa API cho sản phẩm AI (Danh sách kiểm tra 2026)
Quản lý khóa API hiệu quả xoay quanh năm việc: giữ khóa ở phía máy chủ và ngoài mã nguồn, cấp khóa riêng với phạm vi quyền hẹp cho từng môi trường và khối lượng công việc, lưu khóa trong trình quản lý bí mật, luân chuyển và thu hồi theo lịch trình đã được kiểm thử, đồng thời giám sát việc sử dụng mà không bao giờ ghi chính khóa đó vào nhật ký. Với sản phẩm AI, rủi ro cao hơn phần lớn các API khác, vì khóa truy cập mô hình bị lộ có thể làm phát sinh hóa đơn lớn chỉ trong vài giờ, đồng thời cho phép truy cập câu lệnh, tệp và các lệnh gọi công cụ.
Hướng dẫn này chuyển những nguyên tắc đó thành danh sách kiểm tra mà các nhóm nền tảng, bảo mật và sản phẩm AI có thể áp dụng. Nội dung bao gồm vòng đời khóa, mẫu danh mục khóa, luân chuyển không gián đoạn, các biện pháp bảo vệ CI/CD, quy trình ứng phó sự cố và mã để tạo, lưu trữ, xác minh khóa. Các nguồn tham khảo gồm Tài liệu tra cứu nhanh về quản lý bí mật của OWASP, các phương pháp sử dụng khóa API của Google Cloud và tài liệu quét bí mật của GitHub, tất cả đều được kiểm tra vào ngày 27 tháng 10 năm 2026.
Các phương pháp quản lý khóa API: danh sách kiểm tra nhanh
| # | Phương pháp | Rủi ro được ngăn chặn |
|---|---|---|
| 1 | Không bao giờ ghi cứng khóa trong mã nguồn, notebook hoặc ứng dụng phía máy khách | Rò rỉ qua lịch sử Git, gói mã trình duyệt và tệp nhị phân ứng dụng di động |
| 2 | Giữ khóa của nhà cung cấp ở phía máy chủ; cấp cho máy khách token phiên ngắn hạn | Người dùng hoặc phần mềm độc hại trích xuất khóa từ thiết bị |
| 3 | Dùng khóa riêng cho từng môi trường, ứng dụng và thành viên nhóm | Một lần rò rỉ khiến mọi hệ thống ngừng hoạt động khi thu hồi khóa |
| 4 | Áp dụng các giới hạn hẹp nhất có thể: API, mô hình, IP, hạn ngạch | Khóa bị đánh cắp có thể dùng cho mọi mục đích |
| 5 | Lưu khóa trong trình quản lý bí mật, không lưu trong phiếu yêu cầu, trò chuyện hay wiki | Các bản sao không thể tìm thấy hoặc luân chuyển |
| 6 | Duy trì danh mục khóa ghi rõ người phụ trách, khối lượng công việc và ngày luân chuyển | Luân chuyển làm gián đoạn những hệ thống dùng khóa mà nhóm không biết đến |
| 7 | Luân chuyển theo lịch với khoảng thời gian hai khóa cùng có hiệu lực, sau đó thu hồi khóa cũ | Khóa tồn tại lâu dài, vẫn còn hiệu lực sau khi nhân viên hoặc nhà cung cấp rời đi |
| 8 | Xóa các khóa không còn sử dụng | Khóa bị bỏ quên nhưng vẫn còn quyền truy cập |
| 9 | Bật quét bí mật và bảo vệ khi đẩy mã | Khóa lọt vào kho mã công khai hoặc dùng chung |
| 10 | Không bao giờ ghi khóa hoặc tiêu đề ủy quyền vào nhật ký; ghi ID hoặc phiên bản khóa | Bí mật rò rỉ qua nhật ký, dữ liệu truy vết và báo cáo lỗi |
| 11 | Đặt giới hạn chi tiêu và cảnh báo khi có hoạt động sử dụng bất thường | Hóa đơn bất ngờ do khóa bị đánh cắp hoặc bị sử dụng mất kiểm soát |
| 12 | Có quy trình ứng phó sự cố ưu tiên thu hồi khóa | Khóa bị lộ kéo dài trong lúc các nhóm tranh luận xem đã có ai khai thác hay chưa |
Phần còn lại của hướng dẫn giải thích cách triển khai từng phương pháp cho khối lượng công việc AI, nơi khóa không chỉ dùng để xác thực mà còn cấp quyền cho luồng dữ liệu chứa câu lệnh, tài liệu và đầu ra của mô hình.
Vòng đời khóa API
OWASP khuyến nghị quản lý bí mật trong toàn bộ vòng đời: tạo, luân chuyển, thu hồi và hết hạn, kèm kiểm toán ở từng bước (Tài liệu tra cứu nhanh về quản lý bí mật của OWASP). Với khóa API cho AI, vòng đời đó như sau:
| Giai đoạn | Việc người phụ trách cần làm | Bằng chứng cần lưu |
|---|---|---|
| Yêu cầu | Nêu rõ lý do cần khối lượng công việc, môi trường và các mô hình | Phiếu yêu cầu hoặc mục trong danh mục |
| Tạo | Tạo trong bảng điều khiển hoặc API của nhà cung cấp với tên mô tả rõ ràng | ID khóa, thời điểm tạo, người tạo |
| Giới hạn | Giới hạn mô hình, API, mạng và ngân sách | Cấu hình giới hạn |
| Lưu trữ | Lưu thẳng vào trình quản lý bí mật; không bao giờ dán ở nơi khác | Đường dẫn bí mật và chính sách truy cập |
| Cấp phát | Truyền vào lúc chạy cho đúng khối lượng công việc cần dùng | Liên kết cấp bí mật trong cấu hình triển khai |
| Giám sát | Theo dõi yêu cầu, token, chi tiêu và thời điểm sử dụng gần nhất | Bảng theo dõi sử dụng và cảnh báo |
| Luân chuyển | Tạo khóa thay thế, chuyển sang khóa mới, xác minh | Bản ghi luân chuyển |
| Thu hồi | Vô hiệu hóa tại nhà cung cấp, xác nhận mã 401 | Thời điểm thu hồi và kết quả kiểm thử |
Năm ranh giới mà khóa AI có thể đi qua
Hãy bắt đầu bằng cách lập bản đồ những nơi bí mật hoặc dữ liệu mà nó cho phép truy cập có thể đi qua. Phần lớn sự cố xảy ra vì các nhóm bảo vệ khóa của nhà cung cấp nhưng bỏ sót một trong những ranh giới liền kề này.
| Ranh giới | Sai sót thường gặp | Biện pháp kiểm soát cần có |
|---|---|---|
| Từ máy khách đến ứng dụng | Khóa của nhà cung cấp được nhúng trong gói mã trình duyệt, tệp nhị phân ứng dụng di động, ứng dụng máy tính hoặc tiện ích mở rộng | Giữ khóa của nhà cung cấp ở phía máy chủ; cấp thông tin xác thực người dùng hoặc phiên ngắn hạn cho máy khách |
| Từ ứng dụng đến cổng API | Mọi dịch vụ dùng chung một khóa không bị giới hạn | Dùng danh tính khối lượng công việc, token cổng API có giới hạn phạm vi, hạn ngạch và chính sách tuyến rõ ràng |
| Từ cổng API đến nhà cung cấp | Một thông tin xác thực có thể truy cập mọi mô hình, dự án hoặc môi trường | Tách khóa theo nhà cung cấp, môi trường, khối lượng công việc và mức độ rủi ro nếu được hỗ trợ |
| Từ yêu cầu đến nhật ký | Tiêu đề ủy quyền, câu lệnh, tệp hoặc đầu ra xuất hiện trong dữ liệu truy vết | Chặn các trường chứa bí mật, giảm thiểu ghi nội dung yêu cầu vào nhật ký, thay thông tin định danh bằng token và kiểm thử việc che dữ liệu |
| Thao tác của con người | Khóa được dán vào phiếu yêu cầu, trò chuyện, sổ tay vận hành hoặc công cụ hỗ trợ | Dùng quy trình truy cập có kiểm soát, truy xuất có kiểm toán, quy trình truy cập khẩn cấp và tự động hết hạn |
Bản đồ ranh giới này chuyển câu hỏi thiết kế từ “Chúng ta lưu khóa ở đâu?” thành “Danh tính nào có thể gửi yêu cầu nào, với dữ liệu nào, qua tuyến nào, và sau đó còn lại bằng chứng gì?”
Áp dụng mô hình giữ khóa ở phía máy chủ
Không nên cấp thông tin xác thực dài hạn của nhà cung cấp cho máy khách trình duyệt, di động, máy tính hoặc tiện ích mở rộng. Bất cứ thứ gì được gửi tới thiết bị người dùng cuối đều nên được coi là có thể bị người dùng đó hoặc phần mềm độc hại chạy với cùng quyền trích xuất.
Một mô hình an toàn hơn là:
- Máy khách xác thực với backend của bạn bằng phiên người dùng, thông tin xác thực thiết bị hoặc token ứng dụng ngắn hạn.
- Backend kiểm tra quyền sử dụng tính năng được yêu cầu và áp dụng giới hạn theo người dùng hoặc tenant.
- Cổng API hoặc thành phần tích hợp phía máy chủ chọn nhà cung cấp và mô hình đã được phê duyệt.
- Khóa của nhà cung cấp được truy xuất lúc chạy hoặc được nền tảng triển khai cấp cho khối lượng công việc đáng tin cậy.
- Phản hồi của nhà cung cấp quay về qua cùng ranh giới chính sách.
Máy khách không bao giờ cần bí mật của nhà cung cấp. Nó chỉ nhận quyền gọi sản phẩm của bạn trong các giới hạn bạn xác định.
Với tác nhân lập trình và công cụ phát triển cục bộ, hãy áp dụng cùng nguyên tắc với mô hình ngoại lệ được thiết kế rõ ràng. Lập trình viên có thể cần thông tin xác thực cục bộ, nhưng đó nên là thông tin xác thực của sản phẩm hoặc cổng API, có thể thu hồi, quy được hoạt động sử dụng về người dùng và có phạm vi giới hạn — thay vì khóa nhà cung cấp dùng chung cho toàn tổ chức được sao chép vào các tệp cấu hình ẩn khắp công ty.
Lập danh mục khóa trước khi luân chuyển
Các dự án luân chuyển thất bại khi nhóm không biết khối lượng công việc nào dùng khóa nào. Hãy tạo danh mục máy có thể đọc và chỉ định người phụ trách trước khi thay đổi thông tin xác thực.
Tối thiểu, cần ghi lại:
| Trường | Ví dụ | Vì sao quan trọng |
|---|---|---|
| ID bí mật | prod-support-chat-anthropic-01 |
Tham chiếu nội bộ ổn định, không phải giá trị bí mật |
| Nhà cung cấp và dự án | Tài khoản nhà cung cấp + mã định danh dự án | Xác định phạm vi ảnh hưởng bên ngoài |
| Môi trường | Phát triển, tiền sản xuất, sản xuất | Ngăn hệ thống kiểm thử kế thừa quyền của môi trường sản xuất |
| Khối lượng công việc | support-chat-api |
Cho phép quy nguồn hoạt động sử dụng và thu hồi có mục tiêu |
| Người phụ trách | Nhóm và lịch trực | Xác định trách nhiệm khi xảy ra sự cố |
| Vị trí lưu trữ | Đường dẫn trong trình quản lý bí mật hoặc liên kết cấp bí mật khi triển khai | Cho biết nguồn dữ liệu chuẩn nằm ở đâu |
| Mô hình/tuyến được phép | Họ mô hình đã phê duyệt hoặc chính sách cổng API | Giới hạn việc sử dụng ngoài dự kiến |
| Giới hạn chi tiêu và yêu cầu | Ngân sách khối lượng công việc, RPM, TPM hoặc kiểm soát số tác vụ đồng thời | Hạn chế lạm dụng và tự động hóa mất kiểm soát |
| Thời điểm tạo và luân chuyển gần nhất | Dấu thời gian | Giúp nhận diện thông tin xác thực đã lâu chưa thay |
| Phương thức luân chuyển | Hai khóa, bí danh phiên bản hoặc khung bảo trì | Tránh thay đổi ứng biến |
| Điều kiện phụ thuộc khi thu hồi | Các dịch vụ cần cập nhật trước | Bảo vệ tính sẵn sàng |
| Phân loại dữ liệu | Công khai, nội bộ, bí mật, chịu quy định quản lý | Liên kết chính sách khóa với quản trị câu lệnh |
Không đưa giá trị khóa vào danh mục. Chỉ lưu siêu dữ liệu và tham chiếu tới bí mật được quản lý.
Tách danh tính theo môi trường, khối lượng công việc và rủi ro
Cách làm sai phổ biến nhất là dùng chung một khóa sản xuất cho mọi dịch vụ. Cách này tiện lợi cho đến khi một kho mã, trình chạy kiểm thử, máy tính của nhà thầu hoặc bản ghi hỗ trợ làm lộ khóa. Khi đó, nhóm không thể thu hồi khóa mà không làm gián đoạn các sản phẩm không liên quan.
Nên dùng danh tính riêng cho:
- Môi trường sản xuất, tiền sản xuất, phát triển và kiểm thử cục bộ.
- Lưu lượng phục vụ khách hàng, công cụ nội bộ, tác vụ hàng loạt và quy trình đánh giá.
- Quy trình rủi ro cao có thể gọi công cụ hoặc xử lý dữ liệu bí mật.
- Các đơn vị kinh doanh hoặc tenant khác nhau khi ranh giới hợp đồng yêu cầu tách biệt.
- Truy cập khẩn cấp, vốn nên bị vô hiệu hóa hoặc được kiểm soát chặt trong hoạt động bình thường.
Nếu nhà cung cấp hỗ trợ giới hạn, hãy áp dụng. Các giới hạn có thể bao gồm API, mô hình, mạng nguồn, dự án, nguồn giới thiệu, ứng dụng hoặc hạn ngạch được phép. Chẳng hạn, hướng dẫn về khóa API của Google Cloud khuyến nghị giới hạn khóa, tách biệt khóa, xóa khóa không cần thiết, tránh đưa khóa vào các commit trong kho mã và giám sát việc sử dụng.
Nếu nhà cung cấp không có các biện pháp kiểm soát đủ chi tiết, hãy thực thi chúng tại cổng API của bạn. Cổng API tập trung có thể xác minh khối lượng công việc gọi đến, ánh xạ nó tới tuyến được phê duyệt, áp dụng ngân sách và giới hạn tốc độ, đồng thời giữ thông tin xác thực nhà cung cấp sau một ranh giới phía máy chủ đã được rà soát. Xem thêm hướng dẫn kiến trúc cổng API AI để thiết kế định tuyến và chuyển đổi dự phòng.
Xem quản trị câu lệnh và nhật ký là một phần của quản lý khóa
Khóa API cấp quyền cho một luồng dữ liệu. Bảo vệ khóa mà không kiểm soát luồng đó vẫn để ngỏ rủi ro chính đặc thù của AI.
Trước khi định tuyến yêu cầu, hãy phân loại nội dung và áp dụng nguyên tắc chỉ dùng dữ liệu tối thiểu cần thiết:
- Loại bỏ thông tin xác thực, token, cookie, khóa riêng tư và chuỗi kết nối.
- Loại trừ các trường mà mô hình không cần.
- Thay thông tin định danh trực tiếp bằng token hoặc mã định danh giả nếu tác vụ không cần những thông tin đó.
- Từ chối dữ liệu chịu quy định quản lý hoặc bị hạn chế theo hợp đồng mà hệ thống không hỗ trợ.
- Tách chỉ dẫn hệ thống khỏi nội dung không đáng tin cậy do người dùng cung cấp hoặc được truy xuất.
- Xác thực đối số công cụ trước khi tác nhân có thể gọi hệ thống bên ngoài.
Nhật ký cần có lược đồ rõ ràng. Đừng phụ thuộc vào việc lập trình viên nhớ không ghi đối tượng yêu cầu vào nhật ký. Hãy xác định các trường được phép, rồi loại bỏ hoặc biến đổi mọi trường còn lại.
Một sự kiện hữu ích trong môi trường sản xuất có thể chứa:
{
"request_id": "req_01J...",
"tenant_id_hash": "tnt_7f2...",
"workload": "support-chat-api",
"route_policy": "support-low-risk-v3",
"provider": "selected-provider",
"model": "selected-model",
"input_tokens": 842,
"output_tokens": 211,
"latency_ms": 1370,
"status": 200,
"key_version": "v12",
"redaction_policy": "customer-support-v4"
}
Theo mặc định, sự kiện không nên chứa tiêu đề ủy quyền, khóa nhà cung cấp nguyên gốc, toàn bộ câu lệnh, tài liệu tải lên, đối số công cụ chưa che dữ liệu hoặc toàn bộ đầu ra của mô hình. Nếu cần thu thập nội dung để đánh giá hoặc xử lý sự cố trong phạm vi kiểm soát chặt chẽ, hãy giới hạn thời gian, kiểm soát truy cập và tách rõ khỏi dữ liệu giám sát thông thường.
Tài liệu tra cứu nhanh về ghi nhật ký của OWASP cung cấp cơ sở hữu ích để loại trừ token truy cập, mật khẩu, khóa mã hóa và dữ liệu nhạy cảm khác khỏi nhật ký ứng dụng.
Thiết kế luân chuyển khóa API không gián đoạn
Luân chuyển chỉ là biện pháp kiểm soát hữu hiệu khi có thể thực hiện an toàn. Quy trình gây ngừng dịch vụ sẽ bị trì hoãn cho đến khi có tình huống khẩn cấp.
Dùng quy trình hai khóa hoặc bí mật có phiên bản khi nhà cung cấp hỗ trợ các thông tin xác thực cùng có hiệu lực trong một khoảng thời gian:
- Tạo khóa nhà cung cấp mới. Áp dụng các giới hạn bằng hoặc hẹp hơn khóa cũ.
- Lưu dưới dạng phiên bản bí mật mới. Không ghi đè trực tiếp giá trị cũ nếu nền tảng hỗ trợ phiên bản hoặc bí danh.
- Triển khai các thành phần đọc hỗ trợ phiên bản mới. Cập nhật cổng API hoặc khối lượng công việc để tra cứu bí danh hoặc phiên bản hiện hành.
- Chuyển lưu lượng và quan sát. Dùng phiên bản khóa mới để xác nhận yêu cầu thành công, mô hình đúng dự kiến, chi tiêu, giới hạn tốc độ và tỷ lệ lỗi.
- Loại bỏ các thành phần còn dùng khóa cũ. Kiểm tra danh mục triển khai, tác vụ, tiến trình xử lý và môi trường khôi phục sau thảm họa.
- Thu hồi khóa cũ. Không chỉ ngừng sử dụng; hãy vô hiệu hóa khóa tại nhà cung cấp.
- Xác minh khóa bị từ chối. Một kiểm thử có kiểm soát cần xác nhận thông tin xác thực cũ không còn hoạt động.
- Lưu bằng chứng. Ghi lại dấu thời gian, người phụ trách, khối lượng công việc bị ảnh hưởng, kết quả xác minh và ngày rà soát tiếp theo.
Với hệ thống hỗ trợ chọn phiên bản khóa, ứng dụng nên tham chiếu tới bí danh ổn định thay vì ghi cứng phiên bản bí mật:
type ProviderCredential = {
value: string;
version: string;
};
async function loadProviderCredential(): Promise<ProviderCredential> {
const activeVersion = await secretStore.resolveAlias("ai/provider/active");
const value = await secretStore.readVersion("ai/provider", activeVersion);
return { value, version: activeVersion };
}
Không in value, tuần tự hóa đối tượng trả về hoặc đính kèm nó vào lỗi. Chỉ ghi mã định danh phiên bản không chứa bí mật vào nhật ký.
Tài liệu tra cứu nhanh về quản lý bí mật của OWASP khuyến nghị lập kế hoạch cho toàn bộ vòng đời bí mật, gồm tạo, luân chuyển, thu hồi, hết hạn, kiểm toán, sao lưu và truy cập khẩn cấp. Tài liệu cũng nhấn mạnh việc tự động hóa luân chuyển khi khả thi.
Ngăn bí mật lọt vào kho mã và nhật ký CI
Trình quản lý bí mật không thể giúp khi thông tin xác thực đã được sao chép vào mã nguồn, dữ liệu mẫu kiểm thử, sản phẩm đầu ra của bản dựng hoặc bản ghi CI.
Áp dụng biện pháp kiểm soát ở ba giai đoạn:
Trước khi commit
- Cung cấp tệp
.env.examplechứa giá trị giữ chỗ, không bao giờ chứa thông tin xác thực có hiệu lực. - Giữ các tệp bí mật cục bộ ngoài hệ thống quản lý phiên bản.
- Chạy trình quét bí mật nhanh trong hook trước commit để phát hiện các mẫu khóa nhà cung cấp phổ biến và giá trị có entropy cao.
- Hướng dẫn lập trình viên rằng xóa bí mật trong commit sau không xóa nó khỏi lịch sử.
Khi đẩy mã và tạo yêu cầu hợp nhất
- Bật quét bí mật trong kho mã và bảo vệ khi đẩy mã nếu có hỗ trợ.
- Thêm mẫu tùy chỉnh cho token cổng API nội bộ mà các trình quét công khai không nhận diện được.
- Yêu cầu ghi rõ lý do bỏ qua kiểm tra và chuyển các trường hợp đó tới bộ phận bảo mật để rà soát.
- Quét tệp được tạo tự động, notebook, bản chụp kiểm thử và kế hoạch hạ tầng — không chỉ mã nguồn ứng dụng.
GitHub mô tả bảo vệ khi đẩy mã là cách quét trong quá trình đẩy và chặn bí mật được phát hiện trước khi chúng vào kho mã. Phát hiện được khóa không có nghĩa là nên tiếp tục giữ khóa đó: hãy coi mọi thông tin xác thực đã được xác nhận là có trong commit đều đã bị lộ và luân chuyển chúng.
Trong CI/CD
- Ưu tiên danh tính khối lượng công việc hoặc liên kết danh tính ngắn hạn thay cho thông tin xác thực đám mây được lưu sẵn.
- Chỉ cấp bí mật cho đúng tác vụ và bước cần dùng.
- Che các giá trị bí mật đã biết, nhưng không dựa vào việc che làm biện pháp kiểm soát chính.
- Tắt chế độ truy vết shell khi truy xuất bí mật.
- Ngăn mã không đáng tin cậy từ các bản fork truy cập bí mật triển khai.
- Rà soát sản phẩm đầu ra, bộ nhớ đệm, bản kết xuất khi gặp sự cố và báo cáo kiểm thử để phát hiện việc vô tình lưu bí mật.
Giám sát việc sử dụng mà không ghi bí mật vào nhật ký
Giám sát hiệu quả trả lời được “ai đã dùng quyền nào?” mà không ghi lại chính thông tin cấp quyền đó.
Theo dõi:
- Khối lượng công việc, môi trường, tenant hoặc dự án và phiên bản khóa.
- Nhà cung cấp, mô hình, chính sách tuyến và đường dự phòng.
- Số yêu cầu, lượng token, chi tiêu, độ trễ và nhóm lỗi.
- Mạng nguồn hoặc danh tính triển khai khi hữu ích.
- Hoạt động truy cập trình quản lý bí mật, bao gồm cả các lần đọc bị từ chối.
- Việc tạo khóa, thay đổi giới hạn, luân chuyển, thu hồi và xóa khóa.
- Hoạt động sử dụng đột ngột từ môi trường, khu vực địa lý, mô hình hoặc khung giờ ngoài dự kiến.
Thiết lập cảnh báo dựa trên hành vi, không chỉ tổng chi tiêu. Khóa có ngân sách thấp bị đánh cắp vẫn có thể làm lộ câu lệnh hoặc bị dùng để thăm dò quy trình nội bộ. Ngược lại, tác vụ hàng loạt hợp lệ có thể khiến chi tiêu tăng vọt mà không có thông tin xác thực nào bị xâm phạm. Đối chiếu hoạt động sử dụng tại nhà cung cấp với ID yêu cầu của ứng dụng, quyết định chính sách của cổng API, sự kiện triển khai và nhật ký kiểm toán của trình quản lý bí mật.
Để bổ sung biện pháp kiểm soát lưu lượng cho việc kiểm soát thông tin xác thực, hãy tham khảo hướng dẫn giới hạn tốc độ LLM và cẩm nang định tuyến dự phòng API LLM.
Đo thời gian từ khi phát hiện lộ khóa đến khi thu hồi trong sự cố
Khi khóa có khả năng bị lộ, mục tiêu đầu tiên là khoanh vùng sự cố, thay vì chứng minh kẻ tấn công đã dùng khóa hay chưa.
Thực hiện theo trình tự sau:
- Đánh dấu thông tin xác thực là đáng ngờ. Ghi lại thời điểm và nơi nó có thể đã bị lộ.
- Tạo khóa thay thế theo quy trình có kiểm soát thông thường. Không dán khóa mới vào trò chuyện để xử lý sự cố nhanh hơn.
- Chuyển khối lượng công việc hợp lệ sang khóa thay thế. Dùng quy trình luân chuyển đã chuẩn bị.
- Thu hồi khóa đáng ngờ. Nếu thu hồi ngay sẽ gây hậu quả không thể chấp nhận, hãy cô lập các tuyến và giảm giới hạn trong khi hoàn tất chuyển đổi.
- Tìm ở mọi nơi có thể chứa bản sao. Kiểm tra lịch sử mã nguồn, nhật ký CI, sản phẩm đầu ra, các lớp container, hệ thống hỗ trợ, bảng theo dõi, notebook, cấu hình cục bộ và bản sao lưu.
- Rà soát các luồng dữ liệu được cấp quyền. Xác định khóa có thể truy cập câu lệnh, đầu ra, tệp, công cụ hoặc mô hình nào, không chỉ phạm vi thanh toán.
- Đối chiếu hoạt động. So sánh hoạt động sử dụng tại nhà cung cấp, nhật ký cổng API, các lần triển khai, truy xuất bí mật và hoạt động người dùng.
- Thông báo cho đúng bên phụ trách. Huy động các nhóm bảo mật, nền tảng, pháp lý, quyền riêng tư và khách hàng tùy theo dữ liệu và hợp đồng liên quan.
- Loại bỏ nguyên nhân gốc rễ. Bổ sung trình quét, giới hạn, ranh giới danh tính hoặc bộ lọc nhật ký còn thiếu.
- Đo thời gian. Ghi lại thời gian đến khi phát hiện, thay thế, chuyển lưu lượng, thu hồi và xác minh.
Chỉ số dễ chuyển thành hành động nhất thường là thời gian từ khi phát hiện lộ khóa đến khi thu hồi: khoảng thời gian thông tin xác thực đáng ngờ vẫn dùng được sau khi tổ chức có bằng chứng đáng tin cậy về việc bị lộ. Rút ngắn khoảng thời gian này đòi hỏi phân công trách nhiệm sẵn, danh mục, tự động hóa và quy trình luân chuyển đã kiểm thử, chứ không phải tài liệu chính sách dài hơn.
Nếu bạn cấp khóa API cho khách hàng của mình
Nhiều sản phẩm AI cũng cấp khóa, chẳng hạn để khách hàng gọi tác nhân hoặc nhúng tính năng của bạn. Các phương pháp tương tự cũng áp dụng khi bạn là bên cấp khóa:
- Tạo khóa bằng bộ sinh số ngẫu nhiên an toàn về mặt mật mã, với ít nhất 32 byte entropy.
- Thêm tiền tố dễ nhận diện (như
sk-fk-trên khóa Flatkey) để trình quét bí mật và nhóm hỗ trợ có thể nhận ra khóa bị lộ. Chương trình đối tác của GitHub dùng các định dạng token đã biết để thông báo cho bên phát hành khi khóa được đẩy lên kho mã công khai (quét bí mật của GitHub). - Chỉ hiển thị toàn bộ khóa một lần, sau đó chỉ lưu giá trị băm. Nếu cơ sở dữ liệu bị rò rỉ, các khóa vẫn an toàn.
- Chỉ hiển thị tiền tố đã che bớt trên bảng điều khiển, cùng ngày tạo và thời điểm sử dụng gần nhất.
- Thu hồi có hiệu lực ngay và trả về
401cho khóa đã thu hồi. - Cho phép khách hàng giới hạn phạm vi khóa theo mô hình, dự án hoặc mức chi tiêu cụ thể.
Python: tạo, băm và xác minh khóa
import hashlib
import hmac
import secrets
PREFIX = "sk-acme-"
def new_api_key() -> tuple[str, str]:
"""Return (plaintext key shown to the user once, hash to store)."""
key = PREFIX + secrets.token_urlsafe(32) # 32 random bytes
return key, hashlib.sha256(key.encode()).hexdigest()
def verify(presented: str, stored_hash: str) -> bool:
candidate = hashlib.sha256(presented.encode()).hexdigest()
return hmac.compare_digest(candidate, stored_hash) # constant-time compare
key, digest = new_api_key()
print(key[:12] + "...") # show the full key once in the UI, never log it
print(verify(key, digest)) # True
Hàm băm nhanh như SHA-256 có thể chấp nhận được ở đây vì khóa dài và ngẫu nhiên, khác với mật khẩu do con người đặt. Lưu giá trị băm, ID khóa, người sở hữu, phạm vi quyền và dấu thời gian.
Node.js: nạp khóa từ môi trường và từ chối hoạt động khi không đáp ứng điều kiện an toàn
// Never fall back to a hardcoded default key.
const apiKey = process.env.FLATKEY_API_KEY;
if (!apiKey || !apiKey.startsWith("sk-fk-")) {
throw new Error("FLATKEY_API_KEY is missing or malformed");
}
const res = await fetch("https://router.flatkey.ai/v1/chat/completions", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "claude-haiku-5-5",
messages: [{ role: "user", content: "ping" }],
max_tokens: 5,
}),
});
console.log(res.status); // log the status, never the header
Xác minh khóa đã thu hồi thực sự không còn hoạt động
Việc thu hồi chỉ được chứng minh khi khóa cũ không dùng được. Sau mỗi lần luân chuyển hoặc sự cố, hãy chạy kiểm tra như sau từ một máy đáng tin cậy:
# Expect 401 for the revoked key; do not echo the key itself
OLD_KEY="$(cat /run/secrets/old_flatkey_key)"
status=$(curl -s -o /dev/null -w "%{http_code}" \
https://router.flatkey.ai/v1/models \
-H "Authorization: Bearer $OLD_KEY")
if [ "$status" = "401" ]; then echo "revoked OK"; else echo "STILL ACTIVE: $status"; fi
Ghi kết quả và thời gian vào nhật ký luân chuyển. Tài liệu Flatkey nêu rõ việc thu hồi có hiệu lực ngay và mọi yêu cầu dùng khóa đã thu hồi đều nhận 401 Unauthorized, không có thời gian gia hạn (tài liệu khóa API của Flatkey).
Flatkey hỗ trợ các phương pháp này như thế nào
Flatkey cung cấp một điểm cuối tương thích OpenAI (https://router.flatkey.ai/v1) cho nhiều nhà cung cấp mô hình, giúp giảm số khóa nhà cung cấp phân tán trong các dịch vụ. Theo tài liệu khóa API của Flatkey (kiểm tra ngày 27 tháng 10 năm 2026):
- Bạn có thể tạo nhiều khóa: mỗi môi trường, ứng dụng hoặc thành viên nhóm một khóa, với tên mô tả rõ ràng như
prod-customer-chatbot. - Toàn bộ khóa
sk-fk-chỉ được hiển thị một lần. Sau đó, trang Khóa liệt kê tên, ngày tạo, dấu thời gian sử dụng gần nhất và tiền tố đã che bớt. - Thu hồi có hiệu lực ngay, vì vậy hãy triển khai khóa thay thế trước khi thu hồi khóa cũ.
- Tất cả khóa dùng chung số dư tài khoản và mặc định có thể truy cập mọi mô hình. Dùng Nhóm trong bảng điều khiển để giới hạn khóa theo mô hình cụ thể hoặc đặt hạn ngạch chi tiêu.
Tài liệu sử dụng mô tả nhật ký theo từng yêu cầu với mô hình, token, chi phí và khóa, cùng giới hạn chi tiêu hằng tháng và cảnh báo số dư thấp qua email, đáp ứng các phương pháp 10 và 11. Với tổ chức lớn hơn, tài liệu doanh nghiệp của Flatkey mô tả khóa con theo cấu trúc cây với ngân sách và danh sách mô hình được phép riêng. Cổng API không thay thế việc xác thực máy khách, phân loại dữ liệu và ghi nhật ký an toàn của bạn, vì vậy hãy tiếp tục áp dụng các mục còn lại trong danh sách kiểm tra. Để bắt đầu, xem hướng dẫn bắt đầu tích hợp Flatkey.
Kiến trúc tham chiếu cho sản phẩm AI dùng nhiều nhà cung cấp
Một hệ thống đa nhà cung cấp an toàn có thể được tổ chức thành năm lớp:
- Lớp danh tính máy khách: xác thực người dùng, thiết bị, tác nhân hoặc ứng dụng mà không làm lộ thông tin xác thực nhà cung cấp.
- Lớp phân quyền ứng dụng: xác minh quyền sử dụng sản phẩm, ranh giới tenant, quyền truy cập tính năng và ngân sách.
- Lớp chính sách dữ liệu: phân loại và che dữ liệu trong câu lệnh, tệp, ngữ cảnh được truy xuất và đối số công cụ.
- Lớp cổng API và định tuyến: chọn mô hình đã phê duyệt, áp dụng hạn ngạch, ghi nhận thông tin quy nguồn không chứa bí mật và xử lý chuyển đổi dự phòng.
- Lớp thông tin xác thực nhà cung cấp: lưu riêng thông tin xác thực từng nhà cung cấp, luân chuyển phiên bản và chỉ cấp chúng cho khối lượng công việc định tuyến đáng tin cậy.
Thiết kế này giới hạn phạm vi ảnh hưởng. Token máy khách bị xâm phạm không tự động làm lộ khóa nhà cung cấp. Danh tính khối lượng công việc bị xâm phạm không nên cho phép truy cập mọi nhà cung cấp. Thông tin xác thực nhà cung cấp bị lộ không nên cấp quyền cho mọi môi trường. Sai sót khi ghi nhật ký không nên làm lộ cả bí mật lẫn toàn bộ nội dung yêu cầu.
Danh sách kiểm tra cho môi trường sản xuất
Dùng danh sách này trước khi ra mắt và trong các đợt rà soát biện pháp kiểm soát hằng quý.
Quản lý khóa và danh tính
- [ ] Không có khóa nhà cung cấp dài hạn nào được đưa vào mã trình duyệt, ứng dụng di động, ứng dụng máy tính hoặc tiện ích mở rộng.
- [ ] Mỗi khối lượng công việc sản xuất đều xác định được người phụ trách và đường cấp thông tin xác thực.
- [ ] Truy cập cho môi trường sản xuất, tiền sản xuất, phát triển, đánh giá và cục bộ được tách biệt.
- [ ] Khóa dùng chung giữa người dùng đã được thay bằng danh tính khối lượng công việc hoặc cổng API ở những nơi có thể.
- [ ] Các giới hạn của nhà cung cấp và cổng API được đặt ở phạm vi hẹp nhất có thể áp dụng thực tế.
Lưu trữ và cấp phát
- [ ] Nguồn dữ liệu chuẩn là kho bí mật được quản lý hoặc liên kết cấp bí mật khi triển khai có kiểm soát.
- [ ] Ứng dụng chỉ truy xuất bí mật lúc chạy và không in hoặc tuần tự hóa chúng.
- [ ] Tác vụ CI chỉ nhận các bí mật cần thiết cho đúng bước cần dùng.
- [ ] Hoạt động truy cập bí mật và các thay đổi quản trị được kiểm toán.
- [ ] Truy cập khẩn cấp được lập tài liệu, giới hạn thời gian và kiểm thử.
Dữ liệu và khả năng quan sát
- [ ] Tiêu đề ủy quyền và giá trị khóa bị loại khỏi nhật ký, dữ liệu truy vết, lỗi và dữ liệu xuất phục vụ hỗ trợ.
- [ ] Việc ghi nhật ký câu lệnh, đầu ra, tệp và đối số công cụ tuân theo lược đồ các trường được phép.
- [ ] Dữ liệu được che trước khi định tuyến đến nhiều nhà cung cấp.
- [ ] Hoạt động sử dụng có thể được quy về khối lượng công việc, môi trường, tuyến, nhà cung cấp, mô hình và phiên bản khóa.
- [ ] Cảnh báo bao quát cả tuyến và danh tính bất thường, bên cạnh chi tiêu.
Luân chuyển và ứng phó
- [ ] Có quy trình luân chuyển hai khóa hoặc bí mật có phiên bản đã được kiểm thử.
- [ ] Khóa cũ được thu hồi tại nhà cung cấp và được xác minh là không thể sử dụng.
- [ ] Quét bí mật và bảo vệ khi đẩy mã bao quát các kho mã và sản phẩm đầu ra được tạo tự động.
- [ ] Nghi ngờ rò rỉ sẽ kích hoạt khoanh vùng ngay mà không chờ bằng chứng lạm dụng.
- [ ] Thời gian từ khi phát hiện lộ khóa đến khi thu hồi được đo sau các đợt diễn tập và sự cố.
Câu hỏi thường gặp
Những phương pháp quản lý khóa API hiệu quả là gì?
Giữ khóa ngoài mã nguồn và ứng dụng phía máy khách, dùng khóa riêng cho từng môi trường và khối lượng công việc, giới hạn mỗi khóa theo API, mô hình và ngân sách cần thiết, lưu khóa trong trình quản lý bí mật, luân chuyển theo lịch trình đã kiểm thử, xóa khóa không dùng, bật quét bí mật, không bao giờ ghi khóa vào nhật ký và thu hồi ngay khi nghi ngờ rò rỉ.
Có nên lưu khóa API trong biến môi trường không?
Biến môi trường là cách hợp lý để cấp khóa cho một tiến trình, nhưng không phải hệ thống quản lý. Giá trị nên đến từ trình quản lý bí mật hoặc cơ chế truyền bí mật của nền tảng, có kiểm soát truy cập, luân chuyển và kiểm toán. Không bao giờ đưa tệp .env vào commit.
Nên luân chuyển khóa API bao lâu một lần?
Chọn chu kỳ dựa trên rủi ro và các biện pháp kiểm soát của nhà cung cấp; nhiều nhóm luân chuyển khóa AI sản xuất mỗi 90 ngày và luân chuyển ngay sau thay đổi nhân sự hoặc khi nghi ngờ bị lộ. Điều quan trọng nhất là diễn tập luân chuyển, thu hồi khóa cũ và xác minh việc thu hồi.
Trình duyệt hoặc ứng dụng di động có thể gọi trực tiếp nhà cung cấp AI bằng khóa API không?
Nên tránh. Bất cứ thứ gì được đưa lên thiết bị đều có thể bị trích xuất. Hãy để máy khách xác thực với backend của bạn, rồi để backend hoặc cổng API gọi mô hình bằng khóa phía máy chủ và áp dụng giới hạn theo người dùng.
Tôi nên làm gì nếu khóa API bị lộ trên GitHub?
Hãy coi khóa đã bị xâm phạm. Tạo khóa thay thế, chuyển khối lượng công việc sang khóa mới, thu hồi khóa bị lộ, xác nhận khóa trả về 401, rà soát việc sử dụng trong thời gian bị lộ và bổ sung quét bí mật hoặc bảo vệ khi đẩy mã để tránh tái diễn. Xóa commit không làm khóa trở nên an toàn.
Một khóa cổng API có an toàn hơn nhiều khóa nhà cung cấp không?
Cách này giảm số bí mật trong mã của bạn, nhưng tập trung quyền truy cập. Dùng khóa cổng API riêng cho từng môi trường và khối lượng công việc, giới hạn phạm vi theo mô hình và chi tiêu, đồng thời bảo vệ khóa nhà cung cấp phía sau cổng API cẩn thận như trước.
Tôi nên lưu khóa API do mình cấp cho người dùng như thế nào?
Chỉ lưu giá trị băm của từng khóa, hiển thị toàn bộ khóa một lần khi tạo, sau đó chỉ hiển thị tiền tố đã che bớt và hỗ trợ thu hồi tức thì.
Nguồn tham khảo và tài liệu đọc thêm
- Tài liệu tra cứu nhanh về quản lý bí mật của OWASP
- Tài liệu tra cứu nhanh về ghi nhật ký của OWASP
- GitHub: Giới thiệu về quét bí mật
- GitHub: Giới thiệu về bảo vệ khi đẩy mã
- Google Cloud: Các phương pháp quản lý khóa API
- Flatkey: Tạo và quản lý khóa API
Các hướng dẫn Flatkey liên quan: Chính sách che dữ liệu cho API AI, Kiến trúc cổng API AI và Giải thích giới hạn tốc độ LLM.
