Signing Amazon Product Advertising API requests — the missing C# WCF sample

(See also part 2 of this post)

Just the sample code

Download the sample project from:

AmazonProductAdvtApiWcfSample.zip, 324KB, 8/1/2009

The sample is self-contained. You don’t need to follow any of the text in this post to build and use it. If trying to replicate the sample’s behavior in a different program, take a look at step 2 below regarding adding the Amazon ECS service reference.

Authentication of Product Advertising API requests

If you develop for the Amazon Product Advertising API (formerly known as the Amazon Associates Web Service — AWS), you would have noticed by now the repeating emails from Amazon about a change in the rules. Starting August 15, 2009, all API requests must be authenticated using cryptographic signatures. The Amazon API documentation explains how to authenticate requests. The API team also provides sample code in C#, Java and Perl. Two C# samples are provided, one for applications using the SOAP interface, and another for applications using REST.

My application uses SOAP, and so I started with that sample. The SOAP sample, it turned out, uses the Microsoft.Web.Services3 namespace, which belongs to the Web Services Enhancements (WSE) class library. WSE appears to be a .NET 2.0, Visual Studio 2005 thing, and is superceded by WCF. If I have to touch my application, I would much rather update it to use WCF, .NET 3.5, and Visual Studio 2008 than to WSE.

Thankfully, a number of folks tackled the problem already. The WCF solution implements the IClientMessageInspector interface to gain an opportunity to sign SOAP requests just before they are sent. The signing logic isn’t particularly complex. It must, however, implement the letter of the specification,or requests are dropped. The remainder of this post outlines a short sample program illustrating how to generate authenticated WCF requests to the Amazon product advertising API. You can download the complete sample from the link at the top of this post.

Step 1 – Create a sample console application

1. In Visual Studio 2008, select New/Project… from the File menu.
2. Select Console Application from Visual C#/Windows, and enter the application’s name.
3. Click OK

Visual Studio creates a new console application. So far, this isn’t different than any other console app.

Step 2 – Add a web service reference

1. In the Solution Explorer view, right click References, then select Add Service Reference…
2. The Add Service Reference dialog appears. Type in the Amazon Product Advertising API WSDL URL in the Address box: http://webservices.amazon.com/AWSECommerceService/AWSECommerceService.wsdl.
3. Click Go. Visual Studio takes a moment to download the service description, and then populates the Services box. You should see AWSECommerceService in there.
4. Type in the namespace for the code that Visual Studio will generate. I used Amazon.ECS. Click OK.

Visual Studio now creates a service reference and adds it to your project. You can see it under the Service References folder in Solution Explorer. Your application will now also have an app.config file added, listing WCF binding and endpoint information for the added service.

Step 3 – Add code to access the Product Advertising API.

You could update your program as follows to have it connect to the product advertising API and search for books with “WCF” in their title. Make sure to add a using statement to reference the namespace you chose for the service in step 2.

    using System.ServiceModel;
    using AmazonProductAdvtApiWcfSample.Amazon.ECS;

    class Program {
        // your Amazon ID's
        private const string accessKeyId    = "YOURACCESSKEYIDHEREX";
        private const string secretKey      = "YOURAMAZONSECRETKEYHERE/YESITSTHISLONGXX";

        // the program starts here
        static void Main(string[] args) {

            // create a WCF Amazon ECS client
            AWSECommerceServicePortTypeClient client = new AWSECommerceServicePortTypeClient(
                new BasicHttpBinding(),
                new EndpointAddress("http://webservices.amazon.com/onca/soap?Service=AWSECommerceService"));

            // prepare an ItemSearch request
            ItemSearchRequest request   = new ItemSearchRequest();
            request.SearchIndex         = "Books";
            request.Title               = "WCF";
            request.ResponseGroup       = new string[] { "Small" };

            ItemSearch itemSearch       = new ItemSearch();
            itemSearch.Request          = new ItemSearchRequest[] { request };
            itemSearch.AWSAccessKeyId   = accessKeyId;

            // issue the ItemSearch request
            ItemSearchResponse response = client.ItemSearch(itemSearch);

            // write out the results
            foreach (var item in response.Items[0].Item) {
                Console.WriteLine(item.ItemAttributes.Title);
            }
        }
    }

