Authentication

Most Apps are intended to provide user-specific content and interaction capabilities. Before you implement authentication, your App will be Hootsuite-user agnostic. This page describes techniques to authenticate a Hootsuite user with your App.

Note: 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 (SSO). SSO 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 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 type of authentication a per-Stream characteristic.

The 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 iterative reinstallation of your App. One of the URL parameters that is 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-512 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 risk can be mitigated by using https and by checking that the timestamp is recent (no more than 10 seconds difference from the time on your server). The timestamp must also be in seconds. When retrieving the timestamp, use var timestamp = Math.floor(Date.now() / 1000) to convert milliseconds to seconds.

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

https://app.somewhere.com?uid=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['uid'];
$timestamp = $_REQUEST['ts'];
$token     = $_REQUEST['token'];
if (sha512($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
ts=1318362023    // timestamp
token=123abc...  // security token (sha512 hash)

Authentication


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.