Sebastian Petrus

Posted on Aug 31 Originally published at apidog.com

Cách kiểm thử API OAuth 2.0 trong Apidog (Authorization Code, Client Credentials, và Token Refresh)

Mọi nhóm API đều gặp phải cùng một vấn đề: các endpoint hoạt động độc lập, cho đến khi OAuth 2.0 được bật và một nửa bộ test bắt đầu trả về lỗi 401. Khi đó, việc xử lý authorization server, access token có thời hạn ngắn, scope và sao chép token thủ công từ phản hồi curl vào header nhanh chóng trở nên nhàm chán.

Dùng thử Apidog hôm nay

Giải pháp không phải là bỏ qua xác thực trong test. Hãy biến việc xử lý token thành một phần của thiết lập kiểm thử để loại bỏ thao tác thủ công.

Hướng dẫn này tập trung vào hai flow phổ biến:

Authorization Code với PKCE cho API hoạt động thay mặt người dùng.
Client Credentials cho các cuộc gọi máy-đến-máy.

Nếu cần tổng quan về tất cả loại grant trước khi bắt đầu, hãy xem tổng quan về các flow OAuth 2.0.

Hai flow OAuth 2.0 quan trọng khi kiểm thử API

OAuth 2.0 định nghĩa nhiều loại grant, nhưng phần lớn hoạt động kiểm thử API hằng ngày xoay quanh một câu hỏi:

API đang hoạt động thay mặt người dùng hay thay mặt một dịch vụ?

Authorization Code với PKCE

Authorization Code là flow tiêu chuẩn để lấy token gắn với người dùng:

Client chuyển người dùng đến authorization server.
Người dùng đăng nhập và chấp thuận.
Authorization server redirect về client cùng một authorization code dùng một lần.
Client đổi code lấy access token tại token endpoint.

Toàn bộ quy trình được định nghĩa trong RFC 6749, phần 4.1.

PKCE (Proof Key for Code Exchange) bổ sung một lớp bảo vệ cho bước trao đổi code:

Client tạo một code_verifier ngẫu nhiên.
Client gửi code_challenge đã băm trong authorization request.
Khi đổi code, client chứng minh rằng mình sở hữu code_verifier ban đầu.

Nhờ vậy, kẻ tấn công chặn được authorization code cũng không thể sử dụng nó. PKCE ban đầu được thiết kế cho ứng dụng di động, nhưng hướng dẫn hiện tại từ oauth.net khuyến nghị dùng PKCE cho mọi Authorization Code flow, kể cả confidential client.

Hãy dùng flow này khi hành vi của endpoint phụ thuộc vào danh tính người dùng, chẳng hạn:

GET /orders chỉ trả về đơn hàng của người gọi.
Endpoint quản trị giới hạn theo vai trò.
Rate limit được áp dụng theo từng người dùng.

Client Credentials

Client Credentials loại bỏ hoàn toàn người dùng. Client xác thực bằng ID và secret của chính mình để nhận token đại diện cho ứng dụng:

curl -X POST https://auth.example.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=orders_service \
  -d [REDACTED CREDENTIAL] \
  -d scope="orders:read orders:write"

Đây là flow dành cho:

Microservice nội bộ.
Cron job.
Pipeline CI gọi deployment API.
Bộ test tự động không cần tương tác với trình duyệt.

Nếu môi trường test cho phép tạo một client riêng, hãy dùng Client Credentials cho mọi trường hợp không cần kiểm thử danh tính người dùng. Xem thêm Client Credentials OAuth 2.0.

Cấu hình OAuth 2.0 trong Apidog

Apidog hỗ trợ cấu hình OAuth 2.0 trong tab Auth của request hoặc folder. Nền tảng có thể tự động lấy, đính kèm và làm mới token.

Các grant được hỗ trợ gồm:

Authorization Code
Authorization Code (With PKCE)
Client Credentials
Password Credentials
Implicit

Ví dụ dưới đây sử dụng một API quản lý đơn hàng giả lập.

Thiết lập Client Credentials

Mở request hoặc folder, chuyển loại xác thực sang OAuth 2.0, sau đó chọn Client Credentials.

Điền các trường:

Access Token URL: https://auth.example.com/oauth/token
Client ID: orders_service
**Client [REDACTED CREDENTIAL] secret được cấp
Scope: orders:read orders:write trong phần tùy chọn nâng cao

Apidog cho phép gửi client credentials theo hai cách:

Header Basic Auth.
Request body.

Hãy chọn đúng cách mà authorization server yêu cầu. Auth0 và Okta thường chấp nhận cả hai, nhưng một số authorization server nội bộ chỉ phân tích request body.

