fastify-casbin-rest

A plugin for Fastify that adds support for Casbin RESTful model.

It depends and builds on top of fastify-casbin and provides an opinionated approach to model an authorization scheme based on a RESTful model using Casbin Node.js APIs within a Fastify application.

Install

npm i casbin fastify-casbin fastify-casbin-rest

fastify-casbin must be registered in the Fastify instance

How it works

Once registered, the plugin use the Fastify instance decorated by fastify-casbin and will automatically enforce authorization rules to routes where the plugin is enabled.

It uses the default Casbin's sub, obj and act entities and extracts them automatically from the request.

When a rule is not satisfied, it returns a 403 Forbidden error by default.

All the options can be customized when registering the plugin.

API

The plugin must be explicitly enabled on individual routes via route options. The plugin will have no effect on routes on which it is not enabled.

fastify.route({
  // ... other route options
  casbin: {
    rest: true
  }
})

Route options

This plugin introduces new route option casbin.rest. It can be either a true value (which enables default configuration) or an object. Supported object options:

| Option | Type | Description | Default | | -------- | ------------------------------- | -------------------------------------------- | --------------------------- | | getSub | Request => string or string | Extracts sub from the request or constant | Value from plugin options | | getDom | Request => string or string | Extracts dom from the request or constant | Value from plugin options | | getObj | Request => string or string | Extracts obj from the request or constant | Value from plugin options | | getAct | Request => string or string | Extracts act from the request or constant | Value from plugin options |

Plugin options

The API exposed by this plugin is the configuration options:

| Option | Type | Description | Default | | -------- | ---------------------------------------------------------- | ------------------------------------------------- | ------------------------------- | | getSub | Request => string | Extracts sub from the request | r => r.user | | getDom | Request => string | Extracts dom from the request | undefined | | getObj | Request => string | Extracts obj from the request | r => r.url | | getAct | Request => string | Extracts act from the request | r => r.method | | onDeny | (Reply, { sub, obj, act, dom }) => any | Invoked when Casbin's enforce resolves to false | Returns a 403 Forbidden error | | onAllow| (Reply, { sub, obj, act, dom }) => any | Invoked when Casbin's enforce resolves to true | noop | | log | (Fastify, Request, { sub, obj, act, dom }) => void | Invoked before invoking Casbin's enforce | Logs using fastify.log.info | | hook | 'onRequest', 'preParsing', 'preValidation', 'preHandler' | Which lifecycle to use for performing the check | 'preHandler' |

Note that extraction rules defined within route options take precedence over the rules defined in the plugin options. If getDom is not set either on a route nor on a plugin level, enforcer is invoked with (sub, obj, act). If getDom is set, enforcer is invoked with (sub, dom, obj, act).

Examples

A working example can be found in the examples folder.

The example below uses fastify-jwt to authenticate users and extract user information from the request. It uses sample REST model and policy files.

const fastify = require('fastify')()

// register jwt plugin
fastify.register(require('fastify-jwt'), {
  secret: 'some secret'
})

// register casbin plugin
fastify.register(require('fastify-casbin'), {
  modelPath: 'rest_model.conf', // the model configuration
  adapter: 'rest_policy.csv' // the adapter
})

// register and configure casbin-rest plugin
fastify.register(require('fastify-casbin-rest'), {
  getSub: r => r.user.payload.username
})

// decorate Fastify instance with authenticate method
fastify.decorate('authenticate', async function (request, reply) {
  try {
    await request.jwtVerify()
  } catch (err) {
    reply.send(err)
  }
})

// sample login endpoint which always authenticates the user
fastify.post('/login', async request => {
  return fastify.jwt.sign({ payload: { username: 'alice' } })
})

fastify.get(
  '/protected',
  {
    // ensure user is authenticated
    preValidation: [fastify.authenticate],
    // enable fastify-casbin-rest plugin on this route, override default "getObj" rule
    casbin: {
      rest: {
        getSub: request => request.userId,
        getAct: 'read'
      },
    }
  },
  async () => `You're in!`
)

License

Licensed under MIT License