If you have any question left, please drop a note with the discussion link of this page.

From Wiki.zanox.com

Authentication is necessary to proof identity to your application. The access control decision is an important factor that allows you to access certain RESTful API resources. For example, only the owner of an advertising space can request properties of an advertising space. This makes it necessary to prove that you are the owner of a resource.

This section shows you how to implement the proper authentication to validate your requests to the Zanox RESTful API.

Background

The RESTful API authentication process requires various HTTP Header parameters to be submitted with a request.

The main component of this process is a hash based signature that is based on the RFC2616 for HTTP Digest Access Authentication and the RFC2104 for Keyed-Hashing for Message Authentication.

Introduction

Usage of the RESTful API distinguishes between operations on resource that require a hash-based signature and those who don't.

Every request has at least to provide two parameters to every request:

1. applicationID and
2. timestamp.

Requests that require authentication have to provide a

3. crypted hash signature with your shared key too.

Requests without Signature

Requests that do not need a signature still require the applicationID.

Step 1/1

The Authorization-Header is constructed by providing ZXWS followed by the applicationID.

Authorization = "ZXWS" + " " + applicationId

Example Request (HTTP Header)

GET /xml/programs HTTP/1.1
Host: api.zanox.com
Authorization: ZXWS CE665764E0386EA44287

Example Response (HTTP Header)

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Server: api.zanox.com

Requests with Signature

Requests that need some kind of security have to include a signature. This signature changes with every requests and includes elements from the request.

Step 1/3

A string2sign has to be build out of three elements that are concatenated without whitespaces. The URI has to be included without the protocol (json/xml/soap) and version parameter (/xml/2008-05-21/adspaces becomes just /adspaces).

1. HTTP-Verb
2. URI (without protocol (xml/json), version and query parameter)
3. GMT-Date (see step 1)

The timestamp has validity of 30 minutes. If the message arrives later or earlier or later than 15 minutes to the original construction the request will be rejected. You have to provide a GMT timestamp that needs to be set in the HTTP header as well (see step 1/3)! If the correct GMT time is not provided in the HTTP header the request can not be processed correctly.

// string2sign = "GET/adspacesMon, 09 Jun 2008 08:17:35 GMT"
string2sign = HTTP-Verb + URI + GMT-Date;

Step 2/3

The signature is build by applying a keyed-HMAC (Hash Message Authentication Code) algorithm to the UTF-8 encoded string2sign. The sharedKey has to provided as a parameter to the keyed-HMAC method.

The HMAC-SHA1 algorithm is defined by the RFC 2104. Finally Base64 encoded has to be applied.

 
signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( string2sign ), sharedKey ) );
 

Step 3/3

The Authorization-Header is constructed by providing ZXWS followed by the applicationID and signature. The date header element needs to be set to the GMT time of the request.

In order to retrieve the correct GMT-date of your local computer you can use this GMT service.

Authorization = "ZXWS" + " " + applicationId + ":" + signature;
Date = gmtdate();

Example Request (HTTP Header)

GET /xml/adspaces HTTP/1.1
Host: api.zanox.com
Date: Mon, 09 Jun 2008 08:17:35 GMT
Authorization: ZXWS CE665764E0386EA44287:FN+JGAMxDShoyh3sfayql6jWCRc=

Verification

If you want to verify your signature and compare your key you may use our SigntureTool [1].