Protocols/WebAPI/Auth/Client/Signing Requests

WebAPI Protocol

Basic

Introduction

Clients

Whimsicals

Host Interaction

Flow

Authentication

• Client

• WebApp

Other Services

•

Foodgroups

This page is about Signing Requests for WebAPI Client authentication.

Even though the 'clientLogin' request itself doesn't need to be signed, all subsequent requests (both OpenAuth requests and any other protected resources like WebAIM) made using the authentication token obtained using 'clientLogin' request "must" be signed.

Instead of defining yet another request signing method, we support the request signing method to generate the "Signature Base String" as defined in the 'OAuth' protocol. The OAuth Signature Base String is documented here. Here we document how to generate and use the same Signature Base String for signing requests using 'clientLogin' tokens.

Please note that we are using the OAuth Signature Base String only, and not adopting the OAuth parameter naming convention. The Session Key generated using the user's password and the session secret returned by 'clientLogin' method should be used as the Key while generating the HMAC-SHA256 of the Signature Base String.

The Signature Base String is a consistent reproducible concatenation of the request elements into a single string. The string is used as an input in hashing or signing algorithms. It consists of 3 parts of information - the HTTP Method used, the Request URI, and the request parameters itself.

All the request parameters MUST be encoded as described in Parameter Encoding prior to constructing the Signature Base String.

Step 1: Normalize Request Parameters

The request parameters are collected, sorted and concatenated into a normalized string:

• Parameters in the OAuth HTTP Authorization header excluding the realm parameter.
• Parameters in the HTTP POST request body (with a content-type of application/x-www-form-urlencoded).
• HTTP GET parameters added to the URLs in the query part (as defined by RFC3986 section 3).

The sig_sha256 parameter MUST be excluded.

The parameters are normalized into a single string as follows:

1. Parameters are sorted by name, using lexicographical byte value ordering. If two or more parameters share the same name, they are sorted by their value. For example:

     a=1, c=hi%20there, f=25, f=50, f=a, z=p, z=t

1. Parameters are concatenated in their sorted order into a single string. For each parameter, the name is separated from the corresponding value by an '=' character (ASCII code 61), even if the value is empty. Each name-value pair is separated by an '&' character (ASCII code 38). For example:

     a=1&c=hi%20there&f=25&f=50&f=a&z=p&z=t

Step 2: Construct Request URL

The Signature Base String includes the request absolute URL, tying the signature to a specific endpoint. The URL used in the Signature Base String MUST include the scheme, authority, and path, and MUST exclude the query and fragment as defined by RFC3986 section 3.

If the absolute request URL is not available to the Service Provider (it is always available to the Consumer), it can be constructed by combining the scheme being used, the HTTP Host header, and the relative HTTP request URL. If the Host header is not available, the Service Provider SHOULD use the host name communicated to the Consumer in the documentation or other means.

The Service Provider SHOULD document the form of URL used in the Signature Base String to avoid ambiguity due to URL normalization. Unless specified, URL scheme and authority MUST be lowercase and include the port number; http default port 80 and https default port 443 MUST be excluded.

For example, the request:

                 http://example.com/resource?id=123

Is included in the Signature Base String as:

                 http://example.com/resource

Step 3: Concatenate Request Elements

The following items MUST be concatenated in order into a single string. Each item is encoded and separated by an �&� character (ASCII code 38), even if empty.

1. The HTTP request method used to send the request. Value MUST be uppercase, for example: HEAD, GET , POST, etc.
2. The request URL from Step 2 above.
3. The normalized request parameters string from Step 1 above.

Step 4: Generating Signature

sig_sha256 is set to the calculated digest octet string, first base64-encoded per RFC2045 section 6.8, then URL-encoded per Parameter Encoding.

Example:

This example uses the OpenAuth "getInfo" request to show how to generate the signature.

Sample getInfo request:

https://api.screenname.nina.bz/auth/getInfo?a=tokendata&clientName=test%20Client&clientVersion=1&f=xml&k=developerkey&ts=1200858745

To generate the signature for this request, it first needs to generate the Signature Base String. The request contains the following parameters which are ordered and concatenated into a normalized string:

• a=tokendata
• clientName=test%20Client
• clientVersion=1
• f=xml
• k=developerkey
• ts=1200858745

The following inputs are used to generate the Signature Base String:

1. GET
2. https://api.screenname.nina.bz/auth/getInfo
3. a=tokendata&clientName=test%20Client&clientVersion=1&f=xml&k=developerkey&ts=1200858745

The Signature Base String is:

GET&https%3A%2F%2Fapi.screenname.nina.bz%2Fauth%2FgetInfo&a%3Dtokendata%26clientName%3Dtest%2520Client%26clientVersion%3D1%26f%3Dxml%26k%3Ddeveloperkey%26ts%3D1200858745