Nhấn Get Token. Apidog sẽ gọi token endpoint, lưu kết quả và hiển thị token cùng thời hạn. Từ đó, mỗi request sẽ tự động được đính kèm header:

[REDACTED CREDENTIAL] <access_token>

Bạn không cần sao chép token hoặc tự quản lý biến {{token}}.

Thiết lập Authorization Code với PKCE

Để kiểm thử theo ngữ cảnh người dùng, chọn Authorization Code (With PKCE) làm grant type. Trong Apidog, PKCE là một grant riêng chứ không phải checkbox.

Các trường cần điền:

Authorization URL: https://auth.example.com/oauth/authorize
Access Token URL: https://auth.example.com/oauth/token
Callback URL: redirect URI đã đăng ký với provider
**Client ID và Client [REDACTED CREDENTIAL] lấy từ OAuth app đã đăng ký

Nhấn Get Token. Apidog sẽ mở cửa sổ trình duyệt đến trang đăng nhập. Đăng nhập bằng test user, chấp thuận consent screen, rồi token sẽ được lưu trong cùng cơ chế quản lý như Client Credentials.

Nếu provider trả về cả OpenID Connect ID token, tùy chọn Token Type Used cho phép chọn loại token được đính kèm. Điều này hữu ích khi API đang kiểm thử xác thực ID token thay vì access token.

Nên tạo một test user riêng cho mỗi vai trò cần kiểm thử, chẳng hạn:

Người mua.
Quản trị viên.
Kiểm toán viên chỉ đọc.

Lấy token cho từng user rồi chạy lại cùng một kịch bản là cách nhanh để xác minh access control theo vai trò.

Tái sử dụng và tự động làm mới token

Access token thường hết hạn sau khoảng một giờ. Nếu không tự động xử lý, token hết hạn sẽ làm test thất bại và buộc bạn lấy token thủ công.

Theo bản cập nhật tháng Sáu của Apidog, Apidog có thể tự động làm mới OAuth 2.0 token khi authorization server cấp refresh token.

Khi access token đã lưu hết hạn, Apidog sẽ:

Dùng refresh token để lấy token mới.
Thay thế token cũ.
Gửi request với token mới.

Nếu provider dùng refresh endpoint riêng, bạn có thể cấu hình Custom Refresh Token URL trong phần tùy chọn nâng cao.

Với Client Credentials, nhiều authorization server không cấp refresh token vì client có thể xác thực lại bất kỳ lúc nào. Trong trường hợp đó:

Nhấn Get Token để lấy token mới.
Trong CI hoặc scheduled run, yêu cầu token mới ở đầu mỗi lần chạy.

Kế thừa xác thực ở cấp folder

Cấu hình OAuth cho từng request riêng lẻ là không hiệu quả. Apidog cho phép đặt xác thực ở cấp folder để các request bên trong tự động kế thừa cấu hình của folder cha.

Ví dụ, đặt OAuth 2.0 trên folder Orders API. Mọi request bên dưới, kể cả request mới do đồng đội thêm vào sprint sau, sẽ dùng cùng một token được quản lý tập trung.

Điều này đặc biệt hữu ích với test nhiều bước:

POST /carts
POST /carts/{id}/items
POST /orders

Cả ba bước sẽ dùng chung:

Một cấu hình OAuth.
Một token được quản lý.
Cơ chế refresh tự động.

Khi client secret thay đổi, bạn chỉ cần cập nhật folder thay vì hàng chục request.

Request con vẫn có thể ghi đè cấu hình của folder cha. Đây là cách phù hợp để tạo negative test cho token và scope.

Kiểm thử các đường dẫn lỗi

Test happy path chứng minh token flow hoạt động. Negative test chứng minh API thực sự thực thi xác thực và phân quyền.

Để ôn lại sự khác biệt giữa các loại token, xem API key và Bearer [REDACTED].

Token hết hạn hoặc bị thiếu: kỳ vọng 401

Sao chép một request trong kịch bản rồi ghi đè xác thực kế thừa bằng:

Không có authentication.
Bearer [REDACTED] hard-code đã hết hạn, chẳng hạn Bearer [REDACTED].

Kiểm tra:

Status code là 401.
Response có header WWW-Authenticate, theo yêu cầu của RFC 6750.
Response body không làm lộ stack trace hoặc hostname nội bộ.

Trả về 200 trong trường hợp này là lỗi nghiêm trọng. Trả về 403 là dấu hiệu thiết kế cần xem xét: server nên phân biệt “không biết bạn là ai” với “biết bạn là ai nhưng không cho phép”.

Scope không đủ: kỳ vọng 403

Tạo một test client khác chỉ có scope orders:read, lấy token của client đó rồi gọi endpoint ghi:

POST /orders

Kiểm tra:

Status code là 403.
Nếu API tuân theo RFC 6750, header WWW-Authenticate có error="insufficient_scope".

Test này giúp phát hiện lỗi phổ biến khi gateway kiểm tra scope ở một số route nhưng bỏ sót các route khác. Nếu scope còn mới với đội ngũ của bạn, hãy xem giải thích về OAuth 2.0 scopes.

Client không hợp lệ: kiểm tra lỗi rõ ràng từ token endpoint

Gửi request trực tiếp đến:

https://auth.example.com/oauth/token

Dùng client_secret giả mạo. Theo RFC 6749, phần 5.2, server nên trả về 400 hoặc 401 nếu client authentication thất bại, cùng JSON body:

{
  "error": "invalid_client"
}

Hãy kiểm tra cả status code và trường error. Authorization server cũng là một API, vì vậy error contract của nó là một phần trong bề mặt cần kiểm thử.

Kiểm tra token endpoint trong test scenario

Ngoài negative test cho client không hợp lệ, token endpoint nên được kiểm thử riêng. Gọi trực tiếp endpoint rồi thêm các assertion sau:

access_token tồn tại và không rỗng.
token_type là bearer, không phân biệt hoa thường.
expires_in lớn hơn 0 và nằm trong chính sách, chẳng hạn không vượt quá 3600.
scope khớp với scope đã yêu cầu, để phát hiện server âm thầm thu hẹp quyền.

Apidog cho phép thêm các assertion trực quan trên JSON response mà không cần viết script. Bạn cũng có thể trích xuất access_token vào biến để dùng ở bước tiếp theo, phù hợp khi muốn kiểm thử raw token exchange thay vì cơ chế OAuth được quản lý.

Đưa scenario này vào CI. Khi authorization server hoạt động sai, build sẽ thất bại ngay thay vì chỉ xuất hiện dưới dạng lỗi 401 khó truy vết trong môi trường production.

Quy trình đề xuất

Một quy trình OAuth 2.0 hoàn chỉnh gồm:

Cấu hình OAuth ở cấp folder cho happy path.
Dùng Authorization Code với PKCE cho các API phụ thuộc danh tính người dùng.
Dùng Client Credentials cho các API máy-đến-máy.
Ghi đè authentication ở từng request cho test 401 và 403.
Kiểm thử riêng token endpoint.
Bật refresh token tự động khi provider hỗ trợ.
Chạy toàn bộ scenario trong CI.

Bạn có thể tải Apidog và dùng thử miễn phí. OAuth 2.0 hoạt động trên gói miễn phí, vì vậy bạn có thể kết nối đến token endpoint của mình trong vài phút.

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

Nên dùng OAuth flow nào để kiểm thử API?

Dùng Client Credentials cho các API máy-đến-máy và phần lớn automation vì flow này không cần tương tác với trình duyệt.

Dùng Authorization Code với PKCE khi test phụ thuộc vào danh tính người dùng, chẳng hạn:

Cách ly dữ liệu theo user.
Kiểm tra role.
Kiểm tra consent behavior.

Tránh Implicit và Password Credentials trong các kế hoạch test mới; cả hai đều không được khuyến khích trong hướng dẫn OAuth hiện tại.

Làm cách nào để tự động làm mới token hết hạn trong Apidog?

Cấu hình OAuth 2.0 trong tab Auth rồi nhấn Get Token. Khi authorization server trả về refresh token, Apidog sẽ tự động làm mới access token khi token cũ hết hạn.

Nếu provider dùng refresh endpoint riêng, hãy cấu hình URL đó trong phần tùy chọn nâng cao. Với Client Credentials không có refresh token, chạy lại Get Token để nhận token mới.

Mọi request trong một scenario có thể dùng chung OAuth token không?

Có. Đặt cấu hình OAuth 2.0 trên folder cha để các request bên trong kế thừa cùng một token được quản lý.

Từng request vẫn có thể ghi đè cấu hình folder. Đây là cách đưa negative test như token hết hạn hoặc scope không đủ vào cùng một scenario.

401 và 403 có ý nghĩa gì trong OAuth API?

401: Xác thực thất bại — token bị thiếu, hết hạn hoặc không hợp lệ.
403: Token hợp lệ nhưng không đủ quyền, chẳng hạn thiếu scope.

Phân biệt đúng hai mã này rất quan trọng. Client thường cần xác thực lại khi nhận 401, nhưng nên dừng lại khi nhận 403. Xem thêm hướng dẫn kiểm thử JWT authentication.

DEV Community