MichielDeMey / Express Jwt Permissions
Programming Languages
Projects that are alternatives of or similar to Express Jwt Permissions
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.
"permissions": [
"status",
"user:read",
"user:write"
]
"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.
Using permission Array
To verify a permission for all routes using an array:
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.
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
// Required: "admin"
app.use(guard.check(
'admin'
))
Array of strings
// Required: "read" AND "write"
app.use(guard.check(
['read', 'write']
))
Array of arrays of strings
// Required: "read" OR "write"
app.use(guard.check([
['read'],
['write']
]))
// Required: "admin" OR ("read" AND "write")
app.use(guard.check([
['admin'],
['read', 'write']
]))
Configuration
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:
"scope": "user:read user:write"
You can pass the configuration into the module:
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:
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.
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.