@nestjs/jwt Documentation

Install the @nestjs/jwt package to use JWT utilities in your NestJS application.

$ npm i --save @nestjs/jwt

To use JWT utilities, first import JwtModule into your module using .register() with a secret. Then, inject JwtService into your providers to sign or verify tokens.

@Module({
  imports: [JwtModule.register({ secret: 'hard!to-guess_secret' })],
  providers: [...],
})
export class AuthModule {}

@Injectable()
export class AuthService {
  constructor(private readonly jwtService: JwtService) {}
}

When using JwtModule.register(), you provide a JwtModuleOptions object. This object allows you to define the global scope of the module and specify keys for signing and verifying tokens.

Key configuration properties:

• global: If true, the JwtModule is registered globally.
• secret: The secret used for signing or verifying.
• publicKey / privateKey: Used for asymmetric (RSA/ECDSA) algorithms.
• signOptions: Options passed to the underlying jsonwebtoken signing process.
• verifyOptions: Options passed to the underlying jsonwebtoken verification process.
• secretOrKeyProvider: A function to dynamically retrieve the secret based on the JwtSecretRequestType (SIGN or VERIFY).

const moduleOptions: JwtModuleOptions = {
  global: true,
  secret: 'my-secret',
  signOptions: { expiresIn: '1h' },
  verifyOptions: { algorithms: ['HS256'] },
};

To configure JwtModule using asynchronous providers (e.g., fetching secrets from a database or environment variables), use JwtModuleAsyncOptions. This is typically used with JwtModule.registerAsync().

Supported patterns:

• useFactory: A function that returns JwtModuleOptions or a Promise<JwtModuleOptions>. You can use inject to provide dependencies to this factory.
• useClass: A class that implements the JwtOptionsFactory interface.
• useExisting: A reference to an existing provider that implements JwtOptionsFactory.

Note: JwtModuleAsyncOptions also supports extraProviders to add additional providers to the module context.

// Example using useFactory
JwtModule.registerAsync({
  global: true,
  useFactory: async (configService: ConfigService) => ({
    secret: configService.get('JWT_SECRET'),
  }),
  inject: [ConfigService],
});

The WrongSecretProviderError is thrown by the @nestjs/jwt module when a secret provider (used for retrieving signing keys or secrets) fails to provide a valid secret or returns an unexpected value. You can catch this error to handle cases where your secret management logic (e.g., fetching from a vault or environment variable) is misconfigured.

try {
  // code that triggers JWT signing or verification using a custom secret provider
} catch (error) {
  if (error instanceof WrongSecretProviderError) {
    // Handle the case where the secret provider returned an invalid secret
  }
}

If you encounter a WrongSecretProviderError, it means you are attempting to use an asynchronous secret provider (a function that returns a Promise) with a synchronous method (sign() or verify()).

Solution:

• If using sign(), switch to signAsync().
• If using verify(), switch to verifyAsync().

Use sign() to synchronously create a JSON Web Token from a payload. The payload can be a string, Buffer, or object.

Important Constraints:

• If the payload is a string, you are not allowed to provide secret or privateKey within the options object; these must be handled via the service configuration or other mechanisms. Providing them when the payload is a string will result in an error.
• If you are using an asynchronous secret provider (a function that returns a Promise), you must use signAsync() instead of sign() to avoid a WrongSecretProviderError.

// Signing an object payload
const token = jwtService.sign({ userId: 123 });

// Signing with options
const tokenWithExp = jwtService.sign({ userId: 123 }, { expiresIn: '1h' });

Use verifyAsync() to validate a token when using an asynchronous secret provider. This method returns a Promise<T> containing the decoded payload.

try {
  const payload = await jwtService.verifyAsync<any>(token);
  console.log(payload.userId);
} catch (error) {
  // Handle invalid token
}