backbone.simple-auth

A basic cookie-based client-side auth service for Backbone apps.

Motivation

Some client-side apps need to send a token stored in a cookie along with each request to an API under the Authorization header. This library manages that for you.

It also provides a central location for your app to determine if the user is authenticated or not.

When should I use this library?

• Your application stores authenticated user tokens in cookies
• Your API follows the Bearer Token spec for the Authorization header. Github's API is an example of an API that accepts this format.

Dependencies

Other than Backbone (and Backbone.$), this library depends on Cookies. Don't worry – it's only 1kb.

Basic Usage

Your server should be configured to set the authentication token as a cookie. When that happens, and your app loads...

// Load up the module
var Auth = require('backbone.simple-auth');
 
// Create a new instance of auth. If the cookie with the given
// name exists, then `auth` will set the value of the `Authorization` HEADER
// for future AJAX requests to be `Bearer COOKIE_VALUE`
auth = new Auth({
  cookieName: 'user-token'
});
 
// Returns true if the cookie exists
auth.get('authenticated');
 
// Get the token
auth.get('token');
 
// Destroy the cookie
auth.logout();

That's all there is to it.

Attributes

Auth is a Backbone Model. As such, you can use the Model API when interacting with it. There are three attributes on Auth:

cookieName

The name of the cookie to search for the token on. Defaults to token.

authenticated

A boolean representing whether or not the user is authenticated. Defaults to false.

token

The value of the token. Defaults to undefined.

API

determineAuth()

Searches for a cookie with the same name as auth.get('cookieName'). If it exists, then its value is assumed to be the token, and the user is set to be authorized.

This is called when auth is first created. You may also wish to call it later if your application allows for logging in on the client.

If the cookie is found, the authenticated event is triggered.

logout()

If the user is logged in, then the cookie will be destroyed. The value of authenticated is set to false, and the value of token is set to undefined. Lastly, the logout event is triggered.

Events

authenticate

The user has logged in. Called when auth is first loaded. The value of the token is passed as the first argument.

logout

The user has been logged out.

FAQ

How do I log the user in from the client?

This library does not handle creation of cookies containing auth tokens, because there are so many ways to accomplish such a task. You will need to build your own system to generate the token. Once you've done that, and you can generate a token for authenticated users, then you must set it as the cookie. Once that is done, call auth.determineAuth() to notify the auth model that the user is logged in.

Is this library secure?

It might seem strange that this library considers a user authenticated if there is any value stored in the cookie. As surprising as it may seem, this is not a security concern. The fact is that there is simply no way for the client to be certain that the user really is authenticated. At most, you can make an educated guess. Even a token that once authenticated the user could be remotely revoked at any time.

In this light, assuming that the user is unlikely to tamper with cookies is a reasonable assumption to make.

These assumptions are always checked against the API whenever sensitive data is requested. Consequently, even a user who does mess with the cookies, or otherwise has an invalid token, will be unable to access any sensitive data. At most, they will see an empty UI interface.

Contributing

Unit tests

In Node

Run gulp to execute the test suite in Node.

In the browser

Run gulp test:browser to start a server. Then, navigate to http://localhost:7777/test/runner.html to run the suite.

Building the library

gulp build