Zalo OAuth 2.0 là cơ chế ủy quyền giúp website, ứng dụng di động hoặc hệ thống doanh nghiệp truy cập tài nguyên Zalo mà không cần giữ mật khẩu của người dùng. Ứng dụng chuyển người dùng sang màn hình cấp quyền của Zalo, nhận một mã ngắn hạn rồi đổi mã đó lấy token để gọi API.
Phần quan trọng không chỉ là tạo nút đăng nhập. Một tích hợp ổn định còn phải kiểm tra callback, chống giả mạo yêu cầu, lưu token an toàn, làm mới token đúng lúc và xử lý trường hợp người dùng thu hồi quyền. Bài viết dưới đây giải thích luồng authorization code, cách lấy access token và refresh token, phạm vi quyền, bảo mật cùng những lỗi thường gặp.
Nội dung chính
Zalo OAuth 2.0 là gì và được dùng khi nào?
Zalo OAuth 2.0 hoạt động theo mô hình ủy quyền bằng token. Người dùng hoặc quản trị viên OA chấp thuận cho một ứng dụng thực hiện một số hành động nhất định. Zalo sau đó cấp token đại diện cho quyền đã được đồng ý, còn mật khẩu vẫn chỉ được nhập trên hệ thống của Zalo.
Zalo OAuth 2.0 chủ yếu trả lời câu hỏi “ứng dụng được phép truy cập tài nguyên nào”, không đồng nghĩa với xác thực danh tính theo OpenID Connect. Dữ liệu người dùng hoặc OA vẫn phải được lấy qua API tương ứng bằng token hợp lệ.
Bốn thành phần chính gồm người sở hữu tài nguyên, ứng dụng khách, máy chủ ủy quyền và Zalo API. Ứng dụng khách có thể là backend website, ứng dụng di động, CRM hoặc hệ thống quản trị OA.
Các trường hợp phổ biến gồm đăng nhập bằng Zalo, lấy dữ liệu người dùng, kết nối OA với CRM hoặc tự động hóa nghiệp vụ. Cần phân biệt User Access Token của Social API với OA Access Token của Official Account API; hai loại không dùng thay cho nhau.
| Thành phần | Vai trò |
|---|---|
| Người dùng hoặc quản trị viên OA | Đăng nhập và cấp quyền |
| Ứng dụng | Tạo yêu cầu, nhận callback, quản lý token |
| Máy chủ OAuth của Zalo | Cấp code, access token và refresh token |
| Zalo API | Kiểm tra token trước khi xử lý yêu cầu |
Zalo OAuth 2.0 sử dụng luồng authorization code trong các tình huống cần người dùng hoặc quản trị viên xác nhận quyền. Trình duyệt chỉ nhận mã ủy quyền dùng một lần; việc đổi mã lấy token nên được thực hiện ở backend để hạn chế lộ thông tin nhạy cảm.
Bước 1: Chuẩn bị ứng dụng và callback
Bạn tạo ứng dụng trên Zalo for Developers, lấy App ID và khai báo redirect URI. Callback phải khớp địa chỉ đã đăng ký. Môi trường production nên dùng HTTPS, tên miền cố định và không tạo callback từ dữ liệu người dùng.
Backend sinh state ngẫu nhiên, lưu theo phiên và đưa vào yêu cầu. Khi Zalo chuyển hướng trở lại, hệ thống phải đối chiếu giá trị nhận được. State giúp chống CSRF và tránh gắn callback sai phiên.
Với SDK hoặc luồng V4 yêu cầu Proof Key for Code Exchange, ứng dụng tạo code_verifier, tính code_challenge và gửi verifier khi đổi code. PKCE làm giảm nguy cơ authorization code bị đánh cắp và sử dụng bởi client khác.
Bước 2: Chuyển người dùng đến trang cấp quyền
URL bắt đầu luồng thường dùng endpoint V4 của Zalo và kèm App ID, callback cùng các tham số cần thiết:
https://oauth.zaloapp.com/v4/permission
?app_id=YOUR_APP_ID
&redirect_uri=https%3A%2F%2Fexample.com%2Fzalo%2Fcallback
&state=RANDOM_STATE
&code_challenge=GENERATED_CHALLENGE
Trong Zalo OAuth 2.0, người dùng đăng nhập trên trang Zalo và xem nội dung quyền ứng dụng yêu cầu. Nếu đồng ý, Zalo chuyển về callback cùng code. Nếu từ chối hoặc phát sinh lỗi, callback có thể nhận tham số lỗi thay vì mã ủy quyền.
Bước 3: Kiểm tra callback
Tại OAuth callback, backend kiểm tra lỗi, xác minh state và chỉ sau đó mới dùng code. Authorization code có thời hạn ngắn, dùng một lần; với luồng OA hiện hành, code có thể hết hiệu lực sau khoảng 10 phút nên cần đổi ngay.
Endpoint token phụ thuộc tích hợp: User Access Token V4 dùng /v4/access_token, còn OA Access Token dùng /v4/oa/access_token. Gọi nhầm endpoint thường khiến code hoặc thông tin ứng dụng bị báo không hợp lệ.
Cách lấy access token và refresh token
Sau khi đổi code thành công, Zalo OAuth 2.0 trả về access token, refresh token, thời gian hiệu lực và một số trường liên quan. Access token được dùng để gọi API nghiệp vụ. Refresh token chỉ gửi đến máy chủ OAuth khi cần xin token mới, không dùng trực tiếp để gọi API dữ liệu.
Ví dụ dưới đây minh họa cách đổi authorization code lấy OA token. Giá trị header và trường request cần được kiểm tra theo tài liệu của đúng sản phẩm đang tích hợp:
curl –request POST
–url https://oauth.zaloapp.com/v4/oa/access_token
–header “Content-Type: application/x-www-form-urlencoded”
–header “secret_key: YOUR_APP_SECRET”
–data-urlencode “app_id=YOUR_APP_ID”
–data-urlencode “grant_type=authorization_code”
–data-urlencode “code=AUTHORIZATION_CODE”
–data-urlencode “code_verifier=YOUR_CODE_VERIFIER”
Zalo OAuth 2.0 yêu cầu hệ thống lưu thời điểm nhận token và tính expires_at từ expires_in, không cố định thời hạn trong mã nguồn. Chính sách OA token và User Access Token khác nhau, vì vậy phải dựa vào phản hồi thực tế của đúng API.
Để làm mới token trong Zalo OAuth 2.0, gửi POST đến endpoint token cùng grant_type=refresh_token và refresh token hiện tại:
curl –request POST
–url https://oauth.zaloapp.com/v4/oa/access_token
–header “Content-Type: application/x-www-form-urlencoded”
–header “secret_key: YOUR_APP_SECRET”
–data-urlencode “app_id=YOUR_APP_ID”
–data-urlencode “grant_type=refresh_token”
–data-urlencode “refresh_token=CURRENT_REFRESH_TOKEN”
Phản hồi có thể chứa access token và refresh token mới. Hãy cập nhật cả hai trong cùng một giao dịch; giữ refresh token cũ có thể làm lần làm mới kế tiếp thất bại.
Nên refresh trước khi access token hết hạn vài phút nhưng vẫn xử lý lỗi token khi gọi API. Nếu nhiều worker cùng refresh, hãy dùng lock hoặc cột phiên bản để tránh sử dụng trùng refresh token và ghi đè kết quả.
Scope và quyền truy cập cần hiểu thế nào?
Trong OAuth, scope biểu diễn phạm vi mà ứng dụng xin truy cập. Với Zalo, quyền thực tế còn phụ thuộc sản phẩm, cấu hình ứng dụng, trạng thái xét duyệt, loại OA, vai trò của người cấp quyền và endpoint được gọi. Có token không có nghĩa ứng dụng được truy cập toàn bộ API.
Khi triển khai Zalo OAuth 2.0, hãy liệt kê chính xác nghiệp vụ cần dùng rồi xác định API và quyền tương ứng. Một hệ thống chỉ đọc thông tin cơ bản không nên xin quyền gửi tin hoặc quản trị nội dung. Nguyên tắc quyền tối thiểu giúp giảm rủi ro, tăng khả năng người dùng chấp thuận và đơn giản hóa quy trình xét duyệt.
Trong Zalo OAuth 2.0, token cần được lưu cùng ngữ cảnh người dùng, OA, App ID và thời điểm cấp. Với OA, hệ thống phải xác nhận đúng tài sản vừa được quản trị viên ủy quyền, tránh kết nối nhầm.
Khi API báo thiếu quyền, không retry liên tục. Hãy ghi log endpoint, mã lỗi, loại token và hướng người dùng cấp quyền lại. Một số thay đổi chỉ có hiệu lực sau khi thực hiện lại luồng chấp thuận.
Bảo mật khi triển khai OAuth với Zalo
Điểm quan trọng nhất của Zalo OAuth 2.0 là giữ bí mật token và App Secret. Secret không được đặt trong JavaScript trình duyệt, mã nguồn ứng dụng di động hoặc kho mã công khai. Việc đổi code, refresh và lưu token nên diễn ra ở backend hoặc dịch vụ bảo mật chuyên trách.
Refresh token là thông tin đăng nhập dài hạn. Hãy mã hóa khi lưu, giới hạn quyền đọc, che token trong log và chỉ cho dịch vụ quản lý token truy cập giá trị gốc.
Không truyền token trong query string vì URL có thể xuất hiện trong lịch sử, log hoặc proxy. Khi gọi API, dùng header đúng quy định, cấu hình timeout và không ghi toàn bộ request header ở production.
Trong Zalo OAuth 2.0, callback phải xác minh state, giới hạn thời gian phiên và xóa code_verifier sau khi sử dụng. Authorization code không được lưu lâu hoặc tái sử dụng. Nếu App Secret hay refresh token bị lộ, cần thay khóa, thu hồi kết nối và yêu cầu cấp quyền lại thay vì chỉ xóa access token.
Mô hình lưu trữ có thể gồm owner_id, token đã mã hóa, expires_at, last_refreshed_at và version. Cột version giúp hạn chế race condition khi refresh.
Lỗi thường gặp và checklist triển khai
Lỗi phổ biến của Zalo OAuth 2.0 là redirect_uri không khớp. Khác HTTP/HTTPS, dấu gạch chéo cuối hoặc subdomain đều có thể khiến yêu cầu bị từ chối. Hãy dùng callback thống nhất cho từng môi trường.
Authorization code không hợp lệ thường do hết hạn, đã dùng hoặc sai code_verifier. Không retry cùng code; hãy hủy phiên và bắt đầu lại luồng cấp quyền.
Lỗi invalid secret key thường do nhầm App Secret, sai header, sai App ID hoặc nhầm endpoint User/OA. Zalo OAuth 2.0 không nên ghi secret đầy đủ vào log khi kiểm tra.
Token hết hạn thường do không lưu expires_in, lịch refresh lỗi hoặc đồng hồ máy chủ sai. Với Zalo OAuth 2.0, hãy refresh chủ động nhưng vẫn xử lý lỗi token khi gọi API.
Refresh có thể thất bại vì giữ token cũ, quyền bị thu hồi, token hết hạn hoặc nhiều worker chạy đồng thời. Khi không thể phục hồi, hãy đánh dấu “cần cấp quyền lại” và dừng job liên quan.
CORS thường cho thấy frontend đang gọi token endpoint trực tiếp. Hãy đổi code và refresh ở backend; frontend chỉ bắt đầu luồng và nhận trạng thái kết nối.
Checklist trước khi đưa vào production:
- App ID, callback và endpoint đúng từng môi trường.
- Secret chỉ nằm trong secret manager hoặc biến môi trường backend.
statengẫu nhiên, dùng một lần và gắn với session.- PKCE được áp dụng khi SDK hoặc luồng V4 yêu cầu.
- Token được mã hóa và không xuất hiện trong log.
expires_atđược tính từ phản hồi thực tế.- Refresh có lock và cập nhật token nguyên tử.
- Có trạng thái yêu cầu cấp quyền lại khi refresh thất bại.
- Quyền được xin theo nguyên tắc tối thiểu.
- Có cảnh báo khi tỷ lệ lỗi OAuth hoặc API tăng bất thường.
Kết luận
Zalo OAuth 2.0 không chỉ là nút “Đăng nhập với Zalo” mà là một chuỗi xử lý ủy quyền có trạng thái và vòng đời rõ ràng. Luồng an toàn bắt đầu bằng authorization code, xác minh state và PKCE, đổi code ở backend, lưu access token cùng refresh token bảo mật rồi làm mới có kiểm soát xem thêm tại zalo web đăng nhập.
Khi triển khai Zalo OAuth 2.0, hãy phân biệt User Access Token với OA Access Token, dùng đúng endpoint, đọc thời hạn từ phản hồi và chuẩn bị cơ chế cấp quyền lại. Quản lý tốt callback, quyền và token rotation sẽ giúp tích hợp ổn định, dễ giám sát và an toàn hơn.
Vương Minh – người dẫn dắt và đứng sau sự thành công của ZALO Web cùng với đội ngũ kĩ sư ưu tú nhất. Với khát vọng tạo ra một sản phẩm công nghệ “Make in Vietnam” đủ sức cạnh tranh sòng phẳng với các đối thủ quốc tế, ông Khải cùng các cộng sự tại Zalo Group đã không ngừng cải tiến để Zalo không chỉ là app nhắn tin mà còn là một hệ sinh thái làm việc đa nền tảng. Zalo Web chính là minh chứng cho triết lý đó: tinh gọn, tốc độ và thấu hiểu sâu sắc thói quen của người dùng Việt.