This plugin enables access to remote resources which are protected by HTTP Basic Authentication through your Backbone Models and Collections.
You can set Basic Authentication credentials in two ways:
- Via a separate model/collection property:
credentials
. - Directly on the model/collection
url
property.
If you are unsure which mode to pick, use the credentials
property on the model.
Usage:
var Model = Backbone.Model.extend({
url: 'http://path/to/basic/auth/protected/resource'
});
var model = new Model();
model.credentials = {
username: 'user',
password: 'pass'
};
// or ...
model.credentials = function() {
return {
username: 'user',
password: 'pass'
};
};
model.fetch();
This mode is good for authentication that may change when the app is used, e.g. if different users are able to authenticate with the app. The credentials can be hard coded or set dynamically.
This mode is the most flexible. If you are unsure which mode to use, try this one first.
Usage:
var Model = Backbone.Model.extend({
url: 'http://username:password@path/to/basic/auth/protected/resource'
});
var model = new Model();
model.fetch();
This mode is good for models where the username/password is unlikely to change, e.g. a fixed API key for your app. The plugin takes care of parsing the URL to create the necessary Basic Authentication header, and jQuery removes the credentials from the URL so your username and password isn't sent to the server directly on the URL.
Thanks goes to Luis Abreu for his work implementing this.
A resource protected with HTTP Basic Authentication requires the following HTTP header to be set on every request:
Authorization: Basic <accesstoken>
The access token is formed by taking the username and password, concatenating together with a :
separator and encoding into Base64.
This plugin handles the Base64 encoding and automatically sets the Authorization
header on every request which uses Backbone.sync
.
On occasion, it can be useful to bypass Backbone.sync
and use raw $.ajax
(for example, when hitting server API resources which do not conform to RESTful principles). More information on this subject can be found in this excellent blog post by Derick Bailey.
If you need/want to do this, there is a convenience function which will help you build the BasicAuth header: Backbone.BasicAuth.getHeader()
, which can be used to create the header to be set directly on the AJAX request.
Example:
// Pass the credentials to the plugin to build the header
$.ajax({
method: 'GET',
dataType: "json",
url: 'http://path/to/basic/auth/protected/resource',
headers: Backbone.BasicAuth.getHeader({
username: 'user',
password: 'pass'
})
});
- Backbone
- Underscore or Lodash
- JavaScript
btoa()
function (a polyfill is available ifbtoa()
is not supported in your target browser)
The idea of this plugin is to adhere to the standard HTTP Basic Authentication scheme. There is bound to be a 'basic' way to read the username / password combination in your chosen server-side language.
- Re-introduced concept of setting Basic Auth credentials from a function, in addition to URL-based method.
- Moved to use the standard method of HTTP Basic Authentication, by adding
username:password
to the URL string. The old method of setting the Basic Auth token (Backbone.BasicAuth.set
/Backbone.BasicAuth.remove
) has now been removed from the codebase. Thanks to Luis Abreu for the PR. - Added AMD support (thanks again Luis Abreu).
- Added Bower support.
Copyright 2013, Tom Spencer (@fiznool), Luis Abreu (@lmjabreu).
backbone.basicauth.js may be freely distributed under the MIT license.