README.md

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