OpenSesame

OpenSesame is a authentication system that provides authentication through the use of Json Web Tokens (JWT) and secure, httpOnly cookies. It provides a login page and a register page but allows for custom login and register pages as well.

It provides the following routes for authentication purposes:

API

• POST /auth/login - Authenticates a user using the value of req.body which is passed to the user-provided config.checkUser function. Sets a cookie with the JWT on the client on sucess and redirects to config.redirectUrl
• POST /auth/register - Registers a user using the value of req.body and the user-provided config.registerUser function. On success it logs the user in the same way /auth/login does.
• GET /auth/logout - Clears the cookie on the client and redirects to / effectively logging the user out.
• GET /auth/verify - Returns 200 when the user is authenticated.
• GET /auth/refresh - Generates a new JWT for an already authenticated user and sets their cookie to it.

Views

• GET /login - Shows a default login page
• GET /register - Shows a default registration page

Configuration options

The following are options that can be passed to opensesame:

Required

• secret - A string which is used by the JWT library to crpytographically sign and verify JWTs.
• checkUser - A function that takes the object that the login page sends to the server and calls a callback with either an error or the user object that will be stored on the JWT. Should check that the username and password are correct. function checkUser(userObject, callback)
• registerUser - A function that takes the object that the registration page sends to the server and calls a callback with either an error or the user object that will be stored on the JWT. Should store the user credentials somewhere for later lookup by the checkUser function. function registerUser(userObject, callback)
• refreshUser - A function that gets an already authenticated user based on the value of the JWT. Should return an up to date user object that will be stored on the JWT. function refreshUser(userObject, callback)

Optional

• redirectUrl - A string specifying a route of where to redirect the user after authenticating. / by default.
• httpsOnly - Specifies whether the cookie should use the secure flag. If true then authentication only works over HTTPS. true by default.
• cookieKey - The name of the key that is set on the client browser's cookie. auth by default.
• useCookieParser - A flag specifying whether to use cookie parser middleware or not. OpenSesame will not work properly if cookie parser middleware is not used. true by default
• tokenExpiration - Specifies how long the JWT should remain valid for. Follows the rauchg/ms convention. 24h by default.
• loginUrl - The url that renders the login page. Users will be redirected here when they try to view a protected resource. /login by default.
• registerUrl - The url that renders the registration page. /register by default.
• customLoginPage - A flag that tells OpenSesame whether to set up its own login page. If true then OpenSesame will not set up the /login route and login page. false by default.
• customRegisterPage - A flag that tells OpenSesame whether to set up its own register page. If true then OpenSesame will not set up the /register route and register page. false by default.

Example

Check the example folder for a running example of how to use opensesame.

var openSesame = require('opensesame');
//you can give opensesame an express app object
openSesame({
    secret: 'testSecret',
    checkUser: function (userObject, callback) {
        if(userObject.user === 'peter' && userObject.pass === 'test1234') {
            callback(null, {username: 'peter'});
        } else {
            callback('Incorrect credentials');
        }
    },
    registerUser: function (userObject, callback) {
        callback(null, {username: 'peter'});
    },
    refreshUser: function (userObject, callback) {
        callback(null, userObject);
    },
    redirectUrl: '/app',
    httpsOnly: false
}, app);

//or have it generate one for you
var app = openSesame({
    secret: 'testSecret',
    checkUser: function (userObject, callback) {
        if(userObject.user === 'peter' && userObject.pass === 'test1234') {
            callback(null, {username: 'peter'});
        } else {
            callback('Incorrect credentials');
        }
    },
    registerUser: function (userObject, callback) {
        callback(null, {username: 'peter'});
    },
    refreshUser: function (userObject, callback) {
        callback(null, userObject);
    },
    redirectUrl: '/app',
    httpsOnly: false
});

Note: OpenSesame uses the cookieParser and the bodyParser.urlEncoded middleware.