(Note: The code for this project at this point in our progress can be downloaded from Github at commit: 8a19651c576968b29f143d271147b0b288ca63a7)

Authentication and Authorization

In this installment we'll tackle some functionality that I feel many tutorials leave out - authentication. We are going to implement a simple model that will both authenticate users and determine whether they are authorized to perform a function. This implementation is not meant to be bulletproof but to get a basic workflow in place. We'll be identifying a user as an admin with permissions to delete users. In practice, I usually keep all admin type functions out of my main application. Keeping them to themselves in a purpose built app allows you to restrict the audience and enforce other security measures, such as IP whitelisting.

HTTP is a stateless transaction by default. Whether we create a server side session to track user details or not, we need some way to identify an incoming request as being made by a particular user. We will be using JSON Web Tokens to provide this identification. They will be generated by our server when a user authenticates themselves and stored in the browser's local storage. To demonstrate authorization and personalizing the interface we will also be asking the server for the user information for the currently logged in user and a set of permissions for actions they are allowed to take. We will use these permissions on the client to present a better experience for the user; we won't easily allow them to perform an action they are not authorized to perform. Ultimately, all actions will be verified on the server to prevent users from bypassing our UI restrictions.

Before we get into the code, let's take a look at the workflow of authenticating a user. Let's assume we have a home page accessible to anyone, our users page, accessible to logged in users, and the delete button accessible to anyone with Admin permissions.

We can describe our workflow in two places: the router and application wide AJAX error handling.

Here is the logic workflow we will be implementing in the router and supporting classes:

Along with these decisions, we will intercept and handle the following HTTP error codes returned by our backend:

401

The User is not Authenticated - Redirect to Login

403

The User is not Authorized - Redirect to Home

500

Generic Error Handling

So, in the case that a user has a token, but it has expired, when they go to retrieve their User object, we will return a 401 error, forcing them to login.

Creating An Admin User (The Wrong Way)

We don't want to create a full featured permissions model or management console at this point. We haven't coded any features so trying to write permissions would be premature. It would be helpful for testing and prototyping, however, to indicate that one or more of our users had a specific property. To add these permissions to a user, we are going to cheat. For our POST /api/users and PUT /api/users/:user_id routes, we are going to check the request query parameters. Any parameters that match permission=foo will get added to a permissions block on the user. If there are none, the permissions block will be set to empty. We will also want to update our User schema to return these permissions as part of our normal retrieval functionality.

/app/models/user.js

var mongoose = require('mongoose');  
var Schema = mongoose.Schema;


var UserSchema = new Schema({  
    name: String,
    email: {type: String, required: true, index: {unique: true}},
    password: {type: String, required: true, select: false},
    permissions: [String]
});

module.exports = mongoose.model('User', UserSchema);  

Here we simply added an Array of Strings named permissions to the Schema.

And update the POST and PUT blocks in /app/routes/user.js to include

user.permissions = req.query.permissions || [];  

where we set the other user properties. Now, using our Postman utility, create or update an existing user and some permissions to the url. For example:

localhost:1337/api/users/54ea3206488bfd24c5ac7ee8?permissions=admin&permissions=superhero  

This would then add admin and superhero to our permissions array. If we leave them off, an empty array is used. Again, this is The Wrong Way to do this, but it will serve our purposes.

Changes

So, let's run down the code changes we are going to make

• We are going to modify our backend server code and

  • create an /api/authenticate endpoint that will accept credentials. If successful, it will return a token.
  • modify the /api/user(s) endpoints to check for the presence of a valid token before performing any actions. If one is not found, a 401 Unauthenticated error code will be returned.
  • modify the DELETE /api/users/:user_id endpoint to verify the authenticated user also has admin permissions. If not, a 403 Unauthorized error code will be returned.
  • update our server to accept requests from other domains. (More on this later).

• We will create a login screen and

  • extend the existing single user form view
  • add some simple client side validation to enforce name and email requirements
  • call the authentication endpoint
  • upon successful login we'll store the token received
    

