Authorization — OAuth 2.0, JWT, API Key, Basic

Mở đầu — vì sao bài này quan trọng

Nếu bạn từng gửi một request trong Postman và nhận về 401 Unauthorized hay 403 Forbidden, thì bạn đã chạm vào chủ đề quan trọng nhất của bài này: Authorization — cơ chế mà API dùng để xác định "bạn là ai" và "bạn được phép làm gì".

Trong thực tế công việc QA, có một sự thật hơi phũ phàng: phần lớn thời gian bạn debug một API test thất bại không phải vì logic sai, mà vì auth sai. Token hết hạn, đặt nhầm header, quên prefix Bearer, hoặc dùng nhầm credentials của môi trường staging cho production — tất cả đều dẫn tới 401. Một kỹ sư QA giỏi phải nắm chắc các loại auth để khi thấy 401, đầu tiên nghĩ ngay đến auth thay vì đi soi payload.

Bài này tập trung riêng vào các loại authorization mà Postman hỗ trợ và cách cấu hình chúng đúng cách: No Auth, API Key, Basic Auth, Bearer Token, JWT và OAuth 2.0. Bạn sẽ hiểu bản chất từng loại, khi nào dùng loại nào, và cách Postman giúp bạn quản lý chúng ở cấp collection để không phải dán token thủ công vào từng request. Đây là kiến thức nền tảng mà mọi API tester đều phải thành thạo trước khi bước sang các kỹ thuật nâng cao như chained requests hay CI/CD.

Khái niệm cốt lõi

Authentication vs Authorization — hai khái niệm dễ lẫn

Nhiều bạn dùng lẫn lộn hai từ này. Authentication (xác thực) trả lời câu hỏi "Bạn có đúng là người bạn nói không?" — như việc bạn đưa CMND ở sân bay. Authorization (phân quyền) trả lời "Với danh tính đó, bạn được phép làm gì?" — như việc vé của bạn cho phép vào phòng chờ hạng thương gia hay không.

Trong Postman, tab Authorization thực chất giúp bạn gắn thông tin xác thực (credentials) vào request để server vừa xác thực vừa phân quyền. Postman không tự "hiểu" phân quyền — nó chỉ giúp bạn đóng gói credentials đúng chuẩn để gửi đi.

Postman gắn auth vào request như thế nào

Điểm mấu chốt: dù bạn chọn loại auth nào ở tab Authorization, cuối cùng Postman đều dịch nó thành header hoặc query parameter thực sự trong request HTTP. Ví dụ chọn Bearer Token thì Postman tự thêm header Authorization: Bearer <token>. Bạn có thể kiểm chứng bằng nút Code (biểu tượng </>) bên phải request — nó hiện ra request HTTP thô mà Postman sẽ gửi.

Auth có thể được đặt ở ba cấp độ, và cấp con có thể kế thừa (inherit) từ cấp cha:

• Cấp Collection — đặt một lần, mọi request bên trong kế thừa. Đây là cách làm chuẩn cho một API dùng chung một cơ chế auth.
• Cấp Folder — override cho một nhóm request cụ thể.
• Cấp Request — override cho một request riêng lẻ.

Tùy chọn "Inherit auth from parent" ở mỗi request chính là cơ chế kế thừa này. Nắm được nó bạn sẽ tiết kiệm hàng giờ so với việc dán token vào từng request.

Bảng các loại auth và use case

API Key

Đây là loại đơn giản nhất: server cấp cho bạn một chuỗi bí mật, bạn gửi kèm mỗi request. Postman cho chọn gửi qua Header (ví dụ X-API-Key: abc123) hoặc Query Params (ví dụ ?api_key=abc123). Ưu tiên header vì query param dễ bị lộ trong log server và lịch sử trình duyệt.

Basic Auth

Bạn nhập username + password, Postman ghép chúng thành username:password, mã hóa Base64 rồi đặt vào header Authorization: Basic <chuỗi_base64>. Lưu ý cực kỳ quan trọng: Base64 là encoding, KHÔNG phải mã hóa. Ai bắt được request đều decode ngược ra password trong một giây. Vì vậy Basic Auth chỉ an toàn khi đi cùng HTTPS.

Bearer Token & JWT

Bearer nghĩa là "người mang" — ai cầm token này thì server tin người đó, không hỏi thêm. Bạn dán token vào, Postman gắn Authorization: Bearer <token>. JWT (JSON Web Token) là một định dạng token phổ biến, gồm 3 phần ngăn bởi dấu chấm: header.payload.signature. Phần payload chứa thông tin như user id, role, và thời điểm hết hạn (exp). Điểm hay: bạn có thể copy JWT dán vào trang jwt.io để đọc payload — hữu ích khi debug xem token đã hết hạn chưa hay thiếu quyền gì.

OAuth 2.0

