Quản lý khóa API và bí mật trong dự án phần mềm: cất ở đâu, xoay khi nào, lộ rồi làm gì

Khóa API, mật khẩu cơ sở dữ liệu và token truy cập có giá trị như chìa khóa két sắt. Khi chúng nằm trong mã nguồn, kho mã hoặc gói JavaScript gửi xuống trình duyệt, ai đọc được thì dùng được.

Bài này trình bày cách quản lý khóa API và bí mật trong dự án phần mềm: phân loại khóa, nơi cất, cấp quyền, chặn khi đẩy mã, xoay khóa và việc phải làm ngay khi lộ. Nguồn là tài liệu của OWASP, GitHub, Vercel, Next.js, Supabase, Stripe, Anthropic và báo cáo của GitGuardian, đối chiếu đến ngày 23/10/2026.

Click Star đã có bài riêng về API, checklist bảo mật website và passkey, MFA, RLS; bài này đi vào vòng đời của khóa. Chưa có số đo về sự cố lộ khóa ở doanh nghiệp Việt Nam.

Điểm chính

• Khóa API, token và mật khẩu cơ sở dữ liệu đều là "bí mật": ai giữ chuỗi đó thì hành động được dưới danh nghĩa chủ tài khoản.
• GitGuardian, hãng bán công cụ phát hiện bí mật, ghi 28.649.024 bí mật mới trong commit công khai trên GitHub năm 2025. Đây là số của nhà cung cấp, không phải khảo sát độc lập.
• Mỗi loại khóa có chỗ đặt riêng: khóa publishable của Supabase và Stripe được ở trình duyệt, khóa bí mật chỉ ở máy chủ. Biến NEXT_PUBLIC_ của Next.js bị nhúng vào gói JavaScript gửi cho mọi người truy cập.
• Phòng thủ theo 4 lớp (khung của Click Star): không đưa vào mã, chặn khi đẩy mã, phát hiện sớm, giảm thiệt hại bằng quyền tối thiểu, hạn mức chi tiêu và xoay khóa.
• Khi khóa đã lộ, thu hồi hoặc xoay khóa trước. GitHub nói đó là bước đầu và có thể giải quyết vấn đề mà không cần viết lại lịch sử Git.
• Trước sự cố: lập sổ kiểm kê khóa, bật push protection, dùng khóa riêng theo môi trường và diễn tập xoay 1 khóa thật.

Khóa API và bí mật là gì, và vì sao hay bị lộ

Khóa API là chuỗi ký tự chứng minh yêu cầu gửi tới 1 dịch vụ đến từ bên được phép. Cùng nhóm "bí mật" còn có token, mật khẩu cơ sở dữ liệu, khóa SSH và chứng chỉ (OWASP, không ghi ngày, đọc 23/10/2026).

OWASP nhận xét bí mật thường bị mã hóa cứng dạng chữ thuần trong mã. Stripe viết rằng kẻ xấu liên tục quét kho mã công khai để tìm khóa, và kho riêng tư vẫn có thể lộ qua môi trường phát triển.

Về quy mô, báo cáo "State of Secrets Sprawl 2026" của GitGuardian (không ghi ngày xuất bản, đọc 23/10/2026) ghi 28.649.024 bí mật mới trong commit công khai năm 2025. Báo cáo cũng ghi 5,6% kho công khai và 32,2% kho nội bộ có ít nhất 1 bí mật.

Với bí mật phát hiện năm 2022, báo cáo ghi 64% vẫn còn hiệu lực sau 4 năm; báo cáo nhận xét vấn đề nằm ở khắc phục chứ không ở phát hiện. Giới hạn: đây là dữ liệu của hãng bán công cụ liên quan, trang không định nghĩa đầy đủ cách đếm và không có số riêng cho Việt Nam.

Khóa nào được ở trình duyệt, khóa nào chỉ ở máy chủ