• We will create a logout action in our navigation bar that

  • will be visible only when logged in
  • will remove the stored token when activated

• We will display information about the logged in user in the navigation bar

• We will modify our router to

  • ensure that we are authenticated before showing the Users view

• We will create an application wide object to

  • perform authentication and logout actions
  • provide access to our currently logged in user

• We will add application wide AJAX error handling

Server Updates

Authentication Endpoint - Until now, we've been storing our passwords in the database in cleartext. We should really be encrypting them. Let's grab a crypto library to handle that, along with the JSON Web Tokens library.

npm install bcrypt-nodejs jsonwebtoken --save  

In /app/models/user.js let's go ahead and require the crypto library and add some functionality to use it.

var bcrypt = require('bcrypt-nodejs');

UserSchema.pre('save', function(next){  
    var user = this;
    if (!user.isModified()){
        return next();
    }

    bcrypt.hash(user.password, null, null, function(err,hash){
        if (err) {
            return next(err);
        }
        user.password = hash;
        next();
    })
});

UserSchema.methods.comparePassword = function(password){  
    var user = this;
    return bcrypt.compareSync(password, user.password);
};

We have two things going on here. First, we've added a hook to the User schema that will get called before any Save operation. If the document has been modified, or is new, we assume the password has been modified and is in cleartext. We convert it to an encrypted form, and then let the normal save function occur.

Secondly, we've added a comparePassword method to the User object. When we authenticate a user, we will use this compare the submitted password to the stored one.

Now let's update our user routes in /app/routes/user.js. First add our dependency:

var jwt = require('jsonwebtoken');

var superSecret = 'TheAmazingKreskin`;  

We've also created a "secret word" that we will use when encrypting and decrypting our token. This should probably be stored in a config file or passed in on the command line for better security.

After our default /api/ route, let's create our /api/authenticate route

var userRouter = express.Router();

userRouter.post('/authenticate', function (req, res) {  
    User.findOne({
        email: req.body.email
    }).select('name email password').exec(function (err, user) {
        if (err) throw err;

        if (!user) {
            res.json({success: false, message: 'User not found'});
        } else {
            var validPassword = user.comparePassword(req.body.password);
            if (!validPassword) {
                res.json({success: false, message: 'Wrong password'});
            } else {
                var token = jwt.sign({
                    name: user.name,
                    email: user.email,
                    _id: user._id
                }, superSecret, {
                    expiresInMinutes: 1440
                });

                res.json({
                    success: true,
                    message: 'login ok',
                    token: token,
                    _id: user._id
                });
            }
        }
    });
});

userRouter.get('/', function (req, res) {  
    res.json({message: 'api is loaded'});
});

When receive the POST request, we lookup the user by the provided email, and select their name and password as well. Remember, by default, our Schema does not return a password. In the event of an error or the user is not found, an error is returned to the user. In this instance, we don't send an error response. We expect that an unsuccessful attempt is a common occurrence, so we will explicitly handle the response. In this way, we could count the number of attempts or provide extra help, rather than just redirecting back to the login page.

If the user is found, we compare the submitted password to the one on record. If successful, we create a token with some user info in it and a timeout of 1440 minutes, or 24 hours. This will force the user to reauthenticate after one day, even if they have a proper token. Encrypting it will prevent the token from being modified by the client.

