SOAP API Authentication

 

The Zanox SOAP authentication implementation includes the connect ID, with secured mhash key (signature) and the timestamp inside the SOAP/XML request where required. 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.

The authentication information is transferred in the SOAP Body, which is defined by the WSDL and XSD. It is therefore easy to recognize which methods require what type of authentication - for methods with no authentication, the XSD schema will define only connect ID as required parameter, for methods requiring signatures, three additional required fields - timestamp, nonce and signature will be defined.

Public resources - auth with connect ID

For public resources, it is enough to provide the connect ID as query parameter, e.g.:

<soapenv:Envelope xmlns:ns="http://api.zanox.com/namespace/2011-03-01/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:GetProgramRequest>
         <ns:programId>1234</ns:programId>
         <ns:connectId>802B8BF4AE99EBE00F41</ns:connectId>
      </ns:GetProgramRequest>
   </soapenv:Body>
</soapenv:Envelope>

Resources that do not require authentication with signature are Programs, Products, AdMedia and Incentives.

Private resources - auth with signature

The actual building of the signature is taken from the RFC2104 specification. The signature is built by applying a keyed-HMAC (Hash Message Authentication Code) algorithm to the UTF-8 encoded StringToSign. The secret key has to be provided as a parameter to the keyed-HMAC method.

Here is the simple explanation of how to generate a signature.

Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( StringToSign ) ) );

 

The StringToSign consists of a couple of elements that are lowercased and concatenated:

Service name + Operation + timestamp + nonce

Service name - "publisherservice" for Publisher API, "dataservice" for Data API, "connectservice" for Connect API;
Operation - SOAP operation (or method name) as defined in the WSDL. For example "getsales" for GetSales operation and "getprofile" for GetProfile operation.
Timestamp - in GMT, format "yyyy-MM-dd'T'HH:mm:ss" (2007-12-11T13:16:00);
Nonce - unique random string, generated at the time of request, valid once, 20 or more characters

 

To successfully authenticate, connect ID, timestamp, nonce and signature have to be passed in the SOAP Body, the XSD defines authentication parameters for every operation that requires it . Authentication parameter names for all request are the same - connectId, timestamp, nonce and signature.

<soapenv:Envelope xmlns:ns="http://api.zanox.com/namespace/2011-03-01/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:GetProfileRequest>
         <ns:connectId>802B8BF4AE99EBE00F41</ns:connectId>
         <ns:timestamp>2013-08-20T14:52:51</ns:timestamp>
         <ns:nonce>589d4ebe-3ba8-4b18-b24f-30f797e1513d</ns:nonce>
         <ns:signature>dEJPtiQpyZ4Ig4a0sWcuRYc7a9M=</ns:signature>
      </ns:GetProfileRequest>
   </soapenv:Body>
</soapenv:Envelope>

 

Example

Connect ID: 802B8BF4AE99EBE00F41
Secret Key: fa4c0c2020Aa4c+ab9Ea0ec8d39E06/df2c5aa44
API Method: GET Sales for the date 2013-08-19

1. Generate nonce and timestamp

Nonce: b382e074-2fc4-41c9-8d5c-f679805f609c
Timestamp: 2013-08-20T14:44:21

2. Concatinate service name, operation, timestamp and nonce to create StringToSign

publisherservicegetsales2013-08-20T14:44:21b382e074-2fc4-41c9-8d5c-f679805f609c

3. Hash the StringToSign using the secret key as HMAC parameter

Signature: aK6w2dT5X1y9E51FTv0rIU7INZc=

4. Add information to request 

<soapenv:Envelope xmlns:ns="http://api.zanox.com/namespace/2011-03-01/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:GetSalesRequest>
         <ns:date>2013-08-19</ns:date>
         <ns:dateType>trackingDate</ns:dateType>
         <ns:connectId>802B8BF4AE99EBE00F41</ns:connectId>
         <ns:timestamp>2013-08-20T14:44:21</ns:timestamp>
         <ns:nonce>b382e074-2fc4-41c9-8d5c-f679805f609c</ns:nonce>
         <ns:signature>aK6w2dT5X1y9E51FTv0rIU7INZc=</ns:signature>
      </ns:GetSalesRequest>
   </soapenv:Body>
</soapenv:Envelope>

 

See an example client code in Java.