@nestjs/jwt

What is @nestjs/jwt?

@nestjs/jwt is a module for NestJS that provides utilities for working with JSON Web Tokens (JWT). It allows you to easily generate, sign, and verify JWTs, which are commonly used for authentication and authorization in web applications.

What are @nestjs/jwt's main functionalities?

Generate JWT

This feature allows you to generate a JWT using a payload and a secret key. The `sign` method creates a token that can be used for authentication.

const jwt = require('@nestjs/jwt');
const jwtService = new jwt.JwtService({ secret: 'your-secret-key' });
const payload = { username: 'john_doe', sub: 1 };
const token = jwtService.sign(payload);
console.log(token);

Verify JWT

This feature allows you to verify a JWT using a secret key. The `verify` method decodes the token and checks its validity. If the token is invalid, an error is thrown.

const jwt = require('@nestjs/jwt');
const jwtService = new jwt.JwtService({ secret: 'your-secret-key' });
const token = 'your-jwt-token';
try {
  const decoded = jwtService.verify(token);
  console.log(decoded);
} catch (err) {
  console.error('Invalid token', err);
}

Decode JWT

This feature allows you to decode a JWT without verifying its signature. The `decode` method extracts the payload from the token.

const jwt = require('@nestjs/jwt');
const jwtService = new jwt.JwtService({ secret: 'your-secret-key' });
const token = 'your-jwt-token';
const decoded = jwtService.decode(token);
console.log(decoded);

Other packages similar to @nestjs/jwt

jsonwebtoken

jsonwebtoken is a popular library for working with JWTs in Node.js. It provides similar functionality to @nestjs/jwt, including methods for signing, verifying, and decoding tokens. However, it is not specifically designed for use with NestJS and lacks some of the integration features provided by @nestjs/jwt.

passport-jwt

passport-jwt is a Passport strategy for authenticating with JWTs. It is used in conjunction with the Passport authentication middleware for Node.js. While it provides robust JWT authentication capabilities, it requires additional setup and integration with Passport, unlike @nestjs/jwt which is designed to work seamlessly with NestJS.

express-jwt

express-jwt is a middleware for Express.js that validates JWTs and sets the `req.user` property. It is useful for protecting routes in an Express application. While it offers similar JWT validation capabilities, it is tailored for use with Express.js rather than NestJS.

README

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

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.