BrowserID: Logging in with BrowserID, Passport and NodeJS

BrowserID is a hot new way of signing in to your favorite web applications without the need of typing in your password for each website. It lets users sign in once through BrowserID and then use different websites that use BrowserID without typing in their details again and again (a quick guide is located here). This NodeJS service, soon to be renamed Mozilla Persona, is super easy to implement with a lightweight authentication module called Passport. For this tutorial, we’ll go through a whirlwind tour of BrowserID and Passport and hopefully, this will show you just how easy it is to use BrowserID in your application. This tutorial is uploaded as a Github Gist and is located here if you want to have a look at the code as a whole.

1. Setting Up

The easiest way to start a NodeJS project is to install NodeJS and create a file called package.json with the following:

Now, simply change directory into the directory containing the package.json file using your terminal and run npm install to install all the dependencies in this file. Notice that Passport is located in two modules. This allows Passport to be very slim since we only need to include the particular system of authentication that we are using, called a ‘strategy’. In this case, it’s ‘passport-browserid’ which is the module required for BrowserID but there are many more strategies available (see the full list here).

Next, we create a file called server.js :

require('coffee-script');
require('./main');

This file is simple. It loads the CoffeeScript module and then the main part of the code, which will be located on a CoffeeScript file called ‘main.coffee’. The CoffeeScript module allows you to simply require ‘.coffee’ files throughout the NodeJS app without using the extension and will compile them on-the-fly when you run ‘node server’

2. Passport Up!

The bulk of the code, as you may have guessed is contained within the main.coffee file. This is quite a complex script at first but we will go through it bit by bit:

Variables

These are pretty straightforward. We use the require function to include the Express framework, the Passport module and the BrowserID strategy. Note that the actual method of the BrowserID strategy that contains the class needed is ‘.Strategy’. Immediately after including the Express framework, we call on the createServer() function of Express which creates the application.

Passport Serialize and Deserialize Functions

To ensure that the server knows that a user is logged in as the user moves from page to page, the user’s browser is required to keep a string of characters in a cookie that is unique and identifiable to that user. This information is sent to the server each time a request is made so that the server knows who to send privileged information to but it must be serialized, or encoded before being sent to avoid misuse. Passport requires the developer to provide the necessary functions to ‘serialize’ and ‘deserialize’ this cookie with the session secret (see below) so that the information is kept safe on the client’s computer. This just means providing the done function with the email in the serializeUser function and checking the email matches with the done function in the deserializeUser function.

Passport-BrowserID Strategy

This is the major Passport function that contains the BrowserID strategy. Firstly we set the namespace of this strategy to ‘browserid’, which we will use later and then we create a new instance of the BrowserID class. This class requires an ‘audience’ variable and a verification function.

• The audience variable is used by BrowserID to identify the requesting party, which is your application. This should contain the website you are calling BrowserID from.
• The verification function ensures that the user requested is valid on both ends. It checks that the user activated from BrowserID is the same as the one in your database, or one that you have just created in your database. However, in the example code above, it just passes the done function with the same email straight back but normally, database functions should be included in this function.

App Configuration and Run App

This is the standard configuration and run app lines. Of note are the session secret which is required for serializing the user information into a session ID that is placed into the User’s cookies. Ensure the configuration lines appear in that order as they are needed in this order.

Routes

This simple application will only include 2 routes but only one page:

• The first route checks if the user is authenticated through the function req.isAuthenticated(). If the user is not authenticated, the route will display the ‘index’ file which will contain the button to sign in.
• The second route activates the authentication function of the BrowserID strategy by sending a POST to ‘/login’. The authentication strategy requires at least specifying where the user should redirect on failure through the ‘failureRedirect’ but you may like to add the ‘successRedirect’ if you wish. When failureFlash is set to true, it allows the developer to show the error messages on the jade file through the variable error.

3. The Front-End

Now that the NodeJS is out of the way, it is time to create the front-end. We use two files that will put in a views folder – layout.jade (that acts as a template) and index.jade (that contains the form):

In layout, we specify a simple HTML5 template page which will include three important scripts that is placed after the main body markup: the jQuery library, the BrowserID library and the client.js script which we will write. Note that the BrowserID file is necessary in the frontend to login to BrowserID as we shall see later.

The markup in the index.jade file goes exactly where the != body is in the previous layout.jade file. This markup is simply a form which posts to ‘/login’ (which was one of our routes) with a hidden input for an ‘assertion’ variable and a login button.

The final thing to gel everything together is the client-side script, which I am neatly calling client.js, containing the following. This file should be placed in a folder called public as we have specified that all static files should be in there.

This file merely calls the function ‘navigator.id.getVerifiedEmail’ from the BrowserID file that we included before. This function activates the BrowserID process, showing a popup allowing the user to login. When the user successfully logs into the BrowserID service, the function sends back an assertion. This assertion is a password key that is sent back to the server through the hidden input with the form. The form activates the server-side process outlined above through the ‘/login’ route, completing the authentication process by verifying with BrowserID that the user has been found and logged in.

4. Running

No need to compile the CoffeeScript file, simply use the cd command to change to your director and run ‘node server’. If you see a message saying ‘Server running at port 1337′, you’ve done something right!

Now, simply point your browser to http://your-local-domain:1337 and then click on the login button that you’ve created! You should see a popup with BrowserID. From there, simply signup or login and then let BrowserID do its job. If you have been successful, you should get the message ‘Congratulations! You’ve signed in as <your email here>’.

Conclusion

BrowserID is a hot new authentication system that relieves developers of the need for complicated processes such as the OAuth system that requires the developer to deal with authentication tokens and secrets. Instead, an assertion is provided in the frontend and then the server sends it back to BrowserID to get the user information. It is a much more streamlined process that is made even simpler by the Passport-BrowserID strategy of the Passport module. This handles a lot of things for the developer, leaving more focus on the actual application itself.