Using our Postman extension, we can test this endpoint right away. Using our prvious user editing capabilities, change the password on one of the users. This will ensure that the password associated with the user is encrypted in the database. (In fact, you may want to clean out any other users you created since they will need to have their passwords reset. For a production app, we could trap for this condition and handle it gracefully. Let's just delete them and make new ones.)

Make a POST request to /api/authenticate with a body of

{"email" : "email_value", "password": "password_value"}

using the values for that user you updated. Remember to set the Content-Type header to application/json. If the passwords match, you should see a response similar to

{
    "success": true,
    "message": "login ok",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiQnJpYW4gTSIsIl9pZCI6IjU0ZTZiMTYyZWIyYWM2MWM1NGU5YjgwZiIsImlhdCI6MTQyNDkyNTA4MCwiZXhwIjoxNDI1MDExNDgwfQ.90utguKl1XrpQZHU6tYPzOhskOeSl4k5RTTk6JcbuDo",
    "_id": "54e6b162eb2ac61c54e9b80f"
}

Even with our authentication endpoint in place, we have no problem accessing our app, even if we provided the wrong password. We'll need to tell the other routes to check for a valid token to be sent with every request.

After our default route, add the following code. Since this is declared after the default route, we will still be able to access it without authentication.

userRouter.get('/', function (req, res) {  
    res.json({message: 'api is loaded'});
});

userRouter.use(function (req, res, next) {  
    var token = req.body.token || req.params.token || req.headers['x-access-token'];
    if (token) {
        jwt.verify(token, superSecret, function (err, decoded) {
            if (err) {
                return res.status(401).send({success: false, message: 'Failed to authenticate token'});
            } else {
                req.decoded = decoded;
                next();
            }
        })
    } else {
        return res.status(401).send({success: false, message: 'No token provided'});
    }
});

With the use directive, we are adding some middleware to our route. For every request on routes declared after this we will attempt to find a token value in the body, in the parameters, or even in the headers. If a token is found, we verify it with our secret word. If it is valid, we continue to the next request handler, which will be our standard GET, PUT, POST, etc. calls. If there is no token, or it is invalid, we send a 401 HTTP error with an appropriate message. Our client will know that it needs to reauthenticate when it receives such a message.

Now, if we try to access our users page, we will get an error and nothing will display.

Next Steps

In our next installment, we'll wire up the client to call the authenticate endpoint when needed and send our token on future calls.

(The code at this state in the project can be checked out at commit: dae2b441bf1c718a6000df50679a6b096d70d8c4)

(Note: The code for this series is available on Github - To get the code in preparation for this installment, checkout commit: d82adb485a608278b2003415cab536503c40d5d2)

Database Integration

A lot of tutorials wave their hands at this point and assume you have a database connected. Worse, some will have you write stubs and timeouts to simulate connection delays. If you know what you're doing, these can be a quick way to get a screen or feature running. If you're building from the ground up, you're just delaying the inevitable. Plus, if you've never done it before, figuring out how to wire it in later can be a challenge.

MongoDB and mongoose

Earlier in this series we installed MongoDB. Ensure that you have a running copy before continuing. For a GUI front end, I like using MongoHub. Mongoose is an object modeling solution that lets you write simple schema based objects to work between your Node server and your Mongo database. It has hooks for validation, query building and more, and with a healthy plugin ecosystem can do nearly anything you throw at it. We'll only scratch the surface of its feature set.

To install mongoose, run:

npm install mongoose --save  

We'll need to tell our app how to connect to MongoDB. In our server.js file, add

var mongoose = require('mongoose');  

to the dependencies section at the top. Then underneath that, add

mongoose.connect('mongodb://localhost:27017/rlbb');  

If you configured MongoDB to run on another port, edit the above the string. rlbb is the name of our database and will be created if not present. Here is also where we would add things like database username, password, and the like if we had them.

Now, let's create a User model. Under app/models, create user.js

var mongoose = require('mongoose');  
var Schema = mongoose.Schema;

var UserSchema = new Schema({  
    name: String,
    email: {type: String, required: true, index: {unique: true}},
    password: {type: String, required: true, select: false}
});

module.exports = mongoose.model('User', UserSchema);  

Here, we've pulled in our mongoose dependency and created a User Schema object. Mongoose uses the Schema as representation of a MongoDB collection and the base of its functionality. We've defined a name, an email, and a password. Along with the property names, we've defined their SchemaType, in this case, they are all Strings. For email and password, we've also included some additional properties. required indicates that the field must be present to be valid. Other validators include min, max, match, and custom validators can be created. For email, which we will use as our username, we create an index for it, and put a unique constraint on it. For password, we indicate that normal retrieval of this object from the collection should not include the password field. This prevents it from going across the network. When we add authentication later, we will explicitly ask for the password. Finally, we create a mongoose model from the schema and export it.

Our First REST Endpoints

So, we have a model of our User data. We now need a way to retrieve it from and write it to the database. In this app, all of our API URLs will start with /api/ and then follow with the appropriate REST endpoints. For user, we will end up creating:

/api/users

POST - With a POST request, a new user will be created.
GET - With a GET request, this will return all users.

/api/users/:user_id

GET - With a GET request, this will return a single user with an ID that matches :user_id.
PUT - With a PUT request, the user indicated will be updated.
DELETE - With a DELETE request, the user indicated will be deleted.

With just two endpoints, and using the HTTP verbs, we can satisfy our basic CRUD requirements. To define these, we will create an Express router and then have Express use it, much like we did with the static assets directory and the catch all request handler.

Under app/routes, create user.js ¹.

var bodyParser = require('body-parser');  
var User = require('../models/user');

module.exports = function (app, express) {  
    var userRouter = express.Router();

    userRouter.get('/', function (req, res) {
        res.json({message: 'api is loaded'});
    });

    userRouter.route('/users')
        .post(function (req, res) {
            var user = new User();
            user.name = req.body.name;
            user.username = req.body.username;
            user.password = req.body.password;

            user.save(function (err) {
                if (err) {
                    if (err.code === 11000) {
                        return res.json({success: false, message: 'Duplicate username.'});
                    } else {
                        return res.send(err);
                    }
                } else {
                    res.json({message: 'user created'});
                }

            });
        })
        .get(function (req, res) {
            User.find(function (err, users) {
                if (err) {
                    res.send(err);
                }
                res.json(users);
            })
        });

    userRouter.route('/users/:user_id')
        .get(function (req, res) {
            User.findById(req.params.user_id, function (err, user) {
                if (err) res.send(err);
                res.json(user);
            })
        })
        .put(function (req, res) {
            User.findById(req.params.user_id, function (err, user) {
                if (err) res.send(err);

                if (req.body.name) user.name = req.body.name;
                if (req.body.email) user.email = req.body.email;
                if (req.body.password) user.password = req.body.password;

                user.save(function (err) {
                    if (err)res.send(err);
                    res.json({message: 'user updated'});
                });
            });
        })
        .delete(function (req, res) {
            User.remove({_id: req.params.user_id}, function (err, user) {
                if (err) res.send(err);
                res.json({message: 'user deleted'});
            })
        });

    return userRouter;
};

This looks like a lot, but it's fairly straightforward. Let's tackle it a chunk at a time.

var bodyParser = require('body-parser');  
var User = require('../models/user');  

Here will pull in our dependencies. We will use body-parser to get the data that comes with the PUT and POST requests and User is the user model we just created.

    var userRouter = express.Router();

    userRouter.get('/', function (req, res) {
        res.json({message: 'api is loaded'});
    });

Here we create an instance of an Express router. To give us a way to verify our routes have been initialized properly, we create a default route api/ that will respond with a canned message. If there are problems we can use this to see if it is a server or database issue.

userRouter.route('/users')  
        .post(function (req, res) {
            var user = new User();
            user.name = req.body.name;
            user.email = req.body.email;
            user.password = req.body.password;

            user.save(function (err) {
                if (err) {
                    if (err.code === 11000) {
                        return res.json({success: false, message: 'Duplicate username.'});
                    } else {
                        return res.send(err);
                    }
                } else {
                    res.json({message: 'user created'});
                }

            });
        })
        .get(function (req, res) {
            User.find(function (err, users) {
                if (err) {
                    res.send(err);
                }
                res.json(users);
            })
        });

Here we create the api/users route and handle both the POST and the GET cases. In the POST block, we create a new User, set the fields with data from the request body, and save it. Mongoose handles the heavy lifting of creating the query and talking to the database. We perform some basic error-handling, and return an appropriate message to the client.

In the GET block, we call a static model method on User to retrieve all the stored users and return them. Once again, mongoose takes care of the details.

userRouter.route('/users/:user_id')  
        .get(function (req, res) {
            User.findById(req.params.user_id, function (err, user) {
                if (err) res.send(err);
                res.json(user);
            })
        })
        .put(function (req, res) {
            User.findById(req.params.user_id, function (err, user) {
                if (err) res.send(err);

                if (req.body.name) user.name = req.body.name;
                if (req.body.username) user.username = req.body.username;
                if (req.body.password) user.password = req.body.password;

                user.save(function (err) {
                    if (err)res.send(err);
                    res.json({message: 'user updated'});
                });
            });
        })
        .delete(function (req, res) {
            User.remove({_id: req.params.user_id}, function (err, user) {
                if (err) res.send(err);
                res.json({message: 'user deleted'});
            })
        });

Here we create the api/users/:user_id route. Express will take the value in the request that maps to the :user_id section and create a request parameter that we can use. In the GET block, we use mongoose's findById method to retrieve a specific user. In the PUT block, we again retrieve the requested user, update its information with data from the request body, then save it. Finally, in the DELETE block, we use mongoose's remove function to delete the specified user.

Now it's time to wire the router into the server. In server.js, after the static directory declaration, add the following

// already in our file
app.use(express.static(__dirname + '/public'));

// ADD THESE TWO LINES
var userRoutes = require('./app/routes/user')(app, express);  
app.use('/api', userRoutes);

// already in our file
app.get('*', function(req,res){  
    res.sendFile(path.join(__dirname + '/public/index.html'));
});

First we create the routes, by requiring the file and passing it the two needed fields, app and express. (Go back and look at how we declared our router definition and you will see we have these two params listed). Then, we tell our server to use the routes. Remember, order is important. First our static files, then our API routes, and finally the catch all to serve up our home page. If we added our routes after the catch all, they would never be hit.

If we were to run our server now, with nodemon server.js we would be able to get and set users via HTTP. But... we don't have any users yet, and we don't have screens to input data. Any easy solution is to use something like Postman - REST Client for Chrome (all the browsers have similar tools). In the URL field, enter localhost:1337/api and make sure GET is selected in the dropdown. When you hit send, you should see our test message returned in JSON format.

We can do a similar task to add a user. Set the URL to localhost:1337/api/users, the method to POST, select raw for our input data and add

{ "email" : "hireme@brianmajewski.com", name: "Brian M", password: "123456Secure!"}

These are the fields we defined on our User model.

We also need to set our content type, so select Headers, and for name put Content-Type and value put application/json. If we're configured right, you should get a response back saying user created. To see our new user, hit the same URL, with GET, and you should receive a response similar to

[
    {
        "_id": "54e6b162eb2ac61c54e9b80f",
        "email": "hireme@brianmajewski.com",
        "name": "Brian M",
        "__v": 0
    }
]

Notice: Our password is not returned, as we specified in our schema. Experiment with the other routes and verify that you can update and delete users as well.

So there you have the basics for all CRUD operations for your app. Whether you are storing Widgets, Gizmos, Comments, or Reviews, you will follow the same basic pattern. Later, when we add authentication, you'll see how we can enhance mongoose's standard methods to perform extra functionality, such as encrypting the password, before saving the user.

To get the code with these updates checkout commit 18b0d51ee45d966abf9293be9a5fe25c6af8c6a6

Next Steps

With a functional backend in place, we will begin to create our front end web application. We'll look at using Bower to manage dependencies and RequireJS to load modules.

(UPDATE: There was a bug in the PUT block of the /users/:user_id route - username should have been email - This bug was fixed in the Chapter 7 version of the code on Github and in the text above)