If you enter your Amazon access key ID into accessKeyId and run this program before the August 15 deadline, you might just obtain results. Your console should list the top 10 results for the “WCF” query against Amazon’s US book catalog. If you read this after the deadline has expired, you must complete the remaining steps before you can see the results.

Step 4 — Add the authentication code

That’s why we’re here. This sample adds the authentication SOAP headers using three classes:

• AmazonSigningMessageInspector implements the IClientMessageInspector interface. The implementation of the BeforeSendRequest method in this class generates the request signature and adds the appropriate headers to the request.
• AmazonSigningEndpointBehavior implements the IEndpointBehavior. The implementation of the ApplyClientBehavior in this class adds our message inspector to the ECS client at the right moment.
• AmazonHeader is a small helper class implementing MessageHeader. Our message inspector uses instances of this class to add the authentication headers into the SOAP request.

Rather than include the full listing of these classes, let’s focus on the portion that actually signs the request.

public object BeforeSendRequest(ref Message request, IClientChannel channel) {
    // prepare the data to sign
    DateTime    now             = DateTime.UtcNow;
    string      timestamp       = now.ToString("yyyy-MM-ddTHH:mm:ssZ");
    string      signMe          = operation + timestamp;
    byte[]      bytesToSign     = Encoding.UTF8.GetBytes(signMe);

    // sign the data
    byte[]      secretKeyBytes  = Encoding.UTF8.GetBytes(secretKey);
    HMAC        hmacSha256      = new HMACSHA256(secretKeyBytes);
    byte[]      hashBytes       = hmacSha256.ComputeHash(bytesToSign);
    string      signature       = Convert.ToBase64String(hashBytes);

    // add the signature information to the request headers
    request.Headers.Add(new AmazonHeader("AWSAccessKeyId", accessKeyId));
    request.Headers.Add(new AmazonHeader("Timestamp", timestamp));
    request.Headers.Add(new AmazonHeader("Signature", signature));

    return null;
}

BeforeSendRequest gets called just before the SOAP request is put out on the network. Our implementation of this method comutes a hash-based message authentication code (HMAC) of the operation and current time using the SHA256 hash function. It also puts the access key ID, timestamp and signature in the SOAP request headers. This embeds tags like the following in the SOAP request:

<soap:Header
   xmlns:aws="http://security.amazonaws.com/doc/2007-01-01/">
   <aws:AWSAccessKeyId>YOURACCESSKEYIDHEREX</aws:AWSAccessKeyId>
   <aws:Timestamp>2009-08-15T23:59:59Z</aws:Timestamp>
   <aws:Signature>SZf1CHmQnrZbsrC13hCZS061ywsEXAMPLE</aws:Signature>
</soap:Header>

Step 5 – Make the Amazon ECS client authenticate

Finally, to make our Amazon ECS client actually authenticate its requests, modify the main() method as follows:

// create a WCF Amazon ECS client
AWSECommerceServicePortTypeClient client = new AWSECommerceServicePortTypeClient(
    new BasicHttpBinding(BasicHttpSecurityMode.Transport),
    new EndpointAddress("https://webservices.amazon.com/onca/soap?Service=AWSECommerceService"));

// add authentication to the ECS client
client.ChannelFactory.Endpoint.Behaviors.Add(new AmazonSigningEndpointBehavior("ItemSearch", accessKeyId, secretKey));

There are three changes from our original console program:

1. The binding constructor now takes a BasicHttpSecurityMode.Transport argument. This forces an HTTPS connection. The Amazon web service refuses to accept authenticated requests over plain HTTP.
2. The endpoint address starts with “https:” instead of “http:”. The remainder of the URL did not change.
3. An instance of our endpoint behavior class is added to the client’s channel factory. This ensures that our message inspector will get plugged in when the client creates new connections, and will get to sign outgoing SOAP messages.

That’s it.

This is all that’s required to get your WCF based Amazon Product Advertising API application to send authenticated requests. If you build and run the application now, your console should list 10 book titles returned from the service.

Worked for you? Didn’t work? Let us know in the comments!

Read part 2.