Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
# express-jwt
[](http://travis-ci.org/auth0/express-jwt)
This module provides Express middleware for validating JWTs ([JSON Web Tokens](https://jwt.io)) through the [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken/) module. The decoded JWT payload is available on the request object.
## Install
```
$ npm install express-jwt
```
## Usage
Basic usage using an HS256 secret:
```javascript
var jwt = require('express-jwt');
app.get('/protected',
jwt({ secret: 'shhhhhhared-secret' }),
function(req, res) {
if (!req.user.admin) return res.sendStatus(401);
res.sendStatus(200);
});
```
The decoded JWT payload is available on the request via the `user` property. This can be configured using the `requestProperty` option ([see below](#retrieving-the-decoded-payload)).
> The default behavior of the module is to extract the JWT from the `Authorization` header as an [OAuth2 Bearer token](https://oauth.net/2/bearer-tokens/).
### Additional Options
You can specify audience and/or issuer as well:
```javascript
jwt({
secret: 'shhhhhhared-secret',
audience: 'http://myapi/protected',
issuer: 'http://issuer'
})
```
> If the JWT has an expiration (`exp`), it will be checked.
If you are using a base64 URL-encoded secret, pass a `Buffer` with `base64` encoding as the secret instead of a string:
```javascript
jwt({ secret: new Buffer('shhhhhhared-secret', 'base64') })
```
Optionally you can make some paths unprotected as follows:
```javascript
app.use(jwt({ secret: 'shhhhhhared-secret'}).unless({path: ['/token']}));
```
This is especially useful when applying to multiple routes. In the example above, `path` can be a string, a regexp, or an array of any of those.
> For more details on the `.unless` syntax including additional options, please see [express-unless](https://github.com/jfromaniello/express-unless).
This module also support tokens signed with public/private key pairs. Instead of a secret, you can specify a Buffer with the public key
```javascript
var publicKey = fs.readFileSync('/path/to/public.pub');
jwt({ secret: publicKey });
```
### Retrieving the Decoded Payload
By default, the decoded token is attached to `req.user` but can be configured with the `requestProperty` option.
```javascript
jwt({ secret: publicKey, requestProperty: 'auth' });
```
The token can also be attached to the `result` object with the `resultProperty` option. This option will override any `requestProperty`.
```javascript
jwt({ secret: publicKey, resultProperty: 'locals.user' });
```
Both `resultProperty` and `requestProperty` utilize [lodash.set](https://lodash.com/docs/4.17.2#set) and will accept nested property paths.
### Customizing Token Location
A custom function for extracting the token from a request can be specified with
the `getToken` option. This is useful if you need to pass the token through a
query parameter or a cookie. You can throw an error in this function and it will
be handled by `express-jwt`.
```javascript
app.use(jwt({
secret: 'hello world !',
credentialsRequired: false,
getToken: function fromHeaderOrQuerystring (req) {
if (req.headers.authorization && req.headers.authorization.split(' ')[0] === 'Bearer') {
return req.headers.authorization.split(' ')[1];
} else if (req.query && req.query.token) {
return req.query.token;
}
return null;
}
}));
```
### Multi-tenancy
If you are developing an application in which the secret used to sign tokens is not static, you can provide a callback function as the `secret` parameter. The function has the signature: `function(req, payload, done)`:
* `req` (`Object`) - The express `request` object.
* `payload` (`Object`) - An object with the JWT claims.
* `done` (`Function`) - A function with signature `function(err, secret)` to be invoked when the secret is retrieved.
* `err` (`Any`) - The error that occurred.
* `secret` (`String`) - The secret to use to verify the JWT.
For example, if the secret varies based on the [JWT issuer](http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#issDef):
```javascript
var jwt = require('express-jwt');
var data = require('./data');
var utilities = require('./utilities');
var secretCallback = function(req, payload, done){
var issuer = payload.iss;
data.getTenantByIdentifier(issuer, function(err, tenant){
if (err) { return done(err); }
if (!tenant) { return done(new Error('missing_secret')); }
var secret = utilities.decrypt(tenant.secret);
done(null, secret);
});
};
app.get('/protected',
jwt({ secret: secretCallback }),
function(req, res) {
if (!req.user.admin) return res.sendStatus(401);
res.sendStatus(200);
});
```
### Revoked tokens
It is possible that some tokens will need to be revoked so they cannot be used any longer. You can provide a function as the `isRevoked` option. The signature of the function is `function(req, payload, done)`:
* `req` (`Object`) - The express `request` object.
* `payload` (`Object`) - An object with the JWT claims.
* `done` (`Function`) - A function with signature `function(err, revoked)` to be invoked once the check to see if the token is revoked or not is complete.
* `err` (`Any`) - The error that occurred.
* `revoked` (`Boolean`) - `true` if the JWT is revoked, `false` otherwise.
For example, if the `(iss, jti)` claim pair is used to identify a JWT:
```javascript
var jwt = require('express-jwt');
var data = require('./data');
var utilities = require('./utilities');
var isRevokedCallback = function(req, payload, done){
var issuer = payload.iss;
var tokenId = payload.jti;
data.getRevokedToken(issuer, tokenId, function(err, token){
if (err) { return done(err); }
return done(null, !!token);
});
};
app.get('/protected',
jwt({
secret: 'shhhhhhared-secret',
isRevoked: isRevokedCallback
}),
function(req, res) {
if (!req.user.admin) return res.sendStatus(401);
res.sendStatus(200);
}
);
```
### 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:
```javascript
app.use(function (err, req, res, next) {
if (err.name === 'UnauthorizedError') {
res.status(401).send('invalid token...');
}
});
```
You might want to use this module to identify registered users while still providing access to unregistered users. You can do this by using the option `credentialsRequired`:
```javascript
app.use(jwt({
secret: 'hello world !',
credentialsRequired: false
}));
```
## Related Modules
- [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken) — JSON Web Token sign and verification
- [express-jwt-permissions](https://github.com/MichielDeMey/express-jwt-permissions) - Permissions middleware for JWT tokens
## Tests
```
$ npm install
$ npm test
```
## Contributors
Check them out [here](https://github.com/auth0/express-jwt/graphs/contributors)
## 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](auth0.com)
## License
This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.