App Directory SDK

Documentation

Authentication Process

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 these techniques do NOT provide methods to authenticate with external service providers. It is your responsibility to set up authentication with an external provider, using whichever authentication methods they support.

To decide which type of authentication suits your needs best, consider the following characteristics:

  • Single Sign-On 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.
  • OAuth does the same thing Single Sign-On does, but instead of passing a user ID and a hash value, it passes a session ID (Session Token) that was previously negotiated between HootSuite and your App. On top of that, during installation of your App the user is required to log into their account that exists in your own user base, and you'll need to store their account ID (in order to match it to the Session Token when viewing streams). The entered account ID is thereby associated with the installation of your App.

Consequently, OAuth is useful if you want to connect a user of your own user base with your App, but also requires the user to install your App multiple times if they wish to connect multiple accounts. Let's call this a per-App characteristic.

Of course, you can also choose to allow a user to log into any other user account and manually associate it with your App yourself while using Single Sign-On authentication. Connecting a user account in this way is entirely up to you. You may offer connecting accounts from your own user base, or implement authentication with an external service provider (using whichever authentication methods they support). Regardless of whether it's the former or the latter, let's call them 3rd party accounts for the ease of this document. Now keep this in mind: If you were to associate a 3rd party account with your App in a per-App way similarly to the OAuth characteristic described above, you would potentially be causing issues due to the fact that a user can add streams of your App multiple times, and it would be impossible for you to reflect the current authentication state in every stream after a user completes de/authentication of their 3rd party account within one of the streams. Therefore it is generally advisable to associate a 3rd party account with a single stream instead. Let's call this a per-Stream characteristic.

This per-Stream type of 3rd party account authentication also 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.

By default, the provided user identifier is a unique identifier that is tied to the user's HootSuite account. Alternatively, you may allow the user to enter an identifier (email address, username, etc.) to be passed to your App. This however should only be used if the data shown by your App is of public nature, as any user could input the email address of another user.

Sample URL:

The App would valide these parameters as such:

URL parameters passed to App stream iframe:

OAuth

Setting up OAuth authentication requires comprehensive knowledge of the OAuth architecture as you're required to implement a "Service Provider" endpoint according to OAuth specifications, as outlined in the flowchart below. While this takes more time to set up than Single Sign-On authentication, the main benefits include higher security as well as a more seamless user experience as the user is asked to log into your App when installing it.

HootSuite uses a standard OAuth implementation, with the addition of an extra step where HootSuite retrieves a session ID from the App's Authentication Endpoint (using an OAuth-authenticated fetch). You will need to implement this Authentication Endpoint on top of the OAuth "Service Provider".

The flowchart below outlines the authentication procedure, starting with the standard OAuth process that is triggered when a user installs the App, through access token validation by the Authentication Endpoint, and ending with the user being logged into the App.

HS-OAuth

Authentication Endpoint

The first time an App stream is opened, no Session Token is passed because HootSuite has none on file yet. At that point the App should call hsp.startAppTokenAuth() to trigger HootSuite to request a Session Token from the App's Authentication Endpoint. Once HootSuite has received the token, it reloads the App stream, this time passing the token, which in turn is validated by the App. If it is the same as the one provided by the Authentication Endpoint, it's safe to consider the user authenticated.

Another way to think of this process is that the Token Exchange step is using OAuth to log a user into your site. You generate a session ID as you would for any other user login action but instead you pass it to HootSuite, which can send it along when the app is loaded to identify the currently logged in user.

In more detail:

  • HootSuite user loads the App stream, the App is loaded from the App provider's server, no auth credentials are passed through.
  • The App notices that there is no user session and that no auth credentials were passed, displays a "Logging in" message and makes the hsp.startAppTokenAuth() javascript call which will start a session token exchange.
  • A request is made on the backend from HootSuite's servers to the App's Authentication Endpoint, which verifies the OAuth tokens and returns a session ID.
  • The App iframe is reloaded, this time passing in the session ID. The app validates the session ID and uses it to start a user session.

HootSuite will keep passing the Session Token it has on file every time an App stream is loaded. It us up to the App developer to decide how long a Session Token should be valid for. If your App considers a session to be expired or otherwise invalid, hsp.startAppTokenAuth() should be called again to trigger the creation of a new Session Token.

Access Token Validation

The App's Authentication Endpoint should validate an Access Token as laid out in the OAuth specifications and return a JSON-encoded string containing a 'session_token':

{"result":"success","session_token":"abcd1234"}

Or, if a token could not be validated:

{"result":"fail","reason":"Some error message"}

If the credentials passed in to the Authentication Endpoint are invalid, the App may instruct HootSuite to open the user's "edit app" dialog using the hsp.editAppAuth() function call, which lets the HootSuite user enter new credentials or restart the OAuth process.

For a list of links to OAuth implementations in various languages (many of which include code that can be used to create a OAuth Provider) take a look at http://oauth.net/code/