# express-jwt-authz

> Validate a JWTs scope to authorize access to an endpoint

Latest version **2.4.1** (published 2020-07-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install express-jwt-authz
pnpm add express-jwt-authz
yarn add express-jwt-authz
bun add express-jwt-authz
```

## Health

**Score 40/100 (D)** — status: abandoned.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 2.4.1 |
| Published | 2020-07-21 |
| First published | 2016-05-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=6 |
| Dependencies | 0 |
| Unpacked size | 7.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 98 |
| Author | Damian Schenkelman |
| Maintainers | aaguiarz, adamjmcgrath, auth0alec, auth0brokkr, auth0npm, bmaxwella0, cocojoe, cristiandouce, davidmoses, davidpatrick0, donflopez, dschenkelman, faroceann, fyockm, glena, heyitsry, hzalaz, iaco, jfromaniello, joshcanhelp, jstrutz, lbalmaceda, ldoorz, luisrudge, luuuis, lzychowski, machuga, matchai, rob.coles, rosnovsky, sambego, sandrinodimattia, shawnmclean, stevehobbsdev, th3maio, widcket, yacine-b, ziluvatar |
| Keywords | express, jwt, authorization |

## Links

- npm: https://www.npmjs.com/package/express-jwt-authz
- Repository: https://github.com/auth0/express-jwt-authz
- Homepage: https://github.com/auth0/express-jwt-authz#readme
- Issues: https://github.com/auth0/express-jwt-authz/issues
- npm.io page: https://npm.io/package/express-jwt-authz

## Alternatives

- [@clerk/clerk-expo](https://npm.io/package/@clerk/clerk-expo.md) — 133.6K weekly downloads
- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads

## Recent versions

- 2.4.1 (latest) — 2020-07-21
- 2.4.0 — 2020-06-12
- 2.3.1 — 2019-04-08
- 2.3.0 — 2019-03-21
- 2.2.0 — 2019-03-15
- 2.1.1 — 2019-02-28
- 2.1.0 — 2019-02-22
- 1.0.0 — 2016-05-23

## README

# express-jwt-authz ![](https://travis-ci.org/auth0/express-jwt-authz.svg?branch=master)

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.

```javascript
var jwt = require('express-jwt');
var jwtAuthz = require('express-jwt-authz');

var options = {};
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
app.post('/users',
  jwt({ secret: 'shared_secret' }),
  jwtAuthz([ 'read:users', 'write:users' ], {}),
  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 }),
  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.

---
_Source: https://npm.io/package/express-jwt-authz · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._