checkpoint
A module to provide an easy but configurable way to implement token based authentication for a node server
Install
This is a Node.js module available through the internal Conqr npm registry.
Before installing, download and install Node.js. Node.js 0.10 or higher is required.
Installation is done using the npm install command:
$ npm install @conqr/{module name}
Usage
new Authenticator(options)
Creates a new auhtenticator.
options
:
-
basicAuthHandler
: handler for basic http authentication in the form of(req, userid, password, done) => void
.req
is the request being authenticated.userid
andpassword
are extracted from the http basic auth header.done(err, user)
is a callback that determines whether the authentication was successful based on the arguments sent. Iferr
is not null, oruser
is false, the request is unauthorized. -
tokenAuthHandler
: handler for token authentication in the form of(req, token, payload, header, signature, done) => void
.token
is the jwt token extracted by thetokenExtract
hook.payload
,header
, andsignature
are the different parts of the verified jwt token. -
tokenExtract
: a function to extract a token from a request in the form of(request) => token
. The function receives a request object and should return the extracted token, ornull
if no token could be extracted.A number of predefined extraction methods are provided by the
ExtractJwt
class provided in this module. Ex.ExtractJwt.fromAuthHeaderAsBearerToken()
-
tokenPayload
: hook for building the payload to be encoded into a jwt token,(user) => payload
. The function receives a user object which can be used to put user specific claims into thepayload
. -
tokenStore
: hook executed after the token has been generated but not yet passed to the final request handler.token
is the encoded jwt token, andpayload
now contains all claims both user specific and global, that have been encoded into the jwt token. -
jwt
: (see jsonwebtoken)-
secretOrKey
: a string, buffer, or object containing either the secret for HMAC algorithms or the PEM encoded private key for RSA and ECDSA. In case of a private key with passphrase an object{ key, passphrase }
can be used (based on crypto documentation), in this case be sure you pass thealgorithm
option. -
jwtIdProvider
: function to generate unique ids for tokens. -
options
-
algorithm
(default:HS256
) -
expiresIn
: expressed in seconds or a string describing a time span zeit/ms. (default:1h
)Eg:
60
,"2 days"
,"10h"
,"7d"
. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default ("120"
is equal to"120ms"
). -
notBefore
: expressed in seconds or a string describing a time span zeit/ms.Eg:
60
,"2 days"
,"10h"
,"7d"
. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default ("120"
is equal to"120ms"
). -
audience
(default:conqr-client
) -
issuer
(default:conqr-server
) noTimestamp
header
-
ignoreExpiration
: iftrue
do not validate the expiration of tokens. -
ignorNotBefore
: iftrue
do not validate the notBefore of tokens. -
clockTolerance
: number of seconds to tolerate when checking thenbf
andexp
claims, to deal with small clock differences among different servers -
maxAge
: the maximum allowed age for tokens to still be valid. It is expressed in seconds or a string describing a time span zeit/ms.Eg:
1000
,"2 days"
,"10h"
,"7d"
. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default ("120"
is equal to"120ms"
).
-
-
-
generateEndpoints
: option to automatically generate protected token generation endpoints for each auth method. (default:true
)Generated endpoints are in the form
/auth/<method>
. Ex./auth/basic
,/auth/google
, etc. -
OAuthCallbackHost
: the base url for OAuth callbacks. Only used in conjunction withgenerateEndpoints
.When this option is set, the
callbackURL
property of the OAuth provider options is ignored. Callback endpoints for OAuth providers will be generated in the following pattern:<host>/auth/<provider>/callback
. Ex.https://example.com/auth/google/callback
. -
OAuthProviders
: object where every key is an OAuth provider, currently supported providers aregoogle
andfacebook
.At the moment all supported providers have the same options:
-
google
-
handler
: handler for authentication with this provider:(request, accessToken, refreshToken, profile, done) => void
. Called after the OAuth provider authentication is completed.accessToken
is the token provided by the OAuth provider for access to the providers API,refreshToken
is used to renew the OAuth access token,profile
contains the userdata provided by the OAuth provider. -
options
clientID
clientSecret
-
callbackURL
: ifOAuthCallbackHost
is set this will be ignored.If set, this property should be a complete url. ex.
https://example.com/google/callback
-
failureRedirect
: a redirect path that will be used if the OAuth handler signals an unsuccessful authntication.
-
-
Authenticator.initExpress(router);
Initializes the authenticator for use with Express.js
router
: express app or router for which authentication should be handled. If generateEndpoints
is set, this is the router on which they will be added.
The initialize function has to be run before any middleware is used.