How to write authentication code tutorial

Prerequisites

• You’ve read Authentication Overview and Authentication using the Client Helpers.

• You are competent in a language you want to be able to authenticate from and are able to port the examples from PHP.

• You have access to a warehouse suitable for testing against and have created a website registration on the warehouse.

If you are using the Drupal integration or client helpers API from PHP, you are unlikely to need to write your own authentication code for the Indicia warehouse’s web services. However, there are cases when being able to write custom code which authenticates against the web services is necessary, in particular when you are writing your own client code. E.g. you might need to authenticate against the Indicia web services from a desktop application, a website written in Java, or from a mobile application. This tutorial guides you through the required steps using examples in PHP with cUrl, which are hopefully simple enough to port to other languages.

First, let’s define some variables to hold the details we need to authenticate, namely the website ID, password and URL of the warehouse. I’m going to use the default demonstration website installed with the warehouse on my localhost web server.

<?php

$website_id=1;
$password='password';
$warehouseUrl='http://localhost/indicia/';

?>

Having defined these variables, we need to the next step is to build the URL which the authentication web services are found at. As we are going to call the get_read_nonce method this is simply a case of appending the following:

<?php

...
$serviceUrl = $warehouseUrl.'index.php/services/security/get_read_nonce';

?>

Next, we use the cUrl library to send an HTTP post to the web service with the website ID as a post argument:

<?php

...
$postargs="website_id=$website_id";
$session = curl_init();
// Set the POST options.
curl_setopt($session, CURLOPT_URL, $serviceUrl);
curl_setopt($session, CURLOPT_POST, true);
curl_setopt($session, CURLOPT_POSTFIELDS, $postargs);
curl_setopt($session, CURLOPT_HEADER, false);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
// Do the POST and then close the session
$nonce = curl_exec($session);
$headers = curl_getinfo($session);
if (curl_errno($session) || $headers['http_code']!==200)
  throw new Exception("cUrl error number: ".curl_errno($session));
curl_close($session);

?>

Now, the $response variable holds the nonce returned from the warehouse. In order to fulfill the requirements of the digest authentication, we must use this nonce along with the website password to create the auth token. We use the sha1 algorithm to do this which is considered to be non-reversible.

Tip

PHP’s sha1 algorithm always returns a lowercase sequence of letters and numbers. There are other implementations which return uppercase. Since we are authenticating against a PHP web service, if your own implementation returns uppercase, then simply convert your auth_token to lowercase before proceeding.

<?php

...
$auth_token=sha1("$nonce:$password");

?>

We now know the $nonce and $auth_token which can be attached as GET or POST parameters to web services requests to authenticate them. In this example we called the get_read_auth web service, it simply requires a change to use the get_auth web service to obtain write authorisation tokens.

For reference, here is the complete code:

<?php

$website_id=1;
$password='password';
$warehouseUrl='http://localhost/indicia/';
$serviceUrl = $warehouseUrl.'index.php/services/security/get_read_nonce';
$postargs="website_id=$website_id";
$session = curl_init();
// Set the POST options.
curl_setopt($session, CURLOPT_URL, $serviceUrl);
curl_setopt($session, CURLOPT_POST, true);
curl_setopt($session, CURLOPT_POSTFIELDS, $postargs);
curl_setopt($session, CURLOPT_HEADER, false);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
// Do the POST and then close the session
$nonce = curl_exec($session);
$headers = curl_getinfo($session);
if (curl_errno($session) || $headers['http_code']!==200)
  throw new Exception("cUrl error number: ".curl_errno($session));
curl_close($session);
$auth_token=sha1("$nonce:$password");

?>