Express JWT Permissions



Middleware that checks JWT tokens for permissions, recommended to be used in conjunction with express-jwt.

Install

``
npm install express-jwt-permissions --save
`

Usage

This middleware assumes you already have a JWT authentication middleware such as express-jwt.

The middleware will check a decoded JWT token to see if a token has permissions to make a certain request.

Permissions should be described as an array of strings inside the JWT token, or as a space-delimited OAuth 2.0 Access Token Scope string.

`json
"permissions": [
"status",
"user:read",
"user:write"
]
`

`json
"scope": "status user:read user:write"
`

If your JWT structure looks different you should map or reduce the results to produce a simple Array or String of permissions.

$3

To verify a permission for all routes using an array:

`javascript
var guard = require('express-jwt-permissions')()

app.use(guard.check('admin'))
`

If you require different permissions per route, you can set the middleware per route.

`javascript
var guard = require('express-jwt-permissions')()

app.get('/status', guard.check('status'), function(req, res) { ... })
app.get('/user', guard.check(['user:read']), function(req, res) { ... })
`

Logical combinations of required permissions can be made using nested arrays.

Single string
`js
// Required: "admin"
app.use(guard.check(
'admin'
))
`

Array of strings

`javascript
// Required: "read" AND "write"
app.use(guard.check(
['read', 'write']
))
`

Array of arrays of strings

`javascript
// Required: "read" OR "write"
app.use(guard.check([
['read'],
['write']
]))

// Required: "admin" OR ("read" AND "write")
app.use(guard.check([
['admin'],
['read', 'write']
]))
`

$3


To set where the module can find the user property (default req.user) you can set the requestProperty option.

To set where the module can find the permissions property inside the requestProperty object (default permissions), set the permissionsProperty option.

Example:

Consider you've set your permissions as scope on req.identity, your JWT structure looks like:

`json
"scope": "user:read user:write"
`

You can pass the configuration into the module:

`javascript
var guard = require('express-jwt-permissions')({
requestProperty: 'identity',
permissionsProperty: 'scope'
})

app.use(guard.check('user:read'))
`

Error handling

The default behavior is to throw an error when the token is invalid, so you can add your custom logic to manage unauthorized access as follows:

`javascript
app.use(guard.check('admin'))

app.use(function (err, req, res, next) {
if (err.code === 'permission_denied') {
res.status(403).send('Forbidden');
}
});
`

Note that your error handling middleware should be defined after the jwt-permissions middleware.

Excluding paths

This library has integration with express-unless to allow excluding paths, please refer to their usage.

`javascript
const checkForPermissions = guard
.check(['admin'])
.unless({ path: '/not-secret' })

app.use(checkForPermissions)
`

Tests

`
$ npm install
$ npm test
``

License

This project is licensed under the MIT license. See the LICENSE file for more info.