OAuth

Your app cannot read haravan data without authenticating first. It must get permission from a user before gaining access to any of the resources in the REST API. This guide will walk you through the authorization process (described in greater detail by the OAuth 2.0 specification).

In this article:

Terminology

Before getting into the nitty-gritty of the authorization process, let’s go over some of the terms that we’ll be using for the rest of the guide.

  • Client
    Any application that would like access to a shop’s data. A user (usually the shop’s owner) must grant permission before the client can access any data.
  • API
    haravan’s REST API. This is the place where the client can view and modify a shop’s data.
  • User
    A haravan account holder, usually a shop owner. This is the person giving permission to a client to access their shop’s data through the REST API.

Step 1: Get the client’s credentials

You will need to retrieve an API Key and Shared Secret as the client uses them to identify itself during the authorization process.

To retrieve the credentials:

1. Click to open the Apps section of the Partners dashboard

2. Click the name of the App to view it's details:

3. The API key is displayed for you, and you can click Show secret under the Credentials header to view the Shared secret.

Step 2: Asking for permission

1. Install App from link :

    https://{{shopname}}.myharavan.com/admin/api/auth/?api_key={{API key}}

Ex:

https://shopname.myharavan.com/admin/api/auth/?api_key=17920187d99a47bff0f5fe937d4c4383

2. After install app, You can work by click to Banner App on "Ứng dụng" or get link by:

    https://{{shopname}}.myharavan.com/admin/app#/embed/{{API key}}

    Ex:

https://shopname.myharavan.com/admin/app#/embed/17920187d99a47bff0f5fe937d4c4383

The first step of process is to get authorization from the user. This is done by displaying a prompt provided by haravan:

To show the prompt, redirect the user to this URL:

https://{shop}.myharavan.com/admin/oauth/authorize?client_id={api_key}&scope={scopes}&redirect_uri={redirect_uri}&response_type=code

With these substitutions made:

      • {shop} - substitute this for the name of the user’s shop.
      • {api_key} - substitute this for the app’s API Key.
      • {scopes} - substitute this for a comma-separated list of scopes. An example for writing orders and reading customers is scope=write_orders,read_customers.
      • {redirect_uri}Required the location to redirect the user after they authorize the client. If missing, haravan will redirect the user to the Application Callback URL set in the App’s settings from the Partners dashboard. If provided, the host of this URL must be identical to the host of the Application Callback URL.
      • &response_type=code  : default required

Step 3: Confirming installation

When the user clicks the Install button in the prompt, they will be redirected to the client server as specified above. One of the parameters passed in the confirmation redirect is the Authorization Code (the other parameters will be covered later in the guide).

https://example.org/some/redirect/uri?shop={shop}.myharavan.com&code={authorization_code}&signature=da9d83c171400a41f8db91a950508985&timestamp=1409617544

The authorization code can be exchanged once for a permanent access token. The exchange is made with a request to the shop.

POST with x-www-form-urlencoded 

POSThttps://{shop}.myharavan.com/admin/oauth/access_token

With {shop} substituted for the name of the user’s shop and with the following parameters provided in the body of the request:

        • client_id
          The API Key for the app. (See the credentials section of this guide).
        • client_secret
          The Shared Secret for the app. (See the credentials section of this guide).
        • code
          The authorization code provided in the redirect described above.
        • grant_type=authorization_code   : default required
        • redirect_uri - Required the location to redirect the user after they authorize the client. If missing, haravan will redirect the user to the Application Callback URL set in the App’s settings from the Partners dashboard. If provided, the host of this URLmust be identical to the host of the Application Callback URL.

The server will respond with an access token.
 
{
  "access_token": "f85632530bf277ec9ac6f649fc327f17"
}

This is a permanent API access token that can be used to access the shop’s data as long as the client is installed. Clients should store the token somewhere to make authenticated requests for a shop’s data.

Step 4: Making authenticated requests

Now that the client has obtained an API access token, it can make authenticated requests to the REST API. These requests are accompanied with a header Authorization: Bearer {access_token} where {access_token} is replaced with the permanent token.   Content-Type: application/json


The server will respond with an access token.
 
{
  "access_token": "f85632530bf277ec9ac6f649fc327f17"
}

This is a permanent API access token that can be used to access the shop’s data as long as the client is installed. Clients should store the token somewhere to make authenticated requests for a shop’s data.

Scopes

Part of the authorization process requires specifying which parts of a shop’s data the client would like access to (see the “Getting permission” part of this guide). A client can ask for any of the following scopes:

Verification

Every request or redirect from haravan to the client server includes a signature parameters that can be used to ensure that it came from haravan. The signature attribute is deprecated due to vulnerabilities in how the signature is generated.

To verify that a request is valid, first parse the query string into a map of keys to values.

An example query string:

"shop=some-shop.myharavan.com&code=a94a110d86d2452eb3e2af4cfb8a3828&timestamp=1337178173&signature=6e39a2ea9e497af6cb806720da1f1bf3" 

Is converted to this map:

{   "shop": "some-shop.myharavan.com",   "code": "a94a110d86d2452eb3e2af4cfb8a3828",   "timestamp": "1337178173",   "signature": "6e39a2ea9e497af6cb806720da1f1bf3"} 

HMAC Signature Validation

The signature  entries are removed from the map, leaving the remaining parameters.

{   "shop": "some-shop.myharavan.com",   "code": "a94a110d86d2452eb3e2af4cfb8a3828",   "timestamp": "1337178173" } 

Map entries are sorted lexicographically by key, and concatenated together with & to create a string:

"code=a94a110d86d2452eb3e2af4cfb8a3828shop=some-shop.myharavan.comtimestamp=1337178173" 

Lastly, this string processed through an HMAC-SHA256 using the Shared Secret as the key. The message is authentic if the generated hexdigest is equal to the value of the signature parameter.


#PHP code:

public function validateSignature($query)

{

if(!is_array($query) || empty($query['signature']) || !is_string($query['signature'])) return false;

$calculated_signature = "";

if($query['code']) $calculated_signature .= 'code=' . $query['code'];

$calculated_signature .= 'shop=' . $query['shop'] . 'timestamp=' . $query['timestamp'];

$signature = bin2hex(hash_hmac('sha256', $calculated_signature, $this->secret, true));

return $query['signature'] == $signature;

}

Note: You can view example source code from Github Haravan

Haravan - Công ty công nghệ cung cấp giải pháp kinh doanh thương mại điện tử, duy nhất tại Việt Nam được Google lựa chọn vào chương trình bệ phóng tiềm năng với hỗ trợ và đào tạo công nghệ để vươn ra thị trường quốc tế vững chắc.