Đây là loại phức tạp nhất nhưng phổ biến nhất ở doanh nghiệp lớn. Thay vì đưa thẳng token, bạn trải qua một flow (luồng ủy quyền) để đổi lấy access token. Postman hỗ trợ sẵn nhiều grant type: Authorization Code (dùng cho web app có người dùng đăng nhập), Client Credentials (server-to-server, không có người dùng), Password Credentials, v.v. Postman có nút "Get New Access Token" — bạn điền các thông số (auth URL, token URL, client id, client secret, scope), Postman tự chạy flow và lấy token về, thậm chí tự động refresh khi hết hạn.

Tình huống thực tế

Ví dụ 1 — Tiki và cái bẫy token hết hạn

Chị Lan là QA tại một sàn thương mại điện tử lớn ở TP.HCM (giả định theo mô hình Tiki). Team dùng Bearer Token cấp bởi hệ thống đăng nhập nội bộ, và token có thời hạn 15 phút. Chị dán token vào biến collection {{access_token}} và chạy bộ 40 test case đặt hàng.

Vấn đề: bộ test chạy mất khoảng 12 phút, nhưng chị hay dừng lại giữa chừng để debug. Khi quay lại chạy tiếp, token đã quá 15 phút, và một loạt test từ case số 25 trở đi báo 401. Chị mất gần một buổi nghi ngờ logic test có bug, trong khi thủ phạm chỉ là token hết hạn.

Bài học: với API dùng token ngắn hạn, đừng dán token cứng. Hãy tạo một request "Login" riêng, đặt ở đầu collection, dùng Tests script để lưu token vào biến environment. Khi cần chạy lại, chỉ việc chạy request Login trước. Ở các bài sau bạn sẽ học cách chain tự động, nhưng ngay bây giờ chỉ cần hiểu: token là thứ sống có thời hạn, không phải hằng số.

Ví dụ 2 — VNG và OAuth 2.0 Client Credentials

Một nhóm tích hợp tại VNG cần test API nội bộ giao tiếp giữa hai service (service-to-service), không có người dùng cuối đăng nhập. Đây là kịch bản kinh điển của grant type Client Credentials. Bạn QA được cấp client_id và client_secret, cùng một token_url.

Trong Postman, bạn chọn Type = OAuth 2.0, Grant Type = Client Credentials, điền token URL, client id, client secret, scope (ví dụ read:orders), rồi bấm Get New Access Token. Postman gọi token endpoint, nhận về access token và lưu lại. Từ đó mọi request kế thừa auth này sẽ tự động mang token.

Cái bẫy ở đây: bạn QA lần đầu quên điền scope, nên token lấy về hợp lệ nhưng khi gọi endpoint orders lại nhận 403 Forbidden. 401 là "tôi không biết bạn"; 403 là "tôi biết bạn nhưng bạn không có quyền". Phân biệt được hai mã này giúp bạn khoanh vùng lỗi trong vài giây thay vì vài giờ.

Bài học: OAuth 2.0 không chỉ là "lấy được token". Scope quyết định token đó làm được gì. Khi gặp 403 dù token hợp lệ, hãy nghi ngờ scope trước tiên.

Ví dụ 3 — Shopee sandbox và API Key đặt sai chỗ

Anh Minh test tích hợp một cổng đối tác kiểu Shopee Open Platform. Tài liệu ghi API key phải đặt ở header X-API-Key. Anh vô tình cấu hình Postman gửi key qua query param (?api_key=...). Kết quả: server bỏ qua, trả 401.

Anh mất thời gian vì tưởng key bị sai. Chỉ khi dùng nút Code xem request thô, anh mới thấy key nằm ở URL chứ không phải header. Đổi sang "Add to: Header" là xong.

Bài học: với API Key, nơi đặt key quan trọng ngang với giá trị key. Luôn đọc kỹ tài liệu API xem key phải nằm ở header nào (tên chính xác, phân biệt hoa thường) hay query param nào. Và luôn dùng nút Code để xác minh request thực sự được gửi đi thế nào.

Hướng dẫn từng bước

Ta sẽ cấu hình OAuth-free Bearer Token ở cấp collection — kịch bản phổ biến nhất trong công việc thực tế.

Bước 1 — Đặt auth ở cấp Collection. Nhấn vào tên collection ở sidebar, chọn tab Authorization. Đây là nơi đặt auth dùng chung để mọi request kế thừa.

Bước 2 — Chọn Type = Bearer Token. Trong ô Token, đừng dán token cứng. Thay vào đó gõ biến: {{access_token}}. Việc này giúp bạn thay token một chỗ mà toàn bộ collection cập nhật theo.

Bước 3 — Tạo request Login để lấy token. Tạo một request POST {{base_url}}/auth/login với body chứa username/password. Ở tab Tests của request này, viết script lưu token:

// Lưu token trả về vào biến environment
const res = pm.response.json();
pm.environment.set("access_token", res.access_token);
pm.test("Login thành công, có token", () => {
  pm.expect(res.access_token).to.be.a("string").and.not.empty;
});

Bước 4 — Đặt các request khác thành "Inherit auth from parent". Mở một request bất kỳ, vào tab Authorization, chọn Type = Inherit auth from parent. Nó sẽ dùng Bearer Token của collection với biến {{access_token}} bạn vừa lưu.

