A progressive Node.js framework for building efficient and scalable server-side applications.

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<T extends object = any>(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<T extends object = any>(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 algorithms
• secretOrKeyProvider function with the following signature (requestType, tokenOrPayload, options?) => jwt.Secret | Promise<jwt.Secret> (allows generating either secrets or keys dynamically)
• signOptions read more
• privateKey PEM encoded private key for RSA and ECDSA with passphrase an object { key, passphrase } read more
• publicKey PEM encoded public key for RSA and ECDSA
• verifyOptions read more
• secretOrPrivateKey (DEPRECATED!) read more

For performance purposes, it is advised to pass instances of KeyObject to secret, privateKey and publicKey properties of this options object. These KeyObject can be generated with createSecretKey(), createPrivateKey() and createPublicKey() from Node.js crypto module. For example:

import { createSecretKey } from 'crypto';

new JwtService({
  secret: createSecretKey(Buffer.from('the secret key'))
});

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.