#Tokens for NodeJS
##Purpose
The purpose of this module is to provide a simple lightweight framework for managing session tokens. This module does NOT provide authentication functionality but rather authorizes requests to a REST service after authentication has already taken place. By using a session token and combining that with a nonce value tracked per session this module will help prevent session hijacking and cross site request forgery attacks.
##Security Standards
This module implements best practices as specified in the OWASP suggested best practices for securing REST services.
##Usage
###createSession
Create a session token with createSession.
#####Method Signature
createSession(complete, error)
#####Example
var auth = require('tokens')();
auth.createSession(function (response) {
console.log('sessionToken : %s', response.sessionToken);
console.log('nonce : %s', response.nonce);
console.log('expirationDateTime: %s', response.expirationDateTime);
},
function(error) {
console.log('error message: %s', error.message);
});
####response: complete
The response will contain the newly created session token, the session's nonce value and the session expiration date and time.
{
"sessionToken": "b0c96728-4c44-4c0a-9fca-5563fb1ebe44",
"nonce": 1,
"expiration": "2014-11-15T20:02:43.450Z"
}
###validateSession
Subsequent requests can be validated by calling validateSession.
#####Method Signature
validateSession(sessionToken, nonce, complete, error)
#####Example
var auth = require('tokens')();
auth.validateSession(sessionTokenFromRequest, nonceFromRequest,
function(response) {
console.log('sessionToken : %s', response.sessionToken);
console.log('nonce : %s', response.nonce);
console.log('expirationDateTime: %s', response.expirationDateTime);
},
function(error) {
console.log('error message: %s', error.message);
console.log('session token: %s', error.sessionToken);
console.log('nonce: %d', error.nonce);
});
####responses: complete, error
#####complete callback The response from a complete callback contains the following information:
{
success: true,
failureReason: '',
newSessionInformation: {
sessionToken: "6faf36df-8877-4177-945b-700c4684e7c3",
nonce: 2,
expiration: "2014-11-16T16:41:41.062Z"
}
}
If there is a failure the success property will be false, the failureReason will contain the error message, and the newSessionInformation will be undefined. A non-successful response is not the same as an error. Failures that result in a non-successful result are caused because the session token or the nonce is incorrect.
- A system error such as the inability to read or write to the persisted storage mechanism would result in an error.
- If there is a system error the complete callback is never called.
#####error callback The error callback will be called if there is a system level error in processing the request. Known error conditions would be:
- could not read or write to the persisted storage
- invalid or corrupt session data retrieved
###destroySession
A session can be immediately destroyed (and removed from persisted storage) by calling destroySession.
#####Method Signature
destroySession(sessionToken, complete, error)
#####Example
var auth = require('tokens')();
auth.destroySession(sessionTokenFromRequest,
function() {
console.log('session %s destroyed.', sessionTokenFromRequest);
},
function(error) {
console.log('error message: %s', error.message);
console.log('session token: %s', error.sessionToken);
});
####responses: complete, error
#####complete callback The complete callback is called with no method arguments as there is no data to return to the caller.
*Please note that if there is an error condition (e.g. the session could not be deleted from the persistence store) the complete callback is not called.
#####error callback The error callback will be called if there is a system level error in processing the request. Known error conditions would be:
- could not read or write to the persisted storage
##Running the unit tests The unit tests use the jasmine-node format.
- To execute them you need to install jasmine:
npm install jasmine-node
- Change into the root project folder
node-session-tokens
- Execute the unit tests:
jasmine-node spec