@syntropy/token-manager

token-manager

A JWT token management library for browser clients

Features:

• Supports multiple token stores (local storage, session storage, URL hash, failover wrapper)
• Bundled AngularJS module (for Angular 1.x)
• Extensible via event listeners, middleware, and decorators

Usage

To install:

npm install --save token-manager

To use with a module bundler (webpack, etc):

var tokenManagerModule = require('token-manager');
angular.module('myApp', [ tokenManagerModule.name ]);

To use directly in-browser, see dist/token-manager.bundle.js.

TokenManager class

Events

TokenManager is an event emitter. See tiny-emitter for detailed documentation on how to bind to or trigger events.

auth

Fires whenever a new token is set. The token value is passed as the first argument.

expiring

Fires shortly before the token expires. The token value is passed as the first argument.

Configure the amount of time before expiration using the expirationWarning option when constructing the instance.

expired

Fires when the token expires. The token value is passed as the first argument.

error

Fires on error. The token value is passed as the first argument.

Methods

constructor(store, options = {})

• store - an instance of TokenStore
• options - a configuration object
  • expirationWarning - time in ms before token expiration to fire the expiring event. If not set, or zero, the event will not fire.
  • logger - instance of a logger, such as console or $log.

get()

Returns the current token from the token store.

auth(newToken)

Sets a new token. If any expiration timers are running they will be reset for the new token.

Fires the auth event when successful, or the error event when unsuccessful.

reset()

Resets the token manager state, stops all timers, and removes the token from the token store.

use(middlewareFn)

Add a middleware function (or array of functions) that is to be run on the token prior to setting it.

Middleware should have the following signature:

middleware(token, next(err, newToken))

Inside the function, call next(err) on error, and next() or next(null, newToken) when done. If newToken is passed, it will replace the token that is provided in subsequent middleware.

on(event, callback(...args))

Add a listener for an event.

once(event, callback(...args))

Add a one-time listener for an event.

off(event[, callback])

Remove a listener for an event. If no callback function is passed, removes all listeners for that event.

emit(event[, ...args])

Fire a custom event with one or more arguments.

keepAliveDecorator(manager, renewFn)

Decorates a token manager instance by exposing a keepAlive() method and binding to the 'expiring' event, so that if there has been recent activity (via keepAlive()), calls the renewFn to renew the token.

exchangeMiddleware(whenFn, settings = {})

Token middleware to detect when an authorization token should be exchanged for an access token (or some other similar token exchange scenario).

Uses fetch to make the token exchange. (You will probably need to polyfill.)

• whenFn(token) - a function that will receive the token as an argument, and returns true if the token should be exchanged.
• settings - a configuration object
  • url (required) - URL to call
  • method='POST' - HTTP verb to use
  • headers={'Authorization': 'Bearer ' + token} - HTTP headers to use

The exchanged token is then returned by the middleware to the auth() method.

TokenStore class

TokenManager relies on token stores that follow a specific interface. Custom token stores should extend this class.

Methods

constructor(store, key)

• store - the storage layer for storing the tokens. By default, TokenStore expects an object or object-like interface.
• key - the key in the store to use to store the token.

get()

Get the current token value from the store.

set(token)

Set a new token in the store.

remove()

Remove the token from the store.

AngularJS module

tokenManager service

Composes TokenManager, TokenStore, keepAliveDecorator, and exchangeMiddleware into a single AngularJS service.

Service configuration can be managed in a config() block via the tokenManagerProvider (see below).

getInstance()

Returns the wrapped TokenManager instance.

initialize()

Gets the current token from the token store, and then calls TokenManager.auth() using that initial token and returns a promise that will resolve to the token value.

getToken()

Alias for TokenManager.get().

getTokenPromise()

Just like getToken(), but returns a promise.

getClaims()

Returns the decoded version of the current token.

getClaimsPromise()

Just like getClaims(), but returns a promise.

setToken(token)

Alias for TokenManager.auth(), but with the following differences:

• If token is empty, calls TokenManager.reset() instead
• If token is invalid, calls TokenManager.reset() instead

logout()

Alias for TokenManager.reset().

keepAlive()

Updates the last activity timestamp. See the keepAliveDecorator above for details.

renew()

Force an immediate token refresh by calling the keepAliveDecorator's renewFn and returning the resulting promise.

tokenManager provider

config(options)

Configures the tokenManager service in a config() block.

Options:

• authorizeUrl="/auth" - URL to use when exchanging tokens
• refreshUrl="/renew" - URL to use to get a new token when the old one is expiring
• tokenTypeClaim="type" - JWT claim to read to determine if the token should be exchanged
• tokenAuthValue="auth" - JWT claim value when the token should be exchanged
• tokenTypeProvider=() => function(claims) - A higher order function that returns a function to check whether the token should be exchanged or not. Use this if tokenTypeClaim and tokenAuthValue are not sufficient to determine when to exchange the token
• persistenceStrategy="urlPersistenceStrategy" - The token store to use
• persistenceStrategyProvider=function - An injectable that returns the desired token store
• autoRefresh=60*1000 - How long (in milliseconds) before token expiration to fire the expiring event and attempt renewal
• autoRefreshSession - How recent (in milliseconds) the most recent activity from the user must be before attempting to refresh the token

urlTokenStore service

TokenStore instance that uses $location to persist the token in the URL hash.

urlTokenStore provider

urlTokenStore may be configured in a config() block using the provider.

config(options = {})

Options:

• persistenceKey="token" - The token key to use in the token store.
• persistenceKey=function() - A function that returns the desired persistenceKey value.

localStorageTokenStore service

TokenStore instance that uses $localStorage to persist the token in local storage.

Requires ngstorage or compatible.

localStorageTokenStore provider

localStorageTokenStore may be configured in a config() block using the provider.

config(options = {})

Options:

• persistenceKey="token" - The token key to use in the token store.
• persistenceKey=function() - A function that returns the desired persistenceKey value.

sessionStorageTokenStore service

TokenStore instance that uses $sessionStorage to persist the token in local storage.

Requires ngstorage or compatible.

sessionStorageTokenStore provider

sessionStorageTokenStore may be configured in a config() block using the provider.

config(options = {})

Options:

• persistenceKey="token" - The token key to use in the token store.
• persistenceKey=function() - A function that returns the desired persistenceKey value.

failoverTokenStore service

TokenStore that composes one or more read TokenStore instances and one or more write TokenStore instances together such that if the first one fails, it will retry against the second, and so on.

failoverTokenStore provider

failoverTokenStore may be configured in a config() block using the provider.

config(options = {})

Options:

• read=[] - an array of one or more *TokenStore services to attempt to read from
• write=[] - an array of one or more *TokenStore services to attempt to write to