Authentication

• Introduction
• Using OAuth
• Why Do You Need OAuth?
• OAuth Definitions
• OAuth Process
  • Registering an Application
  • Authentication Endpoints
    • Getting an Unauthorized Request Token
    • User Authorization
    • Getting an Access Token
• OAuth Error Codes
• PHP Examples
  • Retrieve the list of products for Admin user with OAuth authentication
  • Retrieve the list of products for Customer user with OAuth authentication

Introduction

In most cases, the third-party application must be authenticated to use the Inovarti Platform API. But users never reveal their credentials to the application to preserve their privacy. So, the question is as follows: how is your application going to authenticate users if it does not know user credentials. OAuth is the solution.

Inovarti Platform authentication is based on OAuth, an open standard for secure API authentication. OAuth is a token-passing mechanism that allows users to control which applications have access to their data without revealing their passwords or other credentials.

The OAuth concept lies in three basic elements that can be easily described in the following picture:

To learn more about OAuth, you can visit the official OAuth site.

Using OAuth

The current API supports OAuth 1.0a.

The OAuth authentication works by asking the user to authorize their application. When the user authorizes the application, the application can access that user protected resources by using an access token. This token will be used in each further request. Access tokens are long-lived and will not expire unless the user revokes access to the application.

OAuth is completely invisible for the site visitors.

Why Do You Need OAuth?

Inovarti Platform uses OAuth to allow access to its data. You need to use OAuth if you want to use any of the following Inovarti Platform APIs:

• Products
• Inventory
• Orders
• Customers
• Customer Addresses
• Categories
  and a lot more

OAuth Definitions

There are some definitions you need to get familiar with before you start using OAuth. These are as follows:

• User - A customer who has an account with Inovarti Platform and can use the services via the Inovarti Platform API.
• Consumer - A third-party application that uses OAuth to access the Inovarti Platform API. This application must be registered in the Inovarti Platform system to receive the Consumer Key and Consumer Secret.
• Consumer Key - A value used by the Consumer to identify itself with Inovarti Platform.
• Consumer Secret - A secret used by the Consumer to guarantee the ownership of the Consumer Key. This value is not passed in requests.
• Request Token - A value used by the Consumer to obtain authorization from the User (when needed). The Request Token is exchanged for an Access Token when permission is granted.
• Access Token - A value used by the Consumer to call Inovarti Platform APIs on behalf of the User.

OAuth Process

The OAuth process consists of several steps:

• Getting an Unauthorized Request Token.
• Requesting user authorization.
• Getting an Access Token by exchanging the Request Token for it.

The application that requires access to data is known as the Consumer and Inovarti Platform is the Service Provider.

Registering an Application

Before starting to make API requests, you need to register the application. After the registration, you will receive the Consumer Key that will identify you in Inovarti Platform. Also, you will receive a Consumer Secret. This secret will be used when requesting for a Request Token.

You can register your application by selecting System > Web Services > REST - OAuth Consumers and clicking Add New in the Admin Panel.

When registering the application, you also need to define the callback URL, to which the user will be redirected after he/she successfully authorizes your application.

Authentication Endpoints

The authentication endpoints include the following ones:

• /oauth/initiate - this endpoint is used for retrieving the Request Token.
• /oauth/authorize - this endpoint is used for user authorization (Customer).
• /admin/oauth_authorize - this endpoint is used for user authorization (Admin).
• /oauth/token - this endpoint is used for retrieving the Access Token.

Also, the simple form can be used for authentication. To use a simple form, add the /simple endpoint to the authentication endpoint. For example: /oauth/authorize/simple

Getting an Unauthorized Request Token

The first step to authenticate the user is to retrieve a Request Token from Inovarti Platform. This is a temporary token that will be exchanged for the Access Token.

The following request parameters should be present in the Authorization header:

• oauth_callback - an URI to which the Service Provider will redirect the resource owner (user) after the authorization is complete.
• oauth_consumer_key - the Consumer Key value, retrieved after the registration of the application.
• oauth_nonce - a random value, uniquely generated by the application.
• oauth_signature_method - name of the signature method used to sign the request. Can have one of the following values: HMAC-SHA1, RSA-SHA1, and PLAINTEXT.
• oauth_signature - a generated value (signature).
• oauth_timestamp - a positive integer, expressed in the number of seconds since January 1, 1970 00:00:00 GMT.
• oauth_version - OAuth version.

User Authorization

The second step is to request user authorization. After receiving the Request Token from Inovarti Platform, the application provides an authorization page to the user. The only required parameter for this step is the Request Token (oauth_token value) received from the previous step. The endpoint is followed by an oauth_token parameter with the value set to the oauth_token value.

