express-jwt-permissions
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.6 • Public • Published

    Express JWT Permissions

    Node.js CI CodeQL codecov npm

    js-standard-style

    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.

    Install

    npm i express-jwt-permissions

    DownloadsWeekly Downloads

    9,766

    Version

    1.3.6

    License

    MIT

    Unpacked Size

    19.7 kB

    Total Files

    11

    Last publish

    Collaborators

    • angryunicorn
    • michieldemey