Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/auth0/express-jwt-authz
Validate the JWT scope to authorize access to an endpoint
https://github.com/auth0/express-jwt-authz
dx-sdk express jwt
Last synced: 11 days ago
JSON representation
Validate the JWT scope to authorize access to an endpoint
- Host: GitHub
- URL: https://github.com/auth0/express-jwt-authz
- Owner: auth0
- License: mit
- Created: 2016-05-21T04:20:22.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-02-08T18:57:10.000Z (5 months ago)
- Last Synced: 2024-05-16T23:42:15.701Z (about 2 months ago)
- Topics: dx-sdk, express, jwt
- Language: JavaScript
- Homepage:
- Size: 83 KB
- Stars: 94
- Watchers: 80
- Forks: 37
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: Changelog.md
- License: LICENSE
Lists
- awesome-jwt - express-jwt-authz - Validate the JWT scope to authorize access to an endpoint. (Libraries / Node.js)
README
# express-jwt-authz 
Validate a JWTs `scope` to authorize access to an endpoint.
## Install
$ npm install express-jwt-authz
> `express@^4.0.0` is a peer dependency. Make sure it is installed in your project.
## Usage
Use together with [express-jwt](https://github.com/auth0/express-jwt) to both validate a JWT and make sure it has the correct permissions to call an endpoint.
:note: `express-jwt` sets the decoded JWT payload on `req.auth` since version `6.0.0`, so make sure to set `customUserKey: 'auth'` in the options provided to `express-jwt-authz` if you are using that version or newer.
```javascript
var jwt = require('express-jwt');
var jwtAuthz = require('express-jwt-authz');
var options = { customUserKey: 'auth' };
app.get('/users',
jwt({ secret: 'shared_secret' }),
jwtAuthz([ 'read:users' ], options),
function(req, res) { ... });
```
If multiple scopes are provided, the user must have _at least one_ of the specified scopes.
```javascript
var options = { customUserKey: 'auth' };
app.post('/users',
jwt({ secret: 'shared_secret' }),
jwtAuthz([ 'read:users', 'write:users' ], options),
function(req, res) { ... });
// This user will be granted access
var authorizedUser = {
scope: 'read:users'
};
```
To check that the user has _all_ the scopes provided, use the `checkAllScopes: true` option:
```javascript
app.post('/users',
jwt({ secret: 'shared_secret' }),
jwtAuthz([ 'read:users', 'write:users' ], { checkAllScopes: true, customUserKey: 'auth' }),
function(req, res) { ... });
// This user will have access
var authorizedUser = {
scope: 'read:users write:users'
};
// This user will NOT have access
var unauthorizedUser = {
scope: 'read:users'
};
```
The JWT must have a `scope` claim and it must either be a string of space-separated permissions or an array of strings. For example:
```
// String:
"write:users read:users"
// Array:
["write:users", "read:users"]
```
## Options
- `failWithError`: When set to `true`, will forward errors to `next` instead of ending the response directly. Defaults to `false`.
- `checkAllScopes`: When set to `true`, all the expected scopes will be checked against the user's scopes. Defaults to `false`.
- `customUserKey`: The property name to check for the scope key. By default, permissions are checked against `req.user`, but you can change it to be `req.myCustomUserKey` with this option. Defaults to `user`.
- `customScopeKey`: The property name to check for the actual scope. By default, permissions are checked against `user.scope`, but you can change it to be `user.myCustomScopeKey` with this option. Defaults to `scope`.
## Issue Reporting
If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.
## Author
[Auth0](https://auth0.com)
## License
This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.