Support Sapo

Tổng đài hỗ trợ - 
1900 6750
( 7:00 - 22:00 )

OAuth

App của bạn không thể lấy dữ liệu từ Sapo nếu không thực hiện bước xác thực đầu tiên. Một người dùng muốn truy vấn vào bất cứ tài nguyên nào qua REST API đều phải xin quyền. Bài viết này sẽ hướng dẫn bạn toàn bộ quá trình xác thực (bạn có thể xem chi tiết hơn ở OAuth 2.0 specification).

Các bước được đề cập đến trong bài viết:

Thuật ngữ

Trước khi đi vào một khía cạnh quan trọng nhất của quá trình xác thực, hãy cùng tìm hiểu qua một vài thuật ngữ mà chúng ta sẽ sử dụng trong phần còn lại của hướng dẫn.

  • Client
    Bất cứ ứng dụng nào muốn truy cập vào dữ liệu của Shop. Một người dùng quản trị (thường là chủ Shop) phải cấp quyền trước khi Client có thể truy cập vào bất kỳ dữ liệu nào của Shop.
  • API 
    REST API của Sapo. Đây là nơi mà Client có thể xem và chỉnh sửa dữ liệu của Shop.
  • User
    Một tài khoản phía quản trị của Sapo, thường là chủ Shop. Đây à người cấp quyền cho Client để truy vấn vào dữ liệu của Shop thông qua REST API.

Bước 1: Lấy chứng chỉ (credentials) của Client

Bạn cần lấy API Key và Secret Key để định danh Client trong suốt quá trình xác thực. Để lấy thông tin trên bạn cần thao tác tạo App trước. Sau đó thực hiện thao hướng dẫn lấy chứng chỉ bên dưới.

Để lấy chứng chỉ:

1. Click để mở trang danh sách Apps trong màn hình quản lý của Partner

2. Click vào tên App để xem thông tin chi tiết

3. Thông tin API Key và Secret Key được hiển thị.

Bước 2: Xin cấp quyền

Bước đầu tiên của quá trình là lấy xác thực từ User. Việc này được thực hiện bằng cách hiển thị màn hình xin quyền được cung cấp bởi Sapo:

Để hiển thị màn hình xin quyền, Redirect User về địa chỉ URL này:

https://{store}.mysapo.net/admin/oauth/authorize?client_id={api_key}&scope={scopes}&redirect_uri={redirect_uri}

Với các giá trị tương ứng như sau:

  • {store} - tên của Shop.
  • {api_key} - API Key.
  • {scopes} - danh sách scopes, cách nhau bởi dấu phẩy. Ví dụ, muốn xin quyền write orders và read customers thì sử dụng scope=write_orders,read_customers.
  • {redirect_uri} - (Bắt buộc) đường dẫn URL mà bạn muốn Redirect User đến sau khi họ xác thực Client. Địa chỉ URL này phải giống với địa chỉ Redirect URL của App

Bước 3: Khẳng định việc cài đặt

Khi User click nút Install trong màn hình xin quyền, họ sẽ được chuyển hướng tới địa chỉ đã được xác định ở trên. Một tham số được truyền trên đường dẫn là Authorization Code (Các tham số khác sẽ được đề cập đến ở phần sau của bài viết).

https://{your_domain}/some/redirect/uri?code={authorization_code}&signature=da9d83c171400a41f8db91a950508985×tamp=1409617544

Authorization code có thể được dùng để lấy một access token để sử dụng bằng cách thực hiện request sau tới Shop.

POSThttps://{store}.mysapo.net/admin/oauth/access_token

Trong đó {store} là tên của Shop và request có gửi kèm theo các tham số sau:

  • client_id
    API Key của App. (Xem lại phần credentials trong bài viết).
  • client_secret
    Secret Key của App. (Xem lại phần credentials trong bài viết).
  • code
    Authorization code được cấp ở trên.

Server sẽ trả về Truy xuất dữ liệu của các tài nguyên cho Client.

{
    "access_token": "f85632530bf277ec9ac6f649fc327f17"
}

Đây chính là API access token vĩnh viễn được sử dụng để truy cập vào các dữ liệu của Shop khi Client được cài đặt. Client nên lưu trữ token này lại để gửi các request hợp lệ đến để lấy dữ liệu từ Shop.

Bước 4: Tạo request đã được xác thực

Sau khi Client đã lấy được API access token, Client có thể tạo các Request đã được xác thực lên REST API. Những Request này có gắn kèm tham số trên header là X-Sapo-Access-Token: {access_token} trong đó {access_token} chính là token mà Client đã lấy được ở trên.

Scopes

Một phần trong quá trình xác thực yêu cầu xác định xem Client muốn truy xuất vào dữ liệu gì của Shop (Xem phần “Xin cấp quyền” trong hướng dẫn này). Một Client có thể xin cấp quyền trong các Scopes sau:

Verification

Mỗi Request hoặc chuyển hướng từ Sapo về Client đều chứa các tham số signature và hmac, được dùng để xác minh dữ liệu đúng là từ Sapo. 

Để xác minh một Request là hợp lệ, đầu tiên thực hiện phân giải tham số trong query string ra thành các cặp (key, value) tương ứng.

Ví dụ về một query string:

"store=some-store.mysapo.net&code=a94a110d86d2452eb3e2af4cfb8a3828&timestamp=1337178173&hmac=Y2YzMmJhNTAyZTc2ZWNkNTI2NDY0OTJmZGFmNWIzYjFkYmQzYzFmZjlhMGI1NDlkMGRiYzhmNzM2YWFlMTlkOQ=="

được phân tách ra như sau:

{
    "store": "some-store.mysapo.net",
    "code": "a94a110d86d2452eb3e2af4cfb8a3828",
    "timestamp": "1337178173",
    "hmac": "echpNU0bdOnrrkuXuezST/t5ybfoG6SdvO/35O3gma0="
}

HMAC Validation

Giá trị hmac được lấy ra, để lại các tham số khác.

{
    "store": "some-store.mysapo.net",
    "code": "a94a110d86d2452eb3e2af4cfb8a3828",
    "timestamp": "1337178173"
}

Mỗi một key được ghép với value tương ứng của nó qua ký tự = để tạo ra một danh sách các xâu. Danh sách các cặp key-value được sắp xếp theo thứ tự như trong từ điển và được ghép với nhau bởi ký tự & để tạo ra một xâu duy nhất:

"code=a94a110d86d2452eb3e2af4cfb8a3828&store=some-store.mysapo.net&timestamp=1337178173"

Cuối cùng, xâu này được thực hiện mã hóa HMAC-SHA256 sử dụng khóa là Secret Key. Dữ liệu được xác thực là hợp lệ nếu như chuỗi ký tự mã hóa được sinh ra bằng với giá trị của tham số hmac.

require 'openssl'
require 'base64'

digest = OpenSSL::Digest.new('sha256')
secret = "hush"
message = "store=some-store.mysapo.net&timestamp=1337178173"
digest = Base64.strict_encode64(OpenSSL::HMAC.digest(digest, secret, message))
digest == "G3jquuw8QwzywMgoWHHYq5ctguAjAY8BU4P1+ETGTPQ="

Bài viết trên có hữu ích cho bạn không?

Hữu ích Không hữu ích
Số lượt đánh giá hữu ích: