Hướng dẫn dùng oauth provider trong PHP

Sau quá trình tạo và cấu hình ứng dụng, để có thể gọi các API của Zalo thì trước hết ứng dụng của bạn cần phải được Zalo cấp một cái “chìa khóa” đó là Access Token.

Lấy Access Token để gọi Zalo API

Bài viết trong chuỗi Hướng dẫn lập trình Zalo API với PHP và JavaScript.

Zalo có hai loại access token, trong đó Official Account Access Token sử dụng cho các dịch vụ liên quan đến Official Account [OA, Article, Shop, ZNS API] và User Access Token dành cho tài khoản cá nhân [Social API].

Zalo Platform chính thức chuyển sang sử dụng Zalo Login v4 để cấp access token. Để tìm hiểu phương pháp cũ, hãy xem bài viết Lấy access token bằng Zalo Login v3.

Việc lấy access token cho Official Account và User là tương tự nhau, chỉ khác URL tới Zalo Service.

Mục lục

• Official Account Access Token
• User Access Token
• Lấy Authorization Code
• Lấy Access Token
• Tạo access token mới khi hết hạn

Official Account Access Token

Luồng lấy oAuth access token cho Official Account như sau:

Luồng lấy Access Token truy cập Official Account API [oAuth v4]

User Access Token

Luồng lấy oAuth access token cho User giống như Official Account nhưng khác ở URL đến Zalo Authentication Service.

Luồng lấy Access Token truy cập Social API [oAuth v4]

Trong oAuth v4, ta cần trải qua 2 bước sau đó là lấy Authorization Code rồi sau đó mới lấy được Access Token.

Lấy Authorization Code

Trước tiên sẽ ta tạo cặp mã code verifier [ngẫu nhiên] và code challenge để phục vụ cho phương thức PKCE, kèm theo một giá trị trạng thái ngẫu nhiên state để ngăn ngừa tấn công CSRF.

Giá trị code verifier và state sẽ còn được sử dụng thêm 01 lần nữa trong auth.php ngay sau đó, vì vậy ta sẽ lưu tạm chúng vào PHP session.

Từ index.php redirect tới Permission URL dưới đây để yêu cầu quyền truy cập Official Account.

Loại APIPermission URLOfficial Account API
Article API
Shop API
ZNS API//oauth.zaloapp.com/v4/oa/permissionSocial API//oauth.zaloapp.com/v4/permission

Tham số truyền vào query string cho URL nói trên gồm:

ParameterÝ nghĩaapp_idID của ứng dụngredirect_uriĐường dẫn được cấu hình tại phần setting của Official Account đang liên kết với Ứng dụng của bạn. Ở đây là URL đầy đủ tới auth.php.code_challengeMã code challenge đã tạo trong index.php từ code verifier phục vụ cho phương thức PKCE.
Sẽ được trả về nguyên vẹn cho auth.php.stateMã trạng thái state đã tạo trong index.php với mục đích ngăn tấn công CSRF.
Sẽ được trả về nguyên vẹn cho auth.php.

Ở đây giả sử ta sẽ lưu access token trong một biến PHP session là zalo_access_token, sau đó sẽ được lưu phía client trong một biến như ví dụ dưới đây là initialToken.

Bạn có thể lưu ở cookie hay local storage tùy theo thiết kế chương trình nhưng hãy thận trọng với XSS.

Sau khi xác nhận quyền truy cập Official Account từ người dùng, Zalo sẽ redirect về auth.php, đồng thời truyền các tham số sau cho auth.php qua method GET.

ParameterÝ nghĩaoa_idID của Official Account đã cấp quyền cho Ứng dụngcode Authorization code mà ta sẽ dùng để xác thực trong bước tiếp theo.
Code chỉ có hiệu lực trong vòng 10 phút.code_challengeCode challenge được trả lại.stateMã trạng thái được trả lại.

Lấy Access Token

auth.php gửi Authentication code và Code verifier đến Access Token URL dưới đây để yêu cầu tạo access token qua method POST:

Loại APIAccess Token URLOfficial Account API, Article API, Shop API, ZNS API//oauth.zaloapp.com/v4/oa/access_tokenSocial API//oauth.zaloapp.com/v4/access_token

Tham số trong HTTP header:

HTTP HeaderÝ nghĩaContent-Typeapplication/x-www-form-urlencoded để xác định dữ liệu trong POST request là kiểu query string.secret_keyKhóa bí mật của ứng dụng lấy từ trang cấu hình ứng dụng của Zalo.

Tham số trong POST parameter:

ParameterÝ nghĩaapp_idID của ứng dụng lấy từ trang cấu hình ứng dụng của Zalo.code Authorization code mà ta đã lấy được ở bước trước đó.grant_typeGiá trị: authorization_code – tạo access token từ authorization code.code_verifierCode verifier đã tạo trong index.php.

Zalo platform sẽ trả về dữ liệu kiểu JSON bao gồm 3 thông tin sau:

ParameterÝ nghĩaaccess_tokenMã truy cập API của Zalo platform [access token].
Hiệu lực trong vòng 1 giờ.refresh_tokenMã để cấp lại access token mới khi đáo hạn [sau 25 giờ = 90,000 giây].
Hiệu lực trong vòng 3 tháng.
Có thể dùng hoặc không tùy thiết kế ứng dụng.expires_inThời gian hiệu lực của access token = 90000.

Bạn hãy lưu lại mã access_token để truy cập đến API của Zalo ví dụ ở đây ta sẽ lưu vào một HTTP only cookie là zalo_access_token.

Tạo access token mới khi hết hạn

Do access token có thời gian sống khoảng 25 giờ [90,000 giây] nên ứng dụng cần yêu cầu cấp phát một access token mới mà không phải thông qua nhiều bước như trên. Đây là lý do refresh token tồn tại.

Trong auth.php, refresh token đang được lưu trong một HTTP only cookie là zalo_refresh_token.

Khi một request bị hết hạn, Zalo sẽ trả về JSON có chứa mã lỗi [-216 / Access token không hợp lệ]. Khi đó, từ phía client có thể request trang refresh.php dưới đây để lấy access token mới và lưu trữ lại.

Kết quả trả về dưới định dạng JSON để có thể sử dụng với JavaScript.

Để tự động dùng refresh token mỗi khi access token bị hết hạn mà không làm gián đoạn các request song song, bạn có thể sử dụng một framework JavaScript ajax ví dụ như axios với chức năng

0 chẳng hạn.