Cùng 1 nhà cung cấp thường phát hành cả khóa cho trình duyệt lẫn khóa chỉ cho máy chủ, nên hãy xác định loại khóa trước.

Theo tài liệu khóa API của Supabase, khóa publishable (sb_publishable_) có quyền thấp và được đặt trong trình duyệt hoặc ứng dụng. Khóa secret (sb_secret_) có thuộc tính BYPASSRLS nên bỏ qua chính sách RLS, và không bao giờ được đặt trong trình duyệt, kể cả ở localhost.

Stripe nêu cùng nguyên tắc: khóa publishable an toàn trong trang web và ứng dụng, khóa secret phải ở máy chủ vì người ngoài có thể bóc ứng dụng để tìm khóa nhúng bên trong.

Với Next.js, tài liệu (cập nhật 25/8/2026) nói biến không có tiền tố NEXT_PUBLIC_ chỉ có ở phía máy chủ. Biến có tiền tố này được nhúng vào gói JavaScript khi chạy next build, nên không được chứa khóa bí mật.

Cất bí mật ở đâu và tách theo môi trường

Theo phương pháp 12-factor (cập nhật 2017), cấu hình gồm thông tin xác thực cho dịch vụ ngoài và phải tách khỏi mã; phép thử là mã có thể mở nguồn bất kỳ lúc nào mà không lộ thông tin xác thực.

OWASP đề xuất tập trung nơi lưu bí mật và cân nhắc tách kho của môi trường sản xuất khỏi môi trường phát triển.

Stripe khuyên dùng kho bí mật của nền tảng nếu có, và dùng biến môi trường nếu nền tảng không có. Trên Vercel, tài liệu (cập nhật 28/8/2026) chia biến thành Config và Secret. Giá trị Secret chỉ ghi sau khi lưu, dùng cho mật khẩu, khóa API và token.

Vercel có chính sách tùy chọn buộc mỗi Secret ở Production khác giá trị ở Preview và Development.

Tài liệu Next.js cảnh báo gần như không bao giờ nên commit tệp .env. Tài liệu Git (đọc 23/10/2026) nói .gitignore không ảnh hưởng tệp đã được theo dõi; phải dùng git rm --cached.

Cấp quyền tối thiểu và dùng khóa riêng cho từng việc

Khóa quyền hẹp giới hạn thiệt hại khi lộ. OWASP đề nghị quyền tối thiểu cho người và hệ thống đọc kho bí mật, kiểm soát chi tiết từng đối tượng.

Stripe cho ví dụ: khóa hạn chế cho hệ thống hóa đơn chỉ được quản lý hóa đơn; nếu khóa bị lấy, kẻ tấn công chỉ gọi được các thao tác được cấp.

GitHub (tài liệu token cá nhân, đọc 23/10/2026) khuyến nghị dùng fine-grained token thay token classic và đặt hạn dùng.

Anthropic hướng dẫn dùng khóa riêng cho từng môi trường để vô hiệu hóa 1 khóa bị lộ mà không ảnh hưởng khóa khác và, với tổ chức có giới hạn tùy chỉnh, đặt hạn mức chi tiêu.

Chặn từ cửa vào: quét bí mật và chặn đẩy mã

Phát hiện bí mật đã nằm trong kho và chặn bí mật trước khi vào kho là 2 việc khác nhau. GitHub làm cả 2 qua secret scanning và push protection (GitHub Docs).

Secret scanning quét toàn bộ lịch sử Git trên mọi nhánh. Kho công khai được quét miễn phí; kho riêng tư của tổ chức cần GitHub Secret Protection trên gói Team hoặc Enterprise Cloud.

Push protection chặn bí mật khi đẩy mã, commit trên giao diện, tải tệp lên và gọi REST API. Với kho, tính năng này tắt theo mặc định và cần Secret Protection; bản cho người dùng bật sẵn trên GitHub.com nhưng chỉ áp cho kho công khai.

