jwt-redis-session

JWT-Redis-Session

JSON Web Tokens backed by Redis. This module exposes almost the same API surface as a generic express 4.x session middleware module with a few changes.

Since cookies are not used with JSON Web Tokens the transmission of the session ID via the JWT can no longer be transparently handled by the middleware. This means that the API surface for the session object must differ slightly from what one would find on express-session. Instead of calling req.session.save() to commit session changes as one would with express-session, this module requires that the application developer distinguish between creation and update commands. The difference between the two is that create() will generate a new session with a new ID and JWT while update() will check for and use the session ID already on req.session. After being issued a JWT the client will need to send the token with each subsequent request. It can be attached to the request as a part of the body, query string, or headers. In the case of the body or query string the token will be looked up by the key "accessToken". If the token is sent in the headers it will be queried by the name "x-access-token". See below for examples.

Usage =====

	
	// ... create your express app object elsewhere
	// ... create a redis client elsewhere with auth, etc
	// ... generate or require a secret key elsewhere

	var JWTRedisSession = require("jwt-redis-session");

	app.use(JWTRedisSession({
		client: redisClient,
		secret: secret,
		keyspace: "sess:", // this is the default if not specified
		maxAge: 86400, // session TTL in seconds, this is the default
		algorithm: "HS256", // hashing algorithm to use, this is the default (SHA-256)
		requestKey: "session" // the key under which all JWT data will be stored, this is the default but you're free to change this if you need to run this middleware with express-session
	}));

	// create a few CRUD routes on the app to demonstrate session usage
	
	app.get("/session/create", function(req, res){
	
		// check the user's credentials somehow...
		User.login(req.param("username"), req.param("password"), function(error, user){
			if(error)
				return res.status(500).json({ error: error.message || error });
			
			// create a session and send the user their JWT
			req.session.user = user;

			// attach any custom claims to the JWT
			var claims = {
				user_id: user.id
			};

			// you can also pass the callback as the first parameter if you don't require any custom claims
			req.session.create(claims, function(err, token){
				if(err)
					res.status(500).json({ error: err.message || err });	
				else
					res.status(200).json({ token: token });
			});	

		});

	});
	
	app.get("/session/read", function(req, res){

		// use the existence of an "id" property on the session to determine if a session exists
		if(req.session.id)
			console.log("Session found!", req.session);
		else
			console.log("Request does not have a session");
		
		// read any custom claims
		console.log("Custom claims: ", req.session.claims);

		// read the original JWT
		console.log("Token: ", req.session.jwt);

		// maybe the application is distributed across multiple server instances
		// and another instance does something to the session while this request is waiting...
		
		setTimeout(function(){

			// force a reload of the session from redis
			req.session.reload(function(error){
				if(error)
					res.status(500).json({ error: error.message || error });
				else
					res.json({ session: req.session });
			});

		}, 10000);

	});

	app.get("/session/update", function(req, res){
	
		req.session.foo = "bar";

		// commit the session changes to redis
		req.session.update(function(error){
			if(error)
				res.status(500).json({ error: error.message || error });
			else
				res.json({ session: req.session });
		});

	});

	app.get("/session/destroy", function(req, res){
	
		// the user's JWT will no longer be associated with their session
		req.session.destroy(function(error){
			if(error)
				res.status(500).json({ error: error.message || error });
			else
				res.end();
		});

	});