You are here: Developers > OpenX Platform API > Authentication reference > About signing requests

About Signing Requests

Signing Requests

OAuth defines a method for validating the authenticity of HTTP requests. This method is called Signing Requests. Instead of sending full credentials (specifically passwords), OAuth uses digital signatures with each request. Digital signatures allow the recipient to verify that the content of the request has not changed in transit. To do that, the sender uses a mathematical algorithm to calculate the signature of the request and includes it with the request.

All of your requests must be signed using the HMAC-SHA1 hashing algorithm. The server checks your hash to make sure it matches the hash it generates. If it does, the data you sent has not been compromised. The following explains how to sign requests.

Base String

To authenticate programmatically:

  1. Create a "base string" using the "resource url" and the HTTP method (POST, GET) you will use before that:

    POST http://sso_openx.com
  2. Next, sort all of your parameters in alphabetical order. (Each request will be accompanied by a set of parameters. Each step in the process requires a different set of parameters, as described in the following sections. Alphabetically sorting them ensures that the hashing algorithm produces the same result on both Consumer and Provider sides).

  3. Add a URL-encoded equal sign and value to each parameter. For every parameter except the last one, add a URL-encoded ampersand.

  4. Add all of the parameters to the string you started in step 1.

The result is the final Base String. An example Python base string is shown below.

POST&http%3A%2F%2Fsso_openx.com%2Fapi%2Ftest.json&parama%3Dparamaval%26paramb%3Dparambval %26version%3D1.0

The parameter name and parameter value should be URL-encoded. You can build a function to handle URL encoding. Also make sure the URL itself is encoded.

Hashing

The Base String is hashed using token credentials. Token credentials are different depending on what part of the OAuth handshake you are currently performing. If you're asking for a request token, your token credentials are the Consumer secret followed by an ampersand (&) often called a "dangling ampersand". This is because you don't have a token yet, so there is no token secret.

If you have a request token and are requesting an access token, your token credentials are the Consumer secret, an ampersand (&), and the request token secret. If youÌve received authorization and can now make requests on the User's behalf, your token credentials are the Consumer secret, followed by an ampersand (&), followed by the access token secret. Whichever string is relevant to you, this string is what you apply as the key when applying the HMAC-SHA1 hashing algorithm. The Base String is the value to hash. You send your final signature to the server along with the rest of the request as the oauth_signature parameter.

URL Encoding

When you transmit special characters over the internet, they must be encoded so that they do not get misrepresented as meaningful characters. URL-encoding converts special-purpose characters such as the ampersand into hexadecimal notation based on the character's ASCII value. For instance, the ASCII value for a space ( ) character is 32. In binary, it looks like:

0010 0000

which is 0x20 in hexadecimal notation, so the URL-encoded space character is:

%20

Most language libraries, such as Python, provide a function to encode URLs.

Executing an HTTP Call

OAuth specifies three ways to send credentials:

  • On the query string (not recommended)

  • POST parameters (OK, but may have problems)

  • The authorization HTTP header (recommended)

A header is at the front of an HTTP request and gives the server information about the type of request, the length in bytes of the request, etc. For OAuth, one more header is added: "Authorization". The following shows the header. Line breaks have been inserted for readability, but when building your header, you would not include these line breaks.

Authorization: OAuth oauth_consumer_key="xxxx",
oauth_token="xxxx",
oauth_version="1.0",
oauth_signature="xxxx",
...

Feedback form