After this, the user is asked to enter their credentials and authorize. When the user is granted the access, he/she is redirected to the URL specified in the oauth_callback parameter. This URL is followed by two parameters:

• oauth_token - the Request Token value.
• oauth_verifier - a verification code that is tied to the Request Token.

Getting an Access Token

The final third authentication step. After the application access is authorized, the application needs to exchange the Request Token for an Access Token. For this step, you will need the Request Token (the oauth_token and oauth_token_secret values) and the oauth_verifier value from the previous step.

The following components should be present in the Authorization header:

• oauth_consumer_key - the Consumer Key value provided after the registration of the application.
• oauth_nonce - a random value, uniquely generated by the application.
• oauth_signature_method - name of the signature method used to sign the request. Can have one of the following values: HMAC-SHA1, RSA-SHA1, and PLAINTEXT.
• oauth_signature - a generated value (signature).
• oauth_timestamp - a positive integer, expressed in the number of seconds since January 1, 1970 00:00:00 GMT.
• oauth_token - the oauth_token value (Request Token) received from the previous steps.
• oauth_verifier - the verification code that is tied to the Request Token.
• oauth_version - OAuth version.

The response will contain the following response parameters:

• oauth_token - the Access Token that provides access to protected resources.
• oauth_token_secret - the secret that is associated with the Access Token.

OAuth Error Codes

When the third-party application performs invalid requests to Inovarti Platform, the following errors related to OAuth can occur:

PHP Examples

Retrieve the list of products for Admin user with OAuth authentication

<?php
/**
 * Example of retrieving the products list using Customer account via Inovarti Platform REST API. OAuth authorization is used
 * Preconditions:
 * 1. Install php oauth extension
 * 2. If you were authorized as an Admin before this step, clear browser cookies for 'yourhost'
 * 3. Create at least one product in Inovarti Platform and enable it for viewing in the frontend
 * 4. Configure resource permissions for Customer REST user for retrieving all product data for Customer
 * 5. Create a Consumer
 */
// $callbackUrl is a path to your file with OAuth authentication example for the Customer user
$callbackUrl = "http://yourhost/oauth_customer.php";
$temporaryCredentialsRequestUrl = "http://yourhost/oauth/initiate?oauth_callback=" . urlencode($callbackUrl);
$customerAuthorizationUrl = 'http://yourhost/oauth/authorize';
$accessTokenRequestUrl = 'http://yourhost/oauth/token';
$apiUrl = 'http://yourhost/api/rest';
$consumerKey = 'yourconsumerkey';
$consumerSecret = 'yourconsumersecret';

session_start();
if (!isset($_GET['oauth_token']) && isset($_SESSION['state']) && $_SESSION['state'] == 1) {
    $_SESSION['state'] = 0;
}
try {
    $authType = ($_SESSION['state'] == 2) ? OAUTH_AUTH_TYPE_AUTHORIZATION : OAUTH_AUTH_TYPE_URI;
    $oauthClient = new OAuth($consumerKey, $consumerSecret, OAUTH_SIG_METHOD_HMACSHA1, $authType);
    $oauthClient->enableDebug();

    if (!isset($_GET['oauth_token']) && !$_SESSION['state']) {
        $requestToken = $oauthClient->getRequestToken($temporaryCredentialsRequestUrl);
        $_SESSION['secret'] = $requestToken['oauth_token_secret'];
        $_SESSION['state'] = 1;
        header('Location: ' . $customerAuthorizationUrl . '?oauth_token=' . $requestToken['oauth_token']);
        exit;
    } else if ($_SESSION['state'] == 1) {
        $oauthClient->setToken($_GET['oauth_token'], $_SESSION['secret']);
        $accessToken = $oauthClient->getAccessToken($accessTokenRequestUrl);
        $_SESSION['state'] = 2;
        $_SESSION['token'] = $accessToken['oauth_token'];
        $_SESSION['secret'] = $accessToken['oauth_token_secret'];
        header('Location: ' . $callbackUrl);
        exit;
    } else {
        $oauthClient->setToken($_SESSION['token'], $_SESSION['secret']);

        $resourceUrl = "$apiUrl/products";
        $oauthClient->fetch($resourceUrl, array(), 'GET', array('Content-Type' => 'application/json'));
        $productsList = json_decode($oauthClient->getLastResponse());
        print_r($productsList);
    }
} catch (OAuthException $e) {
    print_r($e->getMessage());
    echo "<br/>";
    print_r($e->lastResponse);
}