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 retrieve various information via the SOAP API. 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.

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

Background

The SOAP API authentication process requires additional parameters to be submitted within a request.

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

Introduction

Usage of the SOAP API distinguishes between SOAP function calls that require a hash-based signature parameter and those who don't.

Every SOAP call has at least to provide the applicationID parameter to every request:

1. applicationID

SOAP calls that require strong authentication have to provide a

2. timestamp and
3. crypted hash signature with your shared key too.

Requests without Signature

SOAP calls require the applicationID to be submitted within every request. The applicationID has to be provided as the very last parameter in every SOAP call.

Example Request: Get all programs

<GetPrograms xmlns="http://api.zanox.com/namespace/2009-02-01">
	<applicationid>1D9FVRAYCP1VJEXAMPLE=</applicationid>
</GetPrograms>

Example Request: Get a single program

<GetProgram xmlns="http://api.zanox.com/namespace/2009-02-01">
	<program>3277<program>
	<applicationid>1D9FVRAYCP1VJEXAMPLE=</applicationid>
</GetProgram>

Requests with Signature

SOAP calls that need some kind of security have to include the applicationID, a signature and the dateTime as well. The signature and dateTime changes with every SOAP call.

Step 1/3

A string2sign has to be build out of three elements of the SOAP request that are concatenated without whitespaces. Method and dateTime have to be replaced by the parameters of the SOAP call. The name of the SOAP service as well as of the method (SOAP function used) must be lowercase.

// string2sign = "publisherservicegetprograms2008-06-08T12:00:00.183Z"

string service = "publisherservice"; //lower case !
string operation = "updateadspace"; // lower case !
string string2sign = service + operation + DateTime.Now.ToString("yyyy-MM-ddTHH:mm:ss.000Z'");

Notice: The dateTime 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 special dateTime format that needs to be set as well. If the correct dateTime is not provided in the function call the request can not be processed correctly.

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 be 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 SOAP call has to include the applicationID, signature and dateTime used to build the string2sign. The applicationID, timestamp and signature have to be provided as the three last parameter in every SOAP call.

Example Request

<GetMyAdspaces xmlns="http://api.zanox.com/namespace/2009-02-01">
	<applicationid>1D9FVRAYCP1VJEXAMPLE=</applicationid>
	<timestamp>2008-06-08T12:00:00.183Z</timestamp>
	<signature>FN+JGAMxDShoyh3sfayql6jWCRc=</signature>
</GetMyAdspaces>

Verification

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