Bước 5 — Chạy Login trước, rồi chạy các request khác. Sau khi Login chạy xong, biến access_token đã có giá trị. Mọi request kế thừa sẽ tự động mang header Authorization: Bearer <token thực>.

Bước 6 — Xác minh bằng nút Code. Bấm biểu tượng </> bên phải, chọn ngôn ngữ cURL, kiểm tra header Authorization đã đúng chưa. Đây là thói quen vàng để chắc chắn Postman gửi đúng thứ bạn nghĩ.

Với OAuth 2.0, thay Bước 3 bằng việc điền cấu hình trong chính tab Authorization và bấm Get New Access Token; Postman sẽ tự lưu token vào request/collection.

Lỗi thường gặp & mẹo

Quên prefix Bearer. Nếu bạn tự thêm header thủ công và ghi Authorization: <token> mà thiếu chữ Bearer phía trước, server sẽ từ chối. Chọn Type = Bearer Token để Postman tự thêm cho đúng.

Dán cả chữ "Bearer" vào ô Token. Ngược lại, khi dùng Type = Bearer Token, ô Token chỉ điền token trần, đừng gõ Bearer eyJ.... Nếu không Postman sẽ tạo ra Authorization: Bearer Bearer eyJ....

Nhầm 401 và 403. 401 = chưa xác thực (token sai/thiếu/hết hạn). 403 = đã xác thực nhưng thiếu quyền (thường là thiếu scope hoặc role). Ghi nhớ điều này giúp bạn khoanh vùng lỗi tức thì.

Token hết hạn giữa buổi test. Với token ngắn hạn, luôn có request Login lấy token mới; đừng dán token cứng vào biến.

Base64 tưởng là an toàn. Basic Auth chỉ encode chứ không mã hóa. Không bao giờ dùng Basic Auth trên HTTP thường; luôn phải HTTPS.

Rò rỉ secret qua export. Khi bạn export collection để chia sẻ, các biến chứa token/secret có thể bị lộ. Hãy dùng environment variables và đặt biến nhạy cảm là kiểu secret (Postman ẩn giá trị), tuyệt đối không hard-code client_secret trong request. Ở bài Postman Vault sau này bạn sẽ học cách quản lý secret an toàn hơn nữa.

Sai môi trường. Dùng nhầm token của staging cho production (hoặc ngược lại) là lỗi kinh điển. Luôn kiểm tra environment đang chọn ở góc trên phải trước khi gửi.

Mẹo debug số một: khi gặp lỗi auth, mở nút Code xem request thô. 90% trường hợp bạn sẽ thấy ngay header sai, thiếu prefix, hoặc key đặt nhầm chỗ.

Bài tập thực hành

• API Key: Dùng một API public có yêu cầu key (ví dụ OpenWeatherMap). Cấu hình gửi key một lần qua query param, một lần qua header. Dùng nút Code để so sánh hai request thô. Ghi lại khác biệt.

• Basic Auth và Base64: Dùng endpoint test https://postman-echo.com/basic-auth (user: postman, pass: password). Cấu hình Basic Auth và gửi thành công. Sau đó copy header Authorization ra, tự decode Base64 (dùng jwt.io hoặc lệnh echo <chuỗi> | base64 -d) để tự chứng minh password lộ ra thế nào.

• Bearer + Inherit: Tạo collection với auth cấp collection = Bearer Token {{access_token}}. Tạo một request Login (có thể mock bằng postman-echo) lưu token vào environment qua Tests script. Đặt 2 request khác ở chế độ Inherit và xác minh chúng mang đúng token.

• Phân biệt lỗi: Cố tình gửi request với token sai để nhận 401, và (nếu có API phù hợp) gửi với token đúng nhưng thiếu quyền để nhận 403. Viết một câu ngắn giải thích bạn sẽ debug mỗi loại thế nào.

• JWT reading: Lấy một JWT bất kỳ (từ jwt.io có sẵn mẫu), dán vào jwt.io, đọc trường exp và role trong payload. Trả lời: token này còn hạn không, và nó cho quyền gì?

Tóm tắt

• Authorization là cơ chế API xác định bạn là ai và được làm gì; auth sai là nguyên nhân số một của lỗi test API.
• Postman hỗ trợ nhiều loại: No Auth, API Key, Basic Auth, Bearer Token, JWT, OAuth 2.0 — nhưng cuối cùng tất cả đều được dịch thành header hoặc query param.
• Auth đặt được ở ba cấp (Collection / Folder / Request); dùng Inherit auth from parent để cấu hình một lần và tái sử dụng.
• API Key: quan trọng cả giá trị lẫn nơi đặt (header hay query). Basic Auth: chỉ encode Base64, phải đi cùng HTTPS. Bearer/JWT: token sống có thời hạn, đừng hard-code. OAuth 2.0: scope quyết định quyền — thiếu scope gây 403.
• Ghi nhớ: 401 = chưa xác thực, 403 = thiếu quyền. Và luôn dùng nút Code để xác minh request thô khi debug auth.

Nắm chắc bài này, bạn đã có nền tảng để bước sang Chained Requests và các kịch bản CI/CD nơi token phải được lấy và làm mới hoàn toàn tự động.