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. connectID

Requests that require authentication have to provide a

2. timestamp and
2. nonce at least a 20 character random string.
4. crypted hash signature with your secretKey too.

Requests without Signature

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

Step 1/1

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

Authorization = "ZXWS" + " " + connectId

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

Example Request (HTTP URL)

GET /xml/programs?connectId=CE665764E0386EA44287 HTTP/1.1
Host: 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.

1. HTTP-Verb (GET/POST/DELETE/PUT/OPTION/HEAD)
2. URI (without protocol (xml/json), version and query parameter)

 for example http://api.zanox.com/xml/2009-07-01/programs/program/49?connectId=B7B23C545599DCA768BA
 URI = /programs/program/49

3. GMT-Date (see step 1)
4. NONCE 20 character random string

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/programs/program/49Mon, 09 Jun 2008 08:17:35 GMT01234567890123456789"
string2sign = HTTP-Verb + URI + GMT-Date + NONCE;

Step 2/3

The signature is build by applying a keyed-HMAC (Hash Message Authentication Code) algorithm to the UTF-8 encoded string2sign. The secretKey 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 ), secretKey ) );
 

Step 3/3

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

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

Authorization = "ZXWS" + " " + connectId + ":" + signature;
Date = gmtdate();
Nonce = randomString();

Example Request (HTTP Header)

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

Verification

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