OAuth 2.0 token server and module for Blueprint.js
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
app
bin
examples
lib
tests
.gitignore
.npmignore
.travis.yml
LICENSE
README.md
package-lock.json
package.json
yarn.lock

README.md

Gatekeeper

OAuth 2.0 token server and module for Blueprint.js

npm version Build Status Dependencies Coverage Status

Installation

yarn add @onehilltech/blueprint-gatekeeper

or

npm install @onehilltech/blueprint-gatekeeper --save

Getting Started

Defining the configuration

Gatekeeper uses JSON Web Tokens to manage authorization of authenticated users. To get started, you must first configure the options for token generation. The options supported are the same as those in node-jsonwebtoken.

// app/configs/gatekeeper.js

module.exports = {
 tokens: {
     // This is the base options for all token generators.
     $: {
       issuer: '[your-issuer-name-here]',
       expiresIn: '1h',
       algorithm: 'HS256',
       secret: 'ssshhh'
     }
 },
};

The jwtid option is not supported since Gatekeeper uses it to generate a unique id for each token.

Mount Gatekeeper router endpoint

Next, we need to import (or mount) the Gatekeeper router into our application. This will expose routes for managing and authenticating accounts and clients.

// app/routers/endpoint.js

const blueprint = require ('@onehilltech/blueprint');
const { Router } = blueprint;

module.exports = Router.extend ({
  specification: {
    '/gatekeeper': blueprint.mount ('@onehilltech/blueprint-gatekeeper:v1')    
  }
});

In the example above, we are mounting the v1 router to the /gatekeeper endpoint. This means that all routers in v1 will be accessible at http://[hostname]/gatekeeper/.

Protecting routes

The last step is to define what routes require authorization (i.e., are protected) using the gatekeeper.auth.bearer Blueprint policy.

// app/routers/endpoint.js

const blueprint = require ('@onehilltech/blueprint');
const { Router } = blueprint;

module.exports = Router.extend ({
  specification: {
    '/gatekeeper': blueprint.mount ('@onehilltech/blueprint-gatekeeper:v1'),
    
    // Let's protect the /v1 routes.
    '/v1': {
      policy: 'gatekeeper.auth.bearer'
    }  
  }
});

In the example above, the router will protect all routes under the /v1 path, which also includes all routers located in app/routers/v1 directory. The client will need to define the Authorization header and include a generated token.

Accessing the Authorized User

The req.user property contains the account model for an authorized user making the request to access a protected route. For example, here is an example of setting the user making the request as the owner of a created resource.

const { model } = require ('@onehilltech/blueprint');
const { ResourceController } = require ('@onehilltech/blueprint-mongodb');

module.exports = ResourceController.extend ({
  Model: model ('tweet'),
  
  create () {
    return this._super (this, ...arguments).extend ({
      prepareDocument (req, doc) {
        // Make the authorized user the owner of the created resource.
        doc.user = req.user._id;
        return doc;
      }
    });
  }
});

Gatekeeper has a UserResourceController that automatically adds the authorized user making the request as the owner of the resource being created.

Cross-Origin Resource Sharing (CORS)

Cross-Origin Resource Sharing (CORS) is a mechanism that allows a client from one domain to access resources from another domain. This typically occurs when you have a web browser accessing an API protected by Gatekeeper. If you need to enable CORS support for your Blueprint application, then use the gatekeeper.cors() middleware:

// app/routes/v1.js

const { env } = require ('@onehilltech/blueprint');
const { cors } = require ('@onehilltech/blueprint-gatekeeper');

module.exports = {
  '/v1': {
    use: [cors ({
      origin: env !== 'production' ? true : null
    })]
  }
};

Now, any request for a route that begins with /v1 will support CORS. The gatekeeper.cors() middleware is a wrapper around Express CORS. It will check if the origin in the request matches any registered client only when running in production. All other times, CORS is enabled by default regardless of the origin in the request.

Gatekeeper Client Libraries

Next Steps

See the Wiki for more information.