Skip to content
This repository

A demonstration of how to use BrowserID.

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 scripts
Octocat-spinner-32 server
Octocat-spinner-32 static
Octocat-spinner-32 .awsbox.json
Octocat-spinner-32 .gitignore
Octocat-spinner-32 Procfile
Octocat-spinner-32 README.md
Octocat-spinner-32 package.json
README.md

MyFavoriteBeer.org - A BrowserID example site

This is a simple site that demonstrates how BrowserID can be used to build a better login experience for users.

Overview

BrowserID is a distributed system that allows users to use their email address as login name and password. The cryptography which allows users to prove that they own an email address without site specific passwords is described in depth in the how browserid works blog post. For website owners, there is a three step tutorial that helps you integrate browserid as fast as possible.

This repository goes into greater depth than the tutorial, and provides a full working example of a small but complete website that uses BrowserID for authentication. This code is running at myfavoritebeer.org.

The Implementation

MyFavoriteBeer is a simple site that allows a user to log in and store a single string of information, their favorite beer. The site consists of a static HTML frontend (code under static/), and a simple web services API implemented by a node.js server (code under server/).

The API

The web services api exported by the node.js server consists of the following:

  • /api/whoami - reports whether the current session is authenticated
  • /api/login - accepts a browserid assertion to allow the user to authenticate
  • /api/get - returns the current user's favorite beer
  • /api/set - sets the current user's favorite beer
  • /api/logout - clears the current session

Further documentation of these calls is available in the source code.

Authentication

The most interesting part of this example is how authentication occurs. Client code includes the browserid javascript include file, and upon a user clicking the sign-in button, navigator.id.getVerifiedEmail() is invoked. BrowserID returns a string which contains an assertion. This assertion is passed up to the myfavoritebeer server via the /api/login api. The server verifies this assertion using the free verifier service by POSTing to https://browserid.org/verify. Finally, upon successful verification, the server sets a cookie which represents an authenticated session.

Sessions

For simplicities' sake, "sessions" in this example are implemented using a third party library which encrypts session data using a private key and stores this data in a cookie on the user's browser. This approach makes it so the server doesn't need to store any data to implement sessions and keeps the example simple.

Persistence

We have to store the beer preferences somewhere. mongodb is used for this purpose and a very simple database abstraction layer exists in db.js. The details of interacting with the database aren't important, but if you're curious have a look in db.js.

Run it!

To run the example code locally:

  1. clone this repository
  2. install node (0.6.5+) and npm.
  3. npm install
  4. PORT=8080 npm start

Now open http://127.0.0.1:8080 up in your web browser.

NOTE: You'll see warnings about how no database is configured. Don't worry about it. The code is designed to run with or without a configured database so that it's easier to play with. The only downside of running without a database is that your server won't remember anything. Oh well.

Deployment

The code is designed to run on heroku's node.js hosting services, and the only way this affects the implementation is via environment variable naming choices and the presence of a Procfile which tells heroku how to start the server.

If you'd like to deploy this service to heroku yourself, all you'd have to do is:

  1. set up a heroku account (and run through their tutorial)
  2. create a heroku instance running nodejs 0.6: heroku create --stack cedar --buildpack http://github.com/hakobera/heroku-buildpack-nodejs.git <appname>
  3. add a free mongolab instance (for persistence): heroku addons:add mongolab:starter
  4. set your app to bind to all available ips: heroku config:add IP_ADDRESS=0.0.0.0
  5. set a random string to encrypt cookies: heroku config:add SEKRET=<long random string>
  6. push the code up to heroku: git push heroku master

NOTE: While the sample is targeted at heroku, with minimal code modifications it should run under the hosting environment of your preference.

Credit

Concept + Design(kinda): http://myfavouritesandwich.org/ Art: http://www.flickr.com/photos/bitzi/236037776/

Something went wrong with that request. Please try again.