[travis-image]: https://api.travis-ci.org/nestjs/nest.svg?branch=master
[travis-url]: https://travis-ci.org/nestjs/nest
[linux-image]: https://img.shields.io/travis/nestjs/nest/master.svg?label=linux
[linux-url]: https://travis-ci.org/nestjs/nest
A progressive Node.js framework for building efficient and scalable server-side applications.
## Description
JWT utilities module for [Nest](https://github.com/nestjs/nest) based on the [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken) package.
## Installation
```bash
$ npm i --save @nestjs/jwt
```
## Usage
Import `JwtModule`:
```typescript
@Module({
imports: [JwtModule.register({ secret: 'hard!to-guess_secret' })],
providers: [...],
})
export class AuthModule {}
```
Inject `JwtService`:
```typescript
@Injectable()
export class AuthService {
constructor(private readonly jwtService: JwtService) {}
}
```
## Secret / Encryption Key options
If you want to control secret and key management dynamically you can use the `secretOrKeyProvider` function for that purpose. You also can use asynchronous version of `secretOrKeyProvider`.
NOTE: For asynchronous version of `secretOrKeyProvider`, synchronous versions of `.sign()` and `.verify()` will throw an exception.
```typescript
JwtModule.register({
/* Secret has precedence over keys */
secret: 'hard!to-guess_secret',
/* public key used in asymmetric algorithms (required if non other secrets present) */
publicKey: '...',
/* private key used in asymmetric algorithms (required if non other secrets present) */
privateKey: '...',
/* Dynamic key provider has precedence over static secret or pub/private keys */
secretOrKeyProvider: (
requestType: JwtSecretRequestType,
tokenOrPayload: string | Object | Buffer,
verifyOrSignOrOptions?: jwt.VerifyOptions | jwt.SignOptions
) => {
switch (requestType) {
case JwtSecretRequestType.SIGN:
// retrieve signing key dynamically
return 'privateKey';
case JwtSecretRequestType.VERIFY:
// retrieve public key for verification dynamically
return 'publicKey';
default:
// retrieve secret dynamically
return 'hard!to-guess_secret';
}
},
});
```
## Async options
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.
**1. Use factory**
```typescript
JwtModule.registerAsync({
useFactory: () => ({
secret: 'hard!to-guess_secret'
})
});
```
Obviously, our factory behaves like every other one (might be `async` and is able to inject dependencies through `inject`).
```typescript
JwtModule.registerAsync({
imports: [ConfigModule],
useFactory: async (configService: ConfigService) => ({
secret: configService.get('SECRET'),
}),
inject: [ConfigService],
}),
```
**2. Use class**
```typescript
JwtModule.registerAsync({
useClass: JwtConfigService
});
```
Above construction will instantiate `JwtConfigService` inside `JwtModule` and will leverage it to create options object.
```typescript
class JwtConfigService implements JwtOptionsFactory {
createJwtOptions(): JwtModuleOptions {
return {
secret: 'hard!to-guess_secret'
};
}
}
```
**3. Use existing**
```typescript
JwtModule.registerAsync({
imports: [ConfigModule],
useExisting: ConfigService,
}),
```
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.
## API Spec
The `JwtService` uses [jsonwebtoken](https://github.com/auth0/node-jsonwebtoken) underneath.
#### jwtService.sign(payload: string | Object | Buffer, options?: JwtSignOptions): string
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`.
NOTE: Will throw an exception for asynchronous version of `secretOrKeyProvider`;
#### jwtService.signAsync(payload: string | Object | Buffer, options?: JwtSignOptions): Promise\
The asynchronous `.sign()` method.
#### jwtService.verify\(token: string, options?: JwtVerifyOptions): T
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`.
NOTE: Will throw an exception for asynchronous version of `secretOrKeyProvider`;
#### jwtService.verifyAsync\(token: string, options?: JwtVerifyOptions): Promise\
The asynchronous `.verify()` method.
#### jwtService.decode(token: string, options: DecodeOptions): object | string
The decode method is an implementation of jsonwebtoken `.decode()`.
The `JwtModule` takes an `options` object:
- `secret` is either a string, buffer, or object containing the secret for HMAC algorithms
- `secretOrKeyProvider` function with the following signature `(requestType, tokenOrPayload, options?) => jwt.Secret | Promise` (allows generating either secrets or keys dynamically)
- `signOptions` [read more](https://github.com/auth0/node-jsonwebtoken#jwtsignpayload-secretorprivatekey-options-callback)
- `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)
- `publicKey` PEM encoded public key for RSA and ECDSA
- `verifyOptions` [read more](https://github.com/auth0/node-jsonwebtoken#jwtverifytoken-secretorpublickey-options-callback)
- `secretOrPrivateKey` (DEPRECATED!) [read more](https://github.com/auth0/node-jsonwebtoken#jwtsignpayload-secretorprivatekey-options-callback)
## Support
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).
## Stay in touch
- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
- Website - [https://nestjs.com](https://nestjs.com/)
- Twitter - [@nestframework](https://twitter.com/nestframework)
## License
Nest is [MIT licensed](LICENSE).