1 | <p align="center">
|
2 | <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo_text.svg" width="320" alt="Nest Logo" /></a>
|
3 | </p>
|
4 |
|
5 | [travis-image]: https://api.travis-ci.org/nestjs/nest.svg?branch=master
|
6 | [travis-url]: https://travis-ci.org/nestjs/nest
|
7 | [linux-image]: https://img.shields.io/travis/nestjs/nest/master.svg?label=linux
|
8 | [linux-url]: https://travis-ci.org/nestjs/nest
|
9 |
|
10 | <p align="center">A progressive <a href="http://nodejs.org" target="blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
|
11 | <p align="center">
|
12 | <a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
|
13 | <a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
|
14 | <a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/dm/@nestjs/core.svg" alt="NPM Downloads" /></a>
|
15 | <a href="https://travis-ci.org/nestjs/nest"><img src="https://api.travis-ci.org/nestjs/nest.svg?branch=master" alt="Travis" /></a>
|
16 | <a href="https://travis-ci.org/nestjs/nest"><img src="https://img.shields.io/travis/nestjs/nest/master.svg?label=linux" alt="Linux" /></a>
|
17 | <a href="https://coveralls.io/github/nestjs/nest?branch=master"><img src="https://coveralls.io/repos/github/nestjs/nest/badge.svg?branch=master#5" alt="Coverage" /></a>
|
18 | <a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
|
19 | <a href="https://opencollective.com/nest#backer"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
|
20 | <a href="https://opencollective.com/nest#sponsor"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
|
21 | <a href="https://paypal.me/kamilmysliwiec"><img src="https://img.shields.io/badge/Donate-PayPal-dc3d53.svg"/></a>
|
22 | <a href="https://twitter.com/nestframework"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow"></a>
|
23 | </p>
|
24 | |
25 | [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
|
26 |
|
27 | ## Description
|
28 |
|
29 | JWT utilities module for [Nest](https://github.com/nestjs/nest) based on the [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken) package.
|
30 |
|
31 | ## Installation
|
32 |
|
33 | ```bash
|
34 | $ npm i --save @nestjs/jwt
|
35 | ```
|
36 |
|
37 | ## Usage
|
38 |
|
39 | Import `JwtModule`:
|
40 |
|
41 | ```typescript
|
42 | @Module({
|
43 | imports: [JwtModule.register({ secret: 'hard!to-guess_secret' })],
|
44 | providers: [...],
|
45 | })
|
46 | export class AuthModule {}
|
47 | ```
|
48 |
|
49 | Inject `JwtService`:
|
50 |
|
51 | ```typescript
|
52 | @Injectable()
|
53 | export class AuthService {
|
54 | constructor(private readonly jwtService: JwtService) {}
|
55 | }
|
56 | ```
|
57 |
|
58 | ## Secret / Encryption Key options
|
59 |
|
60 | If you want to control secret and key management dynamically you can use the `secretOrKeyProvider` function for that purpose.
|
61 |
|
62 | ```typescript
|
63 | JwtModule.register({
|
64 | /* Secret has precedence over keys */
|
65 | secret: 'hard!to-guess_secret',
|
66 |
|
67 | /* public key used in asymmetric algorithms (required if non other secrets present) */
|
68 | publicKey: '...',
|
69 |
|
70 | /* private key used in asymmetric algorithms (required if non other secrets present) */
|
71 | privateKey: '...',
|
72 |
|
73 | /* Dynamic key provider has precedence over static secret or pub/private keys */
|
74 | secretOrKeyProvider: (
|
75 | requestType: JwtSecretRequestType,
|
76 | tokenOrPayload: string | Object | Buffer,
|
77 | verifyOrSignOrOptions?: jwt.VerifyOptions | jwt.SignOptions
|
78 | ) => {
|
79 | switch (requestType) {
|
80 | case JwtSecretRequestType.SIGN:
|
81 | // retrieve signing key dynamically
|
82 | return 'privateKey';
|
83 | case JwtSecretRequestType.VERIFY:
|
84 | // retrieve public key for verification dynamically
|
85 | return 'publicKey';
|
86 | default:
|
87 | // retrieve secret dynamically
|
88 | return 'hard!to-guess_secret';
|
89 | }
|
90 | },
|
91 | });
|
92 | ```
|
93 |
|
94 | ## Async options
|
95 |
|
96 | Quite often you might want to asynchronously pass your module options instead of passing them beforehand. In such case, use `registerAsync()` method, that provides a couple of various ways to deal with async data.
|
97 |
|
98 | **1. Use factory**
|
99 |
|
100 | ```typescript
|
101 | JwtModule.registerAsync({
|
102 | useFactory: () => ({
|
103 | secret: 'hard!to-guess_secret'
|
104 | })
|
105 | });
|
106 | ```
|
107 |
|
108 | Obviously, our factory behaves like every other one (might be `async` and is able to inject dependencies through `inject`).
|
109 |
|
110 | ```typescript
|
111 | JwtModule.registerAsync({
|
112 | imports: [ConfigModule],
|
113 | useFactory: async (configService: ConfigService) => ({
|
114 | secret: configService.get<string>('SECRET'),
|
115 | }),
|
116 | inject: [ConfigService],
|
117 | }),
|
118 | ```
|
119 |
|
120 | **2. Use class**
|
121 |
|
122 | ```typescript
|
123 | JwtModule.registerAsync({
|
124 | useClass: JwtConfigService
|
125 | });
|
126 | ```
|
127 |
|
128 | Above construction will instantiate `JwtConfigService` inside `JwtModule` and will leverage it to create options object.
|
129 |
|
130 | ```typescript
|
131 | class JwtConfigService implements JwtOptionsFactory {
|
132 | createJwtOptions(): JwtModuleOptions {
|
133 | return {
|
134 | secret: 'hard!to-guess_secret'
|
135 | };
|
136 | }
|
137 | }
|
138 | ```
|
139 |
|
140 | **3. Use existing**
|
141 |
|
142 | ```typescript
|
143 | JwtModule.registerAsync({
|
144 | imports: [ConfigModule],
|
145 | useExisting: ConfigService,
|
146 | }),
|
147 | ```
|
148 |
|
149 | It works the same as `useClass` with one critical difference - `JwtModule` will lookup imported modules to reuse already created `ConfigService`, instead of instantiating it on its own.
|
150 |
|
151 | ## API Spec
|
152 |
|
153 | The `JwtService` uses [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken) underneath.
|
154 |
|
155 | #### jwtService.sign(payload: string | Object | Buffer, options?: JwtSignOptions): string
|
156 |
|
157 | The sign method is an implementation of jsonwebtoken `.sign()`. Differing from jsonwebtoken it also allows an additional `secret`, `privateKey`, and `publicKey` properties on `options` to override options passed in from the module. It only overrides the `secret`, `publicKey` or `privateKey` though not a `secretOrKeyProvider`.
|
158 |
|
159 | #### jwtService.signAsync(payload: string | Object | Buffer, options?: JwtSignOptions): Promise\<string\>
|
160 |
|
161 | The asynchronous `.sign()` method.
|
162 |
|
163 | #### jwtService.verify\<T extends object = any>(token: string, options?: JwtVerifyOptions): T
|
164 |
|
165 | The verify method is an implementation of jsonwebtoken `.verify()`. Differing from jsonwebtoken it also allows an additional `secret`, `privateKey`, and `publicKey` properties on `options` to override options passed in from the module. It only overrides the `secret`, `publicKey` or `privateKey` though not a `secretOrKeyProvider`.
|
166 |
|
167 | #### jwtService.verifyAsync\<T extends object = any>(token: string, options?: JwtVerifyOptions): Promise\<T\>
|
168 |
|
169 | The asynchronous `.verify()` method.
|
170 |
|
171 | #### jwtService.decode(token: string, options: DecodeOptions): object | string
|
172 |
|
173 | The decode method is an implementation of jsonwebtoken `.decode()`.
|
174 |
|
175 | The `JwtModule` takes an `options` object:
|
176 |
|
177 | - `secret` is either a string, buffer, or object containing the secret for HMAC algorithms
|
178 | - `secretOrKeyProvider` function with the following signature `(requestType, tokenOrPayload, options?) => jwt.Secret` (allows generating either secrets or keys dynamically)
|
179 | - `signOptions` [read more](https://github.com/auth0/node-jsonwebtoken#jwtsignpayload-secretorprivatekey-options-callback)
|
180 | - `privateKey` PEM encoded private key for RSA and ECDSA with passphrase an object `{ key, passphrase }` [read more](https://github.com/auth0/node-jsonwebtoken#jwtsignpayload-secretorprivatekey-options-callback)
|
181 | - `publicKey` PEM encoded public key for RSA and ECDSA
|
182 | - `verifyOptions` [read more](https://github.com/auth0/node-jsonwebtoken#jwtverifytoken-secretorpublickey-options-callback)
|
183 | - `secretOrPrivateKey` (DEPRECATED!) [read more](https://github.com/auth0/node-jsonwebtoken#jwtsignpayload-secretorprivatekey-options-callback)
|
184 |
|
185 | ## Support
|
186 |
|
187 | Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
|
188 |
|
189 | ## Stay in touch
|
190 |
|
191 | - Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
|
192 | - Website - [https://nestjs.com](https://nestjs.com/)
|
193 | - Twitter - [@nestframework](https://twitter.com/nestframework)
|
194 |
|
195 | ## License
|
196 |
|
197 | Nest is [MIT licensed](LICENSE).
|