@nestjs/jwt v10.2.0
Description
JWT utilities module for Nest based on the jsonwebtoken package.
Installation
$ npm i --save @nestjs/jwt
Usage
Import JwtModule
:
@Module({
imports: [JwtModule.register({ secret: 'hard!to-guess_secret' })],
providers: [...],
})
export class AuthModule {}
Inject JwtService
:
@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.
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
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
).
JwtModule.registerAsync({
imports: [ConfigModule],
useFactory: async (configService: ConfigService) => ({
secret: configService.get<string>('SECRET'),
}),
inject: [ConfigService],
}),
2. Use class
JwtModule.registerAsync({
useClass: JwtConfigService
});
Above construction will instantiate JwtConfigService
inside JwtModule
and will leverage it to create options object.
class JwtConfigService implements JwtOptionsFactory {
createJwtOptions(): JwtModuleOptions {
return {
secret: 'hard!to-guess_secret'
};
}
}
3. Use existing
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 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\<string>
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\<T>
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 algorithmssecretOrKeyProvider
function with the following signature(requestType, tokenOrPayload, options?) => jwt.Secret | Promise<jwt.Secret>
(allows generating either secrets or keys dynamically)signOptions
read moreprivateKey
PEM encoded private key for RSA and ECDSA with passphrase an object{ key, passphrase }
read morepublicKey
PEM encoded public key for RSA and ECDSAverifyOptions
read moresecretOrPrivateKey
(DEPRECATED!) read more
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.
Stay in touch
- Author - Kamil Myśliwiec
- Website - https://nestjs.com
- Twitter - @nestframework
License
Nest is MIT licensed.
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
4 years ago
4 years ago
5 years ago
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago