Authentication Process

App Directory SDK

Authentication Process (v2.0, current)

Most Apps intend to provide user-specific content and interaction capabilities. Before you implement authentication, your App will be agnostic of the Hootsuite user that is using it. This page describes techniques to authenticate a Hootsuite user with your App.

Note that this technique does NOT provide a method to authenticate with external service providers. It is your responsibility to set up authentication with an external provider, using whichever authentication methods they support.

We require all apps to implement Single Sign-On. It tells a stream of your App which Hootsuite user is viewing it by providing a user ID. Spoofing of that user ID is prevented with the help of a hash value (security token), thus authenticating the request.

You may also choose to allow a user to log into any other user account and manually associate it with your App yourself using Single Sign-On authentication. You may offer connecting accounts from your own user base, or implement authentication with an external service provider (using whichever authentication methods they support). It is generally advisable to associate a 3rd party account with a single stream. Let's call this a per-Stream characteristic.

This per-Stream type of 3rd party account authentication has the benefit of allowing a user to connect multiple accounts at the same time, each in its own stream, without requiring installation of your App multiple times.

One of the URL parameters passed to streams is the stream's placement ID, pid. This is unique for each stream a user has added, and is useful when implementing per-Stream authentication of a 3rd party account.

Single Sign-On

A user identifier, a timestamp and a secret key (salt) shared between Hootsuite and the App Developer are hashed together using SHA-1 and passed to the app. The verification hash can be recalculated by the App Developer and compared to the one passed in. If they match, the user referred to by the identifier may be considered to be logged in.

Using this method, a third party may not spoof a verification hash without knowing the shared secret key. However, this method is vulnerable to a replay attack if an attacker is able to intercept unencrypted network traffic and view the query string. This can be mitigated by using https and by checking that the timestamp is recent (no more than 10 seconds different from the time on your server).

By default, the provided user identifier is a unique identifier that is tied to the user's Hootsuite account. 

Sample URL:

https://app.somewhere.com?i=1667985&ts=1310681657&token=231a3fb74139c74c37e9111ceb59ce02a349ef88

The App would validate these parameters as such:

$secret = 'sharedSecretABCD1234'; // defined in App configuration at hootsuite.com/developers
$user_id   = $_REQUEST['i'];
$timestamp = $_REQUEST['ts'];
$token     = $_REQUEST['token'];
if (sha1($user_id . $timestamp . $secret) == $token)
{
    echo "Successful login!";
}

URL parameters passed to App stream iframe:

lang=en
timezone=7200
pid=2823         // placement ID, unique for each stream per user
uid=1234567      // Hootsuite user ID
i=1234567        // user identifier (optionally entered by user upon App installation)
ts=1318362023    // timestamp
token=123abc...  // security token (sha1 hash)