{"id":13796718,"url":"https://github.com/MichielDeMey/express-jwt-permissions","last_synced_at":"2025-05-13T00:31:07.430Z","repository":{"id":2906170,"uuid":"47852082","full_name":"MichielDeMey/express-jwt-permissions","owner":"MichielDeMey","description":":vertical_traffic_light: Express middleware for JWT permissions","archived":false,"fork":false,"pushed_at":"2023-02-06T12:02:27.000Z","size":509,"stargazers_count":518,"open_issues_count":8,"forks_count":37,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-04-14T12:16:14.054Z","etag":null,"topics":["express","jwt","middleware","permissions"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MichielDeMey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["MichielDeMey"]}},"created_at":"2015-12-11T21:31:59.000Z","updated_at":"2024-03-12T00:11:58.000Z","dependencies_parsed_at":"2023-02-19T07:10:32.709Z","dependency_job_id":null,"html_url":"https://github.com/MichielDeMey/express-jwt-permissions","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichielDeMey%2Fexpress-jwt-permissions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichielDeMey%2Fexpress-jwt-permissions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichielDeMey%2Fexpress-jwt-permissions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MichielDeMey%2Fexpress-jwt-permissions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MichielDeMey","download_url":"https://codeload.github.com/MichielDeMey/express-jwt-permissions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224937476,"owners_count":17395119,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["express","jwt","middleware","permissions"],"created_at":"2024-08-03T23:01:14.190Z","updated_at":"2024-11-18T10:31:32.939Z","avatar_url":"https://github.com/MichielDeMey.png","language":"JavaScript","funding_links":["https://github.com/sponsors/MichielDeMey"],"categories":["JavaScript","Libraries"],"sub_categories":["Node.js"],"readme":"# Express JWT Permissions\n\n[![Node.js CI](https://github.com/MichielDeMey/express-jwt-permissions/workflows/Node.js%20CI/badge.svg)](https://github.com/MichielDeMey/express-jwt-permissions/actions?query=workflow%3A%22Node.js+CI%22)\n[![CodeQL](https://github.com/MichielDeMey/express-jwt-permissions/actions/workflows/codeql-analysis.yml/badge.svg?branch=master)](https://github.com/MichielDeMey/express-jwt-permissions/actions/workflows/codeql-analysis.yml)\n[![codecov](https://codecov.io/gh/MichielDeMey/express-jwt-permissions/branch/master/graph/badge.svg?token=UXWXehGp1x)](https://codecov.io/gh/MichielDeMey/express-jwt-permissions)\n[![npm](https://img.shields.io/npm/dm/express-jwt-permissions.svg?maxAge=2592000)](https://www.npmjs.com/package/express-jwt-permissions)\n[![](https://img.shields.io/static/v1?label=Sponsor\u0026message=%E2%9D%A4\u0026logo=GitHub\u0026color=%23fe8e86)](https://github.com/sponsors/MichielDeMey)\n\n[![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard)\n\nMiddleware that checks JWT tokens for permissions, recommended to be used in conjunction with [express-jwt](https://github.com/auth0/express-jwt).\n\n## Install\n\n```\nnpm install express-jwt-permissions --save\n```\n\n## Usage\n\nThis middleware assumes you already have a JWT authentication middleware such as [express-jwt](https://github.com/auth0/express-jwt).\n\nThe middleware will check a decoded JWT token to see if a token has permissions to make a certain request.\n\nPermissions should be described as an array of strings inside the JWT token, or as a space-delimited [OAuth 2.0 Access Token Scope](https://tools.ietf.org/html/rfc6749#section-3.3) string.\n\n```json\n\"permissions\": [\n  \"status\",\n  \"user:read\",\n  \"user:write\"\n]\n```\n\n```json\n\"scope\": \"status user:read user:write\"\n```\n\nIf your JWT structure looks different you should map or reduce the results to produce a simple Array or String of permissions.\n\n### Using permission Array\nTo verify a permission for all routes using an array:\n\n```javascript\nvar guard = require('express-jwt-permissions')()\n\napp.use(guard.check('admin'))\n```\n\nIf you require different permissions per route, you can set the middleware per route.\n\n```javascript\nvar guard = require('express-jwt-permissions')()\n\napp.get('/status', guard.check('status'), function(req, res) { ... })\napp.get('/user', guard.check(['user:read']), function(req, res) { ... })\n```\n\nLogical combinations of required permissions can be made using nested arrays.\n\nSingle string\n```js\n// Required: \"admin\"\napp.use(guard.check(\n  'admin'\n))\n```\n\nArray of strings\n\n```javascript\n// Required: \"read\" AND \"write\"\napp.use(guard.check(\n  ['read', 'write']\n))\n```\n\nArray of arrays of strings\n\n```javascript\n// Required: \"read\" OR \"write\"\napp.use(guard.check([\n  ['read'],\n  ['write']\n]))\n\n// Required: \"admin\" OR (\"read\" AND \"write\")\napp.use(guard.check([\n  ['admin'],\n  ['read', 'write']\n]))\n```\n\n### Configuration\nTo set where the module can find the user property (default `req.user`) you can set the `requestProperty` option.\n\nTo set where the module can find the permissions property inside the `requestProperty` object (default `permissions`), set the `permissionsProperty` option.\n\nExample:\n\nConsider you've set your permissions as `scope` on `req.identity`, your JWT structure looks like:\n\n```json\n\"scope\": \"user:read user:write\"\n```\n\nYou can pass the configuration into the module:\n\n```javascript\nvar guard = require('express-jwt-permissions')({\n  requestProperty: 'identity',\n  permissionsProperty: 'scope'\n})\n\napp.use(guard.check('user:read'))\n```\n\n## Error handling\n\nThe 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:\n\n```javascript\napp.use(guard.check('admin'))\n\napp.use(function (err, req, res, next) {\n  if (err.code === 'permission_denied') {\n    res.status(403).send('Forbidden');\n  }\n});\n```\n\n**Note** that your error handling middleware should be defined after the jwt-permissions middleware.\n\n## Excluding paths\n\nThis library has integration with [express-unless](https://github.com/jfromaniello/express-unless) to allow excluding paths, please refer to their [usage](https://github.com/jfromaniello/express-unless#usage).\n\n```javascript\nconst checkForPermissions = guard\n  .check(['admin'])\n  .unless({ path: '/not-secret' })\n\napp.use(checkForPermissions)\n```\n\n## Tests\n\n```\n$ npm install\n$ npm test\n```\n\n## License\n\nThis project is licensed under the MIT license. See the [LICENSE](LICENSE.txt) file for more info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMichielDeMey%2Fexpress-jwt-permissions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMichielDeMey%2Fexpress-jwt-permissions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMichielDeMey%2Fexpress-jwt-permissions/lists"}