JSON Web Token session middleware backed by Redis
npm install @patagoniantech/jwt-redis-sessionJWT-Redis-Session
=================
JSON Web Token session middleware backed by Redis. This connect middleware module exposes an API surface similar to a session middleware module, however instead of using cookies to transport session details this module uses JSON Web Tokens. This is useful for cookie-less clients or for cross service user authentication.
``bash`
npm install @patagoniantech/jwt-redis-session
Developers are free to use either the JWT claims or redis to store session related data. In many cases when serializing a user's session only the minimal amount of data necessary to uniquely identify the user's session is actually serialized and sent to the client. By default when this module creates a JWT token it will only reserve the "jti" property on the JWT claims object. This property will refer to a UUID that acts as the key in redis for the user's session data. This ensures that by default this module will only serialize the minimal amount of data needed. Any other data stored on the JWT session object throughout the request-response process will be serialized and stored in redis.
Due to the way JSON Web Tokens work the claims object can only be modified when creating a new token. Because of this by default this module does not attach a TTL to the JWT. Any TTL attached to the JWT cannot be refreshed without regenerating a new JWT so this module instead manages a session's expiration via redis key expirations. Aside from the "jti" property, which this module reserves, developers are free to attach any data to the claims object when creating a new JWT, including a TTL, but need to be aware that any TTL on the claims object will supercede the TTL managed by redis.
This module supports a few initialization parameters that can be used to support several usage scenarios, including running any number of instances of this middleware module alongside each other.
* requestKey - The key name on the request object used to identify the JWT session object. The default for this value is "session". This would interfere with a module such as express-session so developers are free to modify this.
* requestArg - The parameter name on the HTTP request that refers to the JWT. The middleware will look for this property in the query string, request body, and headers. The header name will be derived from a camelBack representation of the property name. For example, if the requestArg is "accessToken" (the default) then this instance of the middlware will look for the header name "x-access-token".
* keyspace - The prefix of the keys stored in redis. By default this is "sess:".
* secret - The secret key used to encrypt token data.
* verificationSecret - The secret key used to verify the token signature.
* signOptions - A SignOptions from "jsonwebtoken" package. This property is optional
* client - The redis client to use to perform redis commands.
* maxAge - The maximum age (in seconds) of a session.
`javascript
const JWTRedisSession = require("@patagoniantech/jwt-redis-session"),
express = require("express"),
fs = require('fs'),
redis = require("redis");
const redisClient = redis.createClient(),
secret = generateSecretKeySomehow(),
app = express();
app.use(JWTRedisSession({
client: redisClient,
secret: secret,
keyspace: "sess:",
maxAge: 86400,
signOptions: {
algorithm: 'HS256'
},
requestKey: "jwtSession",
requestArg: "jwtToken"
}));
// If you need to use an asymmetric algorithm such as RS256
const privateKey = fs.readFileSync('/path/to/private_key.pem', 'utf8');
const publicKey = fs.readFileSync('/path/to/public_key.pem', 'utf8');
app.use(JWTRedisSession({
client: redisClient,
secret: privateKey,
verificationKey: publicKey,
keyspace: "sess:",
maxAge: 86400,
signOptions: {
algorithm: 'RS256'
},
requestKey: "jwtSession",
requestArg: "jwtToken"
}));
`
All examples following this assume the above configuration.
Create a new JSON Web Token from the provided claims and store any relevant data in redis.
`javascript
var handleRequest = function(req, res){
User.login(req.param("username"), req.param("password"), function(error, user){
// this will be stored in redis
req.jwtSession.user = user.toJSON();
// this will be attached to the JWT
var claims = {
iss: "my application name",
aud: "myapplication.com"
};
req.jwtSession.create(claims, function(error, token){
res.json({ token: token });
});
});
};
`
The session's UUID, JWT claims, and the JWT itself are all available on the jwtSession object as well. Any of these properties can be used to test for the existence of a valid JWT and session.
`javascript
var handleRequest = function(req, res){
console.log("Request JWT session data: ",
req.jwtSession.id,
req.jwtSession.claims,
req.jwtSession.jwt
);
res.json(req.jwtSession.toJSON());
};
`
Any modifications to the jwtSession will be reflected in redis.
`javascript
var handleRequest = function(req, res){
if(req.jwtSession.id){
req.jwtSession.foo = "bar";
req.jwtSession.update(function(error){
res.json(req.jwtSession.toJSON());
});
}else{
res.redirect("/login");
}
};
`
Force a reload of the session data from redis.
`javascript
var handleRequest = function(req, res){
setTimeout(function(){
req.jwtSession.reload(function(error){
res.json(req.jwtSession.toJSON());
});
}, 5000);
};
`
`javascript
var handleRequest = function(req, res){
req.jwtSession.touch(function(error){
res.json(req.jwtSession.toJSON());
});
};
`
Remove the session data from redis. The user's JWT may still be valid within its expiration window, but the backing data in redis will no longer exist. This module will not recognize the JWT when this is the case.
`javascript
var handleRequest = function(req, res){
req.jwtSession.destroy(function(error){
res.redirect("/login");
});
};
`
This module uses Mocha/Chai for testing. In order to run the tests a local redis server must be running or the REDIS_HOST and REDIS_PORT environment variables must be set.
`bash``
npm install
grunt test