Components of an OAuth 1 Signature

As you’ve seen in the preceding chapters, we will use HTTP Headers to identify our clients to a server. Before proceeding, you should be familiar with the concepts in Chapter 1, specifically with how HTTP Headers work. While that chapter will not make you an HTTP expert, it provides enough information and concepts needed to understand this chapter.

The header we’re going to be paying particular attention to is the Authorization header. This header must be constructed correctly for an OAuth Server to be able to work with our requests. The Authorization header contains all the pertinent information needed to identify ourselves to the third-party service our client is trying to access. The Authorization header has a number of different components we will look at in detail. Knowing these will help you understand how to generate and use the components to create a valid OAuth request.

Let’s get started by taking a look at the components of the Authorize header needed to create an OAuth Request. We’ll start at the simple items and then move on to the more complex ones.

Understanding Tokens

In the last section I introduced the concept of tokens, in this section we are going to explore them in depth. Tokens are used to identify a user or application to the OAuth server. Using tokens to identify a user eliminates the need to provide a username and password in the API call.

The tokens come in pairs, one part being a public token and the other a secret token. As the name implies, the secret token is to be kept a secret and is not transmitted with OAuth requests. Since both tokens are required to properly identify a user and the public access token is more easily discovered, it’s very important to protect the secret key and store it securely.

Securing tokens can be achieved with a couple simple practices. The first practice is to avoid committing the values of the key, token, and secrets to your version control system. Even if you are using a private repository, there is no way of knowing whether the repository will remain private, so it’s best practice to avoid committing the values. The second practice is avoid storing any files with these values in a publicly accessible location. If the values can be accessed through a web browser or through local storage in a browser, an attacker may be able to find these values and make requests on your behalf. Lastly, while you have to send the access token and consumer key in the Authorization header, it’s important to never send the secret values in plain-text via an HTTP Request. Later in this chapter we’ll be covering the composite key and its role in protecting the secret values from being sent in plain-text. I have found phpdotenv1 to be a great method of storing these values.

Tokens are provided by the third party service when a user authenticates and grants permission for the application to access their information. The service will essentially “connect” the local user account to the tokens. Since we have the ability to grant access to the API application, we also have the ability to revoke access. The application is identified by a different public/secret token combination which allows you to manage what applications have access to your account on the third party service. This is also the mechanism which allows for the revocation of applications.

The other important concept to understand with tokens is they are designed to have a relatively short life. Tokens are regenerated with each authentication call, so if the tokens aren’t maintained by the application using them, they will be new for each session. It is generally a good idea to take advantage of this characteristic, as it provides an additional layer of security for your account. Think of it as changing your password before every single login–that’s essentially what is happening and it makes it more difficult for attackers to fixate on an account. While there are still the same concerns with the account on the third party service, it helps prevent your information from being compromised by another application or API. It is very important to use strong passwords and utilize secure practices for storing your credentials regardless of how they are being used.

Understanding the Signature

The most difficult aspect of making an OAuth request is signing the request. If this step is done incorrectly, it will cause any HTTP request sent to the API to be rejected with a 401/Unauthorized status. Another confusing aspect is certain services require the components of the Authorization header to be in alphabetical order (Twitter, for example) while other services don’t require any particular order. This can be especially confusing when trying to make a request for the first time. Ideally, you should understand exactly what the OAuth server is expecting to receive, but it’s usually safe to alphabetize the components by default. That way, your client generates requests any service will accept.

There are a few sub-components of the signature we’ll want to define because they are vital to properly signing the requests. Understanding how these are generated will provide a better understanding of how all tokens and components of the Authorization header are used.

<?php
// values for all the headers
$authorization_header_values = [
    'oauth_nonce' => $nonce,
    'oauth_callback' => $callback,
    'oauth_signature_method' => 'HMAC-SHA1',
    'oauth_timestamp' => time(),
    'oauth_consumer_key' => $consumer_key,
    'oauth_token' => $token,
    'oauth_version' => '1.0'
];

// if there is no callback, don't send it
if (!isset($callback) || $callback === '') {
    unset($authorization_header_values['oauth_callback']);
}

// build the base string and sort the
// authorization header values alphabetically by key
$temp_array = array();
ksort($authorization_header_values);
foreach ($authorization_header_values as $key => $value) {
    $temp_array[] = $key . '=' . rawurlencode($value);
}

// unpack the values that we stored in the temporary array
$parameters = rawurlencode(implode('&', $temp_array));

<?php
// values for all the headers
$authorization_header_values = [
    'oauth_nonce' => $nonce,
    'oauth_callback' => $callback,
    'oauth_signature_method' => 'HMAC-SHA1',
    'oauth_timestamp' => time(),
    'oauth_consumer_key' => $consumer_key,
    'oauth_token' => $token,
    'oauth_version' => '1.0'
];

// if there is no callback, don't send it
if ($callback === '') {
    unset($authorization_header_values['oauth_callback']);
}

// build the base string
$temp_array = array();
ksort($authorization_header_values);

$parameters = rawurlencode(http_build_query($authorization_header_values));

$base_string = 'GET&' . rawurlencode($endpoint) 
             . '&' . $parameters;

GET&https%3A%2F%2Fapi.twitter.com%2F1.1%2Fstatuses%2F
user_timeline.json&count%3D2%26oauth_consumer_key%3D
Ruk5McRjIKd2DP22n3afjw%26oauth_nonce%3Dd303edff00aaaad160688
d8acab54bc6%26oauth_signature_method%3DHMAC-SHA1%26
oauth_timestamp%3D1445350048%26oauth_token%3D162aaaaa-yZJSlF
ednBab8zFJDZvSQ9AEDicAW2aHKcaHiBUaJ%26oauth_version%3D1.0%26
screen_name%3Dtwitterapi

$composite_key = rawurlencode($consumer_secret) . '&' .
                 rawurlencode($access_secret);

$signature = base64_encode(
   hash_hmac('sha1', $base_string, $composite_key, true)
);

Understanding the Nonce

We have familiarized ourselves with tokens and understand how to build the OAuth signature, but there still might be a word that looks unfamiliar. What exactly is a nonce? According to Webster’s Dictionary it is “a word or expression coined for or used on one occasion”. In the programming world, we’d call it a string and the rest of the definition fits the bill. It’s a string which is passed along with the request and is only used once. This means that every single request you send has a unique, unpredictable nonce.

In practice, this is a randomly generated hash and it’s used to protect from replay attacks. So while the word looks funny, there’s really not much to it. All you really need to remember is you shouldn’t use the same nonce value more than once.

To generate a nonce we need to generate a random string of characters and then hash them. There are some different techniques for doing this, below is one example.

$bytes = openssl_random_pseudo_bytes(16);
$string = bin2hex($bytes);
$nonce = hash(sha512, $string);
var_dump($nonce);

Will produce a nonce like:

string(128) "9e23987cf0da2f907d0eda3779bd5d4539a40d7904338c8
f198ec4a37f62a415444653e6a443aeb4f271c1f892d8b6fe0d2246fbfe7
78e5359c6b9626b6b71c2"

Forming a Valid OAuth 1.0 Request

We’ve dissected the components of an OAuth 1.0 request and should have a little bit more simplified view of how these requests are made. By taking the individual components apart, what once seemed really complex now seems a bit more realistic to grasp. How do we tie this all together? The following example is going to be an implementation of a class building an OAuth 1.0 request. For clarity’s sake, I’m going to comment the code in a way which explains what I’m doing. This example is going to be a call to a fake API with made-up tokens. Without further delay, let’s look at our classes.

Listing 3.3 shows a basic class for holding our consumer information. This will hold the token and secret generated when we register our application with an external service.

Listing 3.3

<?php
/**
 * Class to hold our Consumer information
 */
class OAuthConsumer
{
   /**
    * Consumer token
    * @var string $token
    */
   public $token;

   /**
    * Consumer secret
    * @var string $secret
    */
   public $secret;
}

We also need a class to store access information returned when a user grants us access.

Listing 3.4

<?php
/**
 * Class to hold our access information
 */
class OAuthAccess
{
   /**
    * Access Token
    * @var string $token
    */
   public $token;

   /**
    * Access Secret
    * @var string $secret
    */
   public $secret;
}

Next, the OAuthHeader class in Listing 3.5 does the hard work of building our Base String, Authorization header, and the signature for our request.

Listing 3.5

<?php
/**
 * Class to build our OAuth Headers
 */
class OAuthHeader
{
   /**
    * Callback value, if any
    * @var string $callback
    */
   protected $callback = '';

   /**
    * Value for the nonce
    * @var string $nonce
    */
   protected $nonce;

   /**
    * Request URL
    * @var string $request_url
    */
   protected $request_url;

   /**
    * HTTP Verb
    * @var string $http_verb
    */
   protected $http_verb;

   /**
    * Consumer Object
    * @var OAuthConsumer $consumer
    */
   protected $consumer;

   /**
    * Access Object
    * @var OAuthAccess $access
    */
   protected $access;

   /**
    * Constructor for OAuthHeader
    * @param OAuthConsumer $consumer
    * @param OAuthAccess $access
    */
   public function __construct(OAuthConsumer $consumer,
                               OAuthAccess $access) {
      $this->consumer = $consumer;
      $this->access = $access;
   }

   /**
    * Accessor method to set the nonce
    * @param string $nonce
    */
   public function setNonce($nonce) {
      $this->nonce = $nonce;
   }

   /**
    * Accessor method to get the nonce
    * @return string
    */
   public function getNonce() {
      return $this->nonce;
   }

   /**
    * Accessor method to set the verb
    * @param string $verb
    */
   public function setHTTPVerb($verb) {
      $this->http_verb = $verb;
   }

   /**
    * Accessor method to get the verb
    * @return string
    */
   public function getVerb() {
      return $this->http_verb;
   }

   /**
    * Accessor method to set request url
    * @param string $request_url
    */
   public function setRequestURL($request_url) {
      $this->request_url = $request_url;
   }

   /**
    * Accessor method to get request url
    * @return string
    */
   public function getRequestURL() {
      return $this->request_url;
   }

   /**
    * Accessor method to set the callback
    * @param string $callback
    */
   public function setCallback($callback) {
      $this->callback = $callback;
   }

   /**
    * Accessor method to get the callback
    * @return string
    */
   public function getCallback() {
      return $this->callback;
   }

   /**
    * Method to organize the values that will make up
    * the authorize header
    * @return array
    */
   protected function setHeaderInfo() {
      $authorize_params = array(
         'oauth_nonce' => $this->getNonce(),
         'oauth_callback' => $this->getCallback(),
         'oauth_signature_method' => 'HMAC-SHA1',
         'oauth_timestamp' => time(),
         'oauth_consumer_key' => $this->consumer->token,
         'oauth_token' => $this->access->token,
         'oauth_version' => '1.0'
      );

      if ($this->callback == '') {
         unset($authorize_params['oauth_callback']);
      }
      return $authorize_params;
   }

   /**
    * Method to buid the base string for the signature
    * @param array $authorize_params
    * @return string
    */
   protected function buildBaseString($params) {
      $temp_array = array();
      ksort($params);
      foreach ($params as $key => $value) {
         $temp_array[] = $key . '=' . rawurlencode($value);
      }

      return $this->http_verb . '&'
      . rawurlencode($this->request_url) . '&'
      . rawurlencode(implode('&', $temp_array));
   }

   /**
    * Method to build the composite key for the signature
    * @return string
    */
   protected function buildCompositeKey() {
      return rawurlencode($this->consumer->secret) . '&'
      . rawurlencode($this->access->secret);
   }

   /**
    * Method to construct the authorization header
    * @param array $params
    * @return string
    */
   protected function buildAuthHeader($params) {
      $header_prefix = 'Authorization: OAuth ';
      $values = array();
      foreach ($params as $key => $value) {
         $values[] = $key . '=' . rawurlencode($value);
      }
      $header_contents = implode(',', $values);
      return $header_prefix . $header_contents;
   }

   /**
    * Method to build the signature
    * @param string $base_string
    * @param string $composite_key
    * @return string
    */
   protected function buildSignature($base_string,
                                     $composite_key) {
      return base64_encode(hash_hmac('sha1',
         $base_string,
         $composite_key,
         true
      ));
   }

   /**
    * Method to return the entire OAuth Request header
    * ready to use
    * @return string
    */
   public function getAuthorizationHeader()    {
      $params = $this->setHeaderInfo();
      $base_string = $this->buildBaseString($params);
      $composite_key = $this->buildCompositeKey();
      $sig = $this->buildSignature(
         $base_string, $composite_key
      );
      $params['oauth_signature'] = $sig;
      return $this->buildAuthHeader($params);
   }
}

So there we’ve knocked a pretty straight-forward implementation which will generate the full authorization header for us. Is this perfect? Probably not, but as you can see the intent was to demystify the process of making an OAuth request yourself. As I stated earlier on, it’s always a great idea to use something tried and true. I mean, if it works correctly, there’s no sense in reinventing it, right?

This chapter explained the details of what’s actually happening when an OAuth request is made. If for some reason the need exists to recreate an OAuth request class, you now understand how this process flows. This wouldn’t be complete without an example of how to execute this code, so let’s take a look at Listing 3.6 to see how to execute this and what the resulting output looks like.

Listing 3.6

<?php
include_once __DIR__ . '/listing.3.3.php';

$consumer = new OAuthConsumer();
$consumer->token = 'ab234efdce1294856';
$consumer->secret = 'b77462342fdedfeaefe23423434310098';

$access = new OAuthAccess();
$access->token = '1efe342faade88421';
$access->secret = 'ccfedb764234094234212defe';

$headers = new OAuthHeader($consumer, $access);
/**
 * There would generally be a method that generates this
 * for you or building the headers would generate a new
 * nonce, doing it this for simplicity.
 */
$headers->setNonce('bfefacdede123213');
$headers->setHTTPVerb('GET');
$headers->setRequestURL(
   'https://api.example.com/v1/user/bcdef12345'
);
$header = $headers->getAuthorizationHeader();
print $header;

You can see this listing provides a relatively straight-forward interface for using this class. What happens when you run it? You should get output similar to the following (as a single string):

Authorization: OAuth oauth_nonce=bfefacdede123213,
oauth_signature_method=HMAC-SHA1,oauth_timestamp=1389156921,
oauth_consumer_key=ab234efdce1294856,
oauth_token=1efe342faade88421,oauth_version=1.0,
oauth_signature=3Ey74KvTkPjyVqodd3GtLX%2BlHPs%3D

You see a full OAuth Authorization header ready for you to use!