bearer-token-parser

This is a Bearer token authentication module that you can use with the Express framework.

Installation

npm i bearer-token-parser

API

See API.md for API reference.

Release Notes

All changes can be found here.

Quick Start

There is a sample app in "./example" to try token authentication.

1. Move to the example directory.

   cd example/

2. Install dependencies.

   npm install

3. Start the app.

   npm start

4. You can send an authentication request with curl.
   • Correct token

     # HTTP Status: 200 OK
     curl -I -H 'Authorization: Bearer mytoken123' http://localhost:3000/auth

   • Wrong token

     # HTTP Status: 401 Unauthorized  
     # WWW-Authenticate: Bearer realm="myapi", error="invalid_token", error_description="Token cannot be authenticated"
     curl -I -H 'Authorization: Bearer mytoken456' http://localhost:3000/auth

   • Missing Authorization header

     # HTTP Status: 401 Unauthorized  
     # WWW-Authenticate: Bearer realm="myapi", error="token_required"
     curl -I http://localhost:3000/auth

   • Authorization header but no Token

     # HTTP Status: 401 Unauthorized  
     # WWW-Authenticate: Bearer realm="myapi", error="invalid_token", error_description="Token format error"
     curl -I -H 'Authorization: Bearer ' http://localhost:3000/auth

Usage

• An example of an Express framework.
  BearerParser can also be used with other frameworks.

  import express from 'express';
  import {BearerParser} from 'bearer-token-parser';
  
  const router = express.Router();
  router.post('/', async (req, res) => {
      // Get bearer token.
      const token = BearerParser.parseBearerTokenHeader(req);
  
      // Execute any process and response.
      res.json(true);
  });
  
  // mount the router on the app.
  app.use('/', router)

• This is an example of validation of Bearer tokens.
  BearerValidator is a module dedicated to the Express framework.
  In case of verification error, the following response is automatically returned.

  |HTTP status|WWW-Authenticate response header|Descritpion| |-|-|-| |401 Unauthorized|Bearer realm="Your realm name", error="token_required"|If the token locale is Header and there is no Authorization header.or if the token localization is Body/Query and there is no token parameter.| |401 Unauthorized|Bearer realm="Your realm name", error="invalid_token", error_description="Token format error"|If the Bearer token is empty or incorrect as token68 format.| |401 Unauthorized|Bearer realm="Your realm name", error="invalid_token", error_description="Token cannot be authenticated"|If the token is unregistered or invalid and cannot be authenticated.This is the case when the return value of the optional tokenCheckCallback method is FALASE.| |400 Bad Request|Bearer realm="Your realm name", error="invalid_request"|In case of request body validation error.This is the case when the return value of the optional requestParameterCheck method is FALASE.|

  import express from 'express';
  import {BearerParser, BearerValidator} from 'bearer-token-parser';
  import {body, validationResult} from 'express-validator';
  
  const router = express.Router();
  router.post('/', [
      // Validation of input data by express-validator.
      body('email').isEmail(),
      body('name').isLength({min: 1, max: 20}),
  
      // Token authentication middleware initialization.
      BearerValidator.validation({
          // // Select the Token location as header/body/query.
          // tokenLocation: 'query',
  
          // // If the token location is query or body, specify the parameter name of the token.
          // tokenParameter: 'access_token',
  
          // Realm name to be included in response headers.
          realm: 'myapi',
          tokenCheckCallback: async (token) => {
              // Return `TRUE` if the token is correct.
              // If you return `FALSE`, a `401` error will be returned by the `BearerValidator.validation` middleware.
              return token === '<Your Bearer token>';
          },
          requestParameterCheck: (req) => {
              // Return `TRUE` if the input data is correct using `express-validator`.
              // If `FALSE` is returned, a `400` error is returned by the `BearerValidator.validation` middleware.
              const errors = validationResult(req);
              return errors.isEmpty();
          }
      }),
  ], async (req, res) => {
      // Get bearer token.
      const token = BearerParser.parseBearerTokenHeader(req);
  
      // Execute any process and response.
      res.json(true);
  });
  
  // mount the router on the app.
  app.use('/', router)

Testing

With npm do:

npm test

Author

Takuya Motoshima

• github/takuya-motoshima
• twitter/TakuyaMotoshima
• facebook/takuya.motoshima.7

License

MIT