Hướng dẫn toàn diện 5 phương pháp xác thực CLI cho nhà phát triển

Xác thực luôn là bước đầu tiên và quan trọng khi xây dựng công cụ dòng lệnh (CLI). Mỗi công cụ lại lựa chọn cách tiếp cận khác nhau, từ việc nhập mã trên trình duyệt đến dùng khóa API hoặc các cơ chế OAuth phức tạp. Trong bài viết này, chúng ta sẽ cùng tìm hiểu chi tiết về 5 phương pháp xác thực phổ biến nhất, cách các công cụ lớn áp dụng, và những lỗi sai có thể phá hoại trải nghiệm người dùng cũng như an ninh.

Tổng quan về 5 phương pháp xác thực

Phương pháp	Phù hợp với	Mức độ bảo mật	Cần trình duyệt?
OAuth Device Code Flow	Môi trường không có giao diện	Cao	Không (trình duyệt nằm trên thiết bị khác)
Browser OAuth (localhost)	Phát triển máy cục bộ	Cao	Có
PKCE Authorization Code	CLI hiện đại có trình duyệt	Cao nhất	Có
API Keys / Token cá nhân	Tự động hóa, CI/CD	Trung bình	Không
Client Credentials Flow	Máy-máy, dịch vụ tự động	Cao	Không

Mỗi phương pháp có ưu và nhược điểm riêng, cần lựa chọn phù hợp theo trường hợp sử dụng.

1. OAuth Device Code Flow (RFC 8628)

Phương pháp này cho phép CLI hiện một mã ngắn và URL, người dùng mở URL trên bất kỳ thiết bị nào để nhập mã và đăng nhập.

Ví dụ sử dụng: GitHub CLI, Azure CLI (tuỳ chọn), Vercel CLI (mặc định từ 09/2025), OpenAI Codex CLI (beta)

Cách hoạt động

1. Chạy lệnh cli login
2. CLI gửi yêu cầu lấy device_code từ server xác thực
3. Server trả về: device_code, user_code (mã nhập tay), verification_uri (địa chỉ web)
4. CLI hiển thị mã và URL, bắt đầu kiểm tra trạng thái đăng nhập định kỳ
5. Người dùng mở URL trên thiết bị khác, nhập mã và xác thực bằng mật khẩu, SSO, MFA...
6. Khi duyệt thành công, server trả token truy cập và token làm mới
7. CLI lưu token và cho phép truy cập

Ưu điểm

• Hoạt động tốt ở môi trường không có giao diện (headless) như SSH, Docker, Cloud IDE.
• Hỗ trợ đầy đủ các phương thức xác thực doanh nghiệp: SAML, OIDC, MFA.
• CLI không trực tiếp nhận mật khẩu người dùng — tất cả diễn ra trên trình duyệt.

Rủi ro bảo mật và thực tiễn

Device code flow có rủi ro phishing: kẻ tấn công có thể kích hoạt mã thiết bị và đánh lừa người dùng cấp quyền cho phiên đăng nhập của họ. AWS đã chuyển mặc định từ device code flow sang PKCE để giảm thiểu vấn đề này.

Microsoft thậm chí chặn hoàn toàn device code flow với một số chính sách truy cập.

Tóm lại, device code flow rất phù hợp khi không thể mở trình duyệt trên cùng máy. Nếu mở được, PKCE là lựa chọn an toàn hơn.

Một số chi tiết kỹ thuật trong RFC

• device_code có thời hạn thường là 30 phút, có thể thay đổi.
• Polling mặc định 5 giây, có thể điều chỉnh theo lỗi slow_down.
• Tất cả giao dịch token phải qua HTTPS.
• Mã thiết bị chỉ dùng một lần.

2. Browser OAuth với redirect localhost

Phương pháp phổ biến cho phát triển cục bộ, CLI khởi tạo server HTTP tạm thời lắng nghe trên localhost, mở trình duyệt để người dùng đăng nhập. Trình duyệt sẽ trả về mã về server cục bộ này.

Công cụ sử dụng: Claude Code, gcloud CLI, Terraform CLI

Cách hoạt động

1. Chạy cli login
2. CLI khởi động server HTTP localhost trên cổng ngẫu nhiên (ví dụ: http://127.0.0.1:8742)
3. Mở trình duyệt đến trang xác thực với redirect URI là địa chỉ localhost trên
4. Người dùng đăng nhập, xác thực
5. Server xác thực redirect với mã code và state về localhost
6. CLI nhận mã, trao đổi lấy token
7. Trình duyệt báo thành công và đóng tab

Khi nào không hiệu quả

Không sử dụng được khi không thể mở trình duyệt hoặc bind địa chỉ localhost, ví dụ:

• Phiên SSH từ xa
• Docker container không forwarding cổng
• Môi trường CI/CD không có giao diện
• Máy chủ headless, môi trường doanh nghiệp giới hạn

3 lỗi bảo mật thường gặp

• Binding server callback ra 0.0.0.0 thay vì 127.0.0.1 khiến dữ liệu bị nghe lén mạng nội bộ.
• Thiếu kiểm tra tham số state để tránh CSRF.
• Không dùng PKCE khiến mã xác thực bị đánh cắp và tái sử dụng.

3. PKCE Authorization Code Flow

PKCE (Proof Key for Code Exchange) là bổ sung bảo mật cho OAuth authorization code flow bằng cách thêm mã chứng minh rằng người trao đổi token chính là người bắt đầu xác thực.

Đã áp dụng: AWS CLI v2.22+ cho SSO

Tại sao quan trọng?

Nếu không dùng PKCE, kẻ xấu chặn được mã xác thực có thể đổi lấy token hợp lệ. PKCE ngăn chặn bằng cách yêu cầu token exchange có kèm giá trị chứng minh (code_verifier).

Các bước bổ sung:

1. CLI tạo code_verifier
2. Tạo code_challenge bằng hàm băm SHA-256 của code_verifier
3. Gửi code_challenge lúc bắt đầu xác thực
4. Khi trao đổi token, gửi lại code_verifier
5. Server xác minh tính hợp lệ

PKCE và Device Code Flow

PKCE vượt trội khi có thể mở trình duyệt cùng máy. Device code flow là lựa chọn cho môi trường không thể mở trình duyệt tại chỗ.

4. API Keys và Personal Access Tokens (PAT)

Cách đơn giản: người dùng tạo khóa trên giao diện web rồi nhập vào CLI.

Dùng phổ biến bởi: Stripe CLI, npm, pip, các công cụ AI như Claude Code, OpenAI Codex

Cách dùng

• Truy cập trang quản lý API keys
• Tạo và sao chép mã khóa dài, ngẫu nhiên
• Lưu vào file config hoặc biến môi trường
• CLI dùng token này để chứng thực API requests

Ưu điểm

• Dễ tích hợp cho automation, CI/CD, script, cron job, không cần tương tác người dùng.
• Tiện lợi cho AI agent gọi API.

Rủi ro

• Khóa dễ bị lộ: bị commit git, log, báo cáo lỗi.
• Thường cấp quyền quá rộng (overprivileged).
• Không hỗ trợ MFA.
• Khó xoay khóa; phải cập nhật nhiều nơi.

Giải pháp hiện đại

Trao đổi khóa dài hạn lấy token ngắn hạn (ví dụ AWS STS). Giảm thiểu thiệt hại nếu khóa lâu dài bị lộ.

5. Client Credentials Flow

Phương thức OAuth cho xác thực máy-máy, không có người dùng.

Ứng dụng: CI/CD pipeline, dịch vụ backend, bot tự động.

Cách hoạt động

Gửi client_id và client_secret để lấy token truy cập mà không cần trình duyệt hay tương tác người dùng.

Khi nào dùng

• Khi dịch vụ hoặc bot cần quyền truy cập API.
• CI/CD không có người xác thực.
• Không dùng cho xác thực người dùng, vì không hỗ trợ MFA hay SSO.

Các CLI phổ biến sử dụng phương pháp nào?

Công cụ	Xác thực mặc định	Tùy chọn dự phòng	Nơi lưu token
GitHub CLI (gh)	Device code flow qua browser	PAT, biến môi trường	OS keychain (fallback: plaintext)
AWS CLI v2	PKCE (SSO)	Device code, file credential	~/.aws/sso/cache/
Azure CLI (az)	WAM trên Windows, OAuth browser	Device code	~/.azure/msal_token_cache.*
Vercel CLI	Device code flow (mới)	API token	~/.local/share/com.vercel.cli/auth.json
Stripe CLI	Browser pairing flow	API key	~/.config/stripe/config.toml
gcloud CLI	Browser OAuth	--no-browser flow	~/.config/gcloud/
Claude Code	Browser OAuth	API key	OS keychain / ~/.claude/.credentials.json
OpenAI Codex CLI	Browser OAuth	Device code beta, API key	~/.codex/auth.json / OS keyring
Terraform CLI	Browser OAuth	Token nhập tay	~/.terraform.d/credentials.tfrc.json

Xu hướng rõ ràng: cho người dùng cục bộ, browser OAuth + PKCE là chuẩn; device code flow làm fallback cho headless; API keys cho tự động hóa.

Lưu trữ token: làm đúng – tránh sai

• Nên dùng: Các khoá bảo mật của OS (Keychain trên macOS, Credential Manager Windows, GNOME Keyring Linux).
• Dự phòng: File cấu hình mã hóa với quyền hạn chặt chẽ (chmod 600).
• Tránh: File plaintext, biến môi trường lâu dài trên máy dev, hoặc localStorage trình duyệt.

Quản lý vòng đời token

• Access token: nên ngắn hạn (~1 giờ), tự động làm mới.
• Refresh token: dài hạn, giữ bảo mật cao, xoay vòng mỗi lần dùng để tránh lộ.
• Nếu token hết hạn, CLI phải tự refresh, không nên bắt người dùng login lại ngay.

Những sai lầm phổ biến

• Bind server callback vào 0.0.0.0 thay vì 127.0.0.1.
• Log trực tiếp token ra log file hoặc console.
• Nhúng token vào ảnh Docker — dễ bị lộ khi phân phối.
• Không xử lý token hết hạn, gây lỗi.
• Xin mức quyền quá lớn so với nhu cầu (vi phạm nguyên tắc tối thiểu đặc quyền).

Ứng dụng AI và xác thực CLI

Năm 2026 khác biệt lớn so với trước: AI agent (Claude Code, Codex, Cursor) gọi CLI tự động, không đơn thuần là người dùng gõ lệnh.

Thách thức:

• Phân quyền đại diện: AI agent không nên có tất cả quyền cá nhân của người dùng.
• Lộ thông tin: API key nằm trong biến môi trường có thể bị agent con đọc.
• Xác thực headless: Device code và API key là lựa chọn chính.
• Theo dõi truy xuất: Audit log hiện chưa phân biệt được thao tác của người hay agent đại diện.

Khuyến nghị:

• Dùng token với quyền giới hạn.
• Ưu tiên token ngắn hạn.
• Phân biệt rõ credential riêng cho agent.
• Giám sát API bất thường.

Khung quyết định chọn phương pháp xác thực

• Người dùng là nhà phát triển trên máy cục bộ → Browser OAuth + PKCE
• Cần chạy trên SSH, container, môi trường headless → Device code flow fallback
• CI/CD không có người → Client credentials hoặc API keys có scope rõ ràng
• Ưu tiên nhanh, đơn giản → API keys + xoay token (token rotation)
• Doanh nghiệp cần SSO, MFA → Các OAuth flow hỗ trợ chuẩn doanh nghiệp
• AI agents sử dụng → API keys cho agent + browser OAuth cho người dùng

Câu hỏi thường gặp

Device code flow có an toàn?
An toàn với hầu hết các tấn công nhưng có rủi ro phishing đã được chứng minh. Nên cân nhắc dùng PKCE nếu có thể.

Có nên lưu token trong biến môi trường?
Có thể dùng cho CI/CD nhưng không khuyến nghị trên máy dev do dễ bị lộ.

Khác biệt giữa API key và PAT?
Thực chất gần giống, thường là vấn đề tổ chức và điểm sử dụng.

Bao lâu nên xoay khóa?
Access token thì tự refresh theo quy trình, API keys nên xoay tối thiểu mỗi 90 ngày hoặc ngay khi nghi ngờ bị lộ.

Xác thực trong Docker thế nào?
Ưu tiên dùng device code flow hoặc truyền biến môi trường runtime, không nhúng chìa khóa vào image.

MCP (Model Context Protocol) là gì?
Chuẩn kết nối AI agent tới công cụ/ dịch vụ ngoài, hiện đang dần hoàn thiện và dùng OAuth hoặc API key.

---

Xác thực CLI đang phát triển nhanh chóng. Những cách tốt nhất cách đây vài năm đang dần bị thay thế. Nếu bạn phát triển CLI hôm nay, hãy ưu tiên browser OAuth + PKCE cho người dùng, API keys cho tự động hóa, và chuẩn bị cho tương lai với AI agent sẽ là người dùng chính của bạn.