strajah-token
v2.0.4
Published
Ciphered accessToken management
Downloads
3
Readme
cipherToken
A method to create ciphered accessToken based on the following principles:
- must include id information.
- must include expiration information.
- must be a designed token to transport, but not to store it.
NodeJS
Require
const cipherToken = require('cipherToken');
Usage
cipherToken is designed to be used as a module.
Initiate the token generator for a set of settings
const accessTokenCreator = cipherToken(settings);
Tokens are created this way
const cipheredToken = accessTokenCreator.create.userId('my-id12').data({'some': 'data'}).encode();
and can be decoded back to a more readable state with
const decodedToken = accessTokenCreator.decode(cipheredToken);
Settings
Settings is a hash with the following properties
- cipherKey : (required) used to cipher the accessToken
- firmKey : (required) used to firm the accessToken
- tokenExpirationMinutes : minutes of accessToken life (90 minutes by default)
- cipherAlgorithm : algorithm used to cipher the token (aes-256-cbc by default)
- hmacAlgorithm : algorithm used to build the hmac (md5 by default)
- hmacDigestEncoding : encoding used in the outbound of the hmac digest (hex by default)
- plainEncoding : encoding used in the data content in the token (utf8 by default)
- tokenEncoding : encoding used in the token format (base64 by default)
- enableSessionId : sessionId of an accessToken, can be preset at accessToken creation
Settings must be passed to cipherToken in each call. Only cipherKey and firmKey are required.
Create tokens
First thing you need is a cipherToken for your settings
const accessTokenCreator = cipherToken(settings);
After that you'll create a set for a given user which will contain data to be encoded in the token
const cipheredToken = accessTokenCreator.set.userId('my-id12').data({'some': 'data'}).sessionId('my-previous-session-id').encode();
UserId can be an username or any other thing you use to identify your customers. SessionId is only to be submitted when you want to create a token associated to the same session of another token (usually near expiration). If you have enableSessionId in your settings enabled but that's the first time creating a token for a new session, then you don't need to use the method 'sessionId' and a random UUID v4 will be generated. Data is to encode the payload you want to travel with the token.
The result, cipheredToken, is an object which for now has only two properties
- token: contains the token itself
- error: only when there was an error during encoding process
Decode tokens
You'll need an accessTokenCreator (still looking for a better name) initialized with the same settings as the ones used in the encoding process
const decodedToken = accessTokenCreator.decode(validToken.token);
decodedToken has the following properties
- set: the data encoded within the token, contains: userId, expiresAtTimestamp, data and sessionId if enabled
- error: if an error occurred during decoding
The only one added by cipherToken is expiresAtTimestamp: at creation, gets the actual time and add to it the time expiration to calculate when will the token expire. Cipher token doesn't care if the token has expired or not.
Example
const cipherToken = require('cipherToken');
const settings = {
cipherKey: 'myCipherKey123',
firmKey: 'myFirmKey123'
};
const accessTokenCreator = cipherToken(settings);
const cipheredToken = accessTokenCreator.create.userId('John Spartan').data('validData').encode();
const decodedToken = accessTokenCreator.decode(cipheredToken);
console.log(decodedToken.set.userId)
console.log(decodedToken.set.expiresAtTimestamp)
console.log(decodedToken.set.data)
console.log(decodedToken.set.sessionId)