Mặc định, ai có quyền ghi vẫn vượt chặn được nếu chọn lý do; mỗi lần vượt tạo cảnh báo, và lý do "I'll fix it later" để cảnh báo ở trạng thái mở.

Gitleaks (giấy phép MIT) quét kho Git và chạy được như hook pre-commit; trang của nó ghi công cụ chỉ nhận bản vá bảo mật và người duy trì chuyển trọng tâm sang Betterleaks.

Xoay khóa: định kỳ và theo sự kiện

OWASP nói xoay đều đặn giới hạn tác dụng của khóa bị đánh cắp và không nêu chu kỳ cụ thể. Anthropic nêu ví dụ 90 ngày; đó là ví dụ, không phải chuẩn.

Vercel liệt kê các lúc nên xoay: thành viên có quyền rời nhóm, nghi khóa lộ, chính sách yêu cầu hoặc dịch vụ ngoài bắt buộc (cập nhật 15/7/2026). Thứ tự: tạo khóa mới, cập nhật biến, triển khai lại, xác nhận chạy đúng rồi mới vô hiệu hóa khóa cũ.

Theo Vercel (cập nhật 17/9/2026), thay đổi biến chỉ áp dụng cho bản triển khai mới. Trang xoay khóa (cập nhật 15/7/2026) nói thêm rằng bản cũ giữ giá trị cũ và sẽ lỗi khi khóa cũ bị vô hiệu hóa, còn biến cấp nhóm phải triển khai lại mọi dự án dùng nó.

Khi đã lộ khóa: làm gì và theo thứ tự nào

Coi khóa là đã lộ ngay khi thấy nó ở nơi không nên có. Stripe nói đổi khóa ngay cả khi không chắc có ai nhìn thấy; GitHub khuyên xoay ngay thông tin xác thực khi nhận cảnh báo.

Thu hồi trước, dọn sau. OWASP liệt kê thứ tự: thu hồi khóa lộ ngay, xoay nhanh, xóa khỏi mã và nhật ký (viết lại lịch sử có tác dụng phụ), ghi lại khóa được dùng khi nào. GitHub nói thu hồi hoặc xoay là bước đầu, còn dọn lịch sử Git tốn thời gian và thường không cần thiết khi khóa đã bị thu hồi.

Các nguồn không thống nhất hoàn toàn về thứ tự. Anthropic nói thu hồi ngay; Supabase liệt kê tạo mới, thay, xác nhận, xóa cũ nhưng cũng nói xóa ngay khóa bị lộ; Vercel tạo khóa mới trước kể cả khi chỉ nghi ngờ lộ.

Nhận định của Click Star: nếu khóa chạm được tiền hoặc dữ liệu cá nhân, thu hồi trước và chấp nhận gián đoạn ngắn; nếu quyền hẹp, tạo mới rồi mới thu hồi.

Sau đó xem nhật ký sử dụng trong thời gian khóa bị lộ để tìm lệnh gọi không phải của mình. Nếu khóa đã bị dùng, đó là sự cố thật; theo nhận định của Click Star, hãy báo người chịu trách nhiệm dữ liệu và đối chiếu quy định hiện hành.

Dọn lịch sử Git là bước sau và có cái giá. GitHub mô tả dùng git-filter-repo rồi đẩy lại bằng push --force --mirror. Mã băm commit đổi, chữ ký commit mất, và commit vẫn có thể truy cập qua cache, pull request hoặc bản fork; GitHub Support chỉ hỗ trợ khi thu hồi bí mật không giảm được rủi ro.

Ý nghĩa với doanh nghiệp Việt Nam và cách đo

Phần này là suy luận. Việc đáng kiểm tra đầu tiên là quyền sở hữu: tài khoản GitHub, Vercel, cơ sở dữ liệu, thanh toán và nhà cung cấp AI nên đứng tên doanh nghiệp. Khi nhân sự hay nhà thầu rời đi, hãy xoay các khóa họ từng đọc được.

Các chỉ số dưới đây là khung tham khảo của Click Star, không lấy từ nguồn ngoài và không kèm ngưỡng chuẩn.

• Tỷ lệ khóa có trong sổ kiểm kê so với khóa tìm thấy khi quét.
• Tuổi của khóa cũ nhất và số khóa chưa từng được xoay.
• Số cảnh báo bí mật đang mở.
• Thời gian từ phát hiện đến thu hồi ở lần diễn tập hoặc sự cố gần nhất.

Đánh giá của Click Star. Các lỗi mà tài liệu mô tả, như khóa dán vào mã cho nhanh, 1 khóa dùng chung cho mọi môi trường hay không ai biết khóa nào đang dùng ở đâu, là lỗi quy trình nhiều hơn lỗi kỹ thuật phức tạp. Sổ kiểm kê và diễn tập xoay thường đem lại nhiều giá trị hơn việc mua thêm công cụ.

Click Star làm phần mềm theo yêu cầu và tích hợp AI nên có lợi ích liên quan, và ở đây dựa vào tài liệu bên thứ ba. Lớp đáng đầu tư đầu tiên là chặn khi đẩy mã kèm quyền tối thiểu, vì giảm cả xác suất lẫn thiệt hại.

Lộ trình 30 ngày (khung tham khảo của Click Star)

Lộ trình do Click Star đề xuất, không lấy từ nguồn ngoài.

Tuần 1, kiểm kê

• Lập sổ kiểm kê: tên, chủ sở hữu, nơi dùng, môi trường, quyền
• Quét lịch sử kho mã bằng secret scanning hoặc Gitleaks
• Xác nhận tài khoản dịch vụ đứng tên doanh nghiệp
• Tìm khóa bí mật trong mã trình duyệt và biến NEXT_PUBLIC_

Tuần 2, chặn lối vào

• Bật push protection hoặc hook pre-commit
• Kiểm tra .gitignore cho .env
• Chuyển khóa sang biến Secret, tách Production khỏi Preview
• Đặt hạn mức chi tiêu cho khóa AI và thanh toán

Tuần 3, giảm quyền

• Thay khóa toàn quyền bằng khóa hạn chế
• Tạo khóa riêng cho từng môi trường và dịch vụ
• Đặt hạn dùng cho token cá nhân
• Gỡ quyền người đã rời dự án và xoay khóa họ từng đọc được

Tuần 4, diễn tập

• Viết quy trình lộ khóa dài 1 trang
• Diễn tập xoay 1 khóa thật từ tạo mới đến thu hồi khóa cũ
• Đặt lịch rà sổ kiểm kê và cảnh báo mở hằng tháng

Những sai lầm thường gặp

1. Dán khóa vào mã "tạm thời" rồi quên, trong khi lịch sử Git giữ nó.
2. Tin rằng kho riêng tư đủ an toàn để chứa khóa.
3. Đặt khóa bí mật trong biến NEXT_PUBLIC_ hoặc mã chạy ở trình duyệt.
4. Dùng 1 khóa quyền rộng cho mọi môi trường và dịch vụ.
5. Xóa commit chứa khóa nhưng không thu hồi khóa.
6. Khi xoay khóa có kế hoạch, thu hồi khóa cũ trước khi triển khai lại mọi dự án và bản Preview dùng khóa đó.
7. Bỏ qua cảnh báo bí mật cũ hoặc chọn "I'll fix it later" rồi không quay lại.

Điều chưa biết

Click Star không có số đo về tần suất lộ khóa, thời gian phát hiện hay chi phí sự cố ở doanh nghiệp Việt Nam. Số liệu GitGuardian do hãng bán công cụ công bố, chưa có kiểm chứng độc lập.

Trong các tài liệu đã đọc, OWASP không nêu chu kỳ xoay khóa và Anthropic chỉ nêu ví dụ 90 ngày. Click Star không mở được trang OpenAI về an toàn khóa API (bị chặn công cụ) nên không dựa vào đó.