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 and password 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. If err is not null, or user 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 the tokenExtract hook. payload, header, and signature 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, or null 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 the payload.

• tokenStore: hook executed after the token has been generated but not yet passed to the final request handler. token is the encoded jwt token, and payload 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 the algorithm 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: if true do not validate the expiration of tokens.
    • ignorNotBefore: if true do not validate the notBefore of tokens.
    • clockTolerance: number of seconds to tolerate when checking the nbf and exp 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 with generateEndpoints.

  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 are google and facebook.

  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: if OAuthCallbackHost 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.

Authenticator.authenticateWithToken()