@nestjs-cognito/core

Changelog

• CognitoIdentityProviderClient has been removed from the @nestjs-cognito/core package.
• InjectCognitoIdentityProviderClient has been removed from the @nestjs-cognito/core package.
• JwtRsaVerifier support has been added to the @nestjs-cognito/core package.
• InjectCognitoJwtVerifier provides access to the JwtRsaVerifier and JwtVerifier instances from the adapter CognitoJwtVerifier.

Table of contents

• Description
• Installation
• Configuration
  • Options Parameters
  • JwtVerifier
  • JwtRsaVerifier
  • Synchronously
  • Asynchronously
• Usage
  • Cognito Identity Provider
  • AWS JWT Verify
    • CognitoJwtVerifier
      • Methods
      • Properties

Description

The @nestjs-cognito/core package simplifies integrating Amazon Cognito user pools into your NestJS applications. It provides a user-friendly interface for:

• Verifying JWT tokens issued by Amazon Cognito.
• (Optional) Interacting with the Amazon Cognito Identity Provider for actions like creating user pools or managing users.

This package leverages the @aws-sdk/client-cognito-identity-provider and aws-jwt-verify packages under the hood. It streamlines their usage within the NestJS framework.

Installation

To install the @nestjs-cognito/core module, run the following command:

npm install @nestjs-cognito/core

Note: In addition to @nestjs-cognito/core, you might need to install one or both of the following packages depending on your use case:

• @aws-sdk/client-cognito-identity-provider: Required if you intend to interact with the Cognito Identity Provider.
• aws-jwt-verify: Required for verifying JWT tokens if you're not using the @nestjs-cognito/auth module.

Important: If you choose to use the @nestjs-cognito/auth module for authentication and authorization functionalities, you won't need to install aws-jwt-verify separately. @nestjs-cognito/auth depends on @nestjs-cognito/core and includes aws-jwt-verify internally.

Configuration

Options Parameters

The CognitoModuleOptions interface defines the configuration options for the @nestjs-cognito/core module. It consists of three properties:

• identityProvider (Optional): Configuration object for the @aws-sdk/client-cognito-identity-provider package.
• jwtVerifier (Optional): Configuration object for the aws-jwt-verify package (supports single or multiple user pools).
• jwtRsaVerifier (Optional): Configuration object for the aws-jwt-verify package (supports single or multiple issuers).

You can use the CognitoModuleOptionsFactory interface to create the CognitoModuleOptions asynchronously using properties like imports, providers, exports, and name.

CognitoModuleAsyncOptions is another interface for asynchronous configuration. It includes properties like imports, inject, useFactory, and extraProviders.

JwtVerifier

JwtRsaVerifier

Note: The jwtVerifier and jwtRsaVerifier properties are mutually exclusive. You can use either one of them, but not both simultaneously.

Synchronously

The CognitoModule.register method takes an options object that implements the CognitoModuleOptions interface as a parameter. This options object can contain configurations for both the jwtVerifier and identityProvider.

Important:

• Use the identityProvider configuration if you plan to interact with the Cognito Identity Provider functions.
• Omit the identityProvider if you only need JWT verification functionality.

import { CognitoModule } from "@nestjs-cognito/core";
import { Module } from "@nestjs/common";

@Module({
  imports: [
    CognitoModule.register({
      // JWT verification for a single user pool
      jwtVerifier: {
        userPoolId: "your_user_pool_id",
        clientId: "your_client_id",
        tokenUse: "id",
      },
      // OR (Multiple user pools)
      /* jwtVerifier: [
        {
          userPoolId: "user_pool_id_1",
          clientId: "client_id_1",
          tokenUse: "id",
        },
        {
          userPoolId: "user_pool_id_2",
          clientId: "client_id_2",
          tokenUse: "id",
        },
      ], */
      // Identity Provider configuration (optional)
      identityProvider: {
        region: "us-east-1",
      },
    }),
  ],
})
export class AppModule {}

Asynchronously

For asynchronous configuration, use CognitoModule.registerAsync. This allows you to import your ConfigModule and inject ConfigService for utilizing environment variables:

import { CognitoModule } from "@nestjs-cognito/core";
import { Module } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";

@Module({
  imports: [
    CognitoModule.registerAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService) => ({
        jwtVerifier: {
          userPoolId: configService.get("COGNITO_USER_POOL_ID") as string,
          clientId: configService.get("COGNITO_CLIENT_ID"),
          tokenUse: "id",
        },
        // OR (Multiple user pools)
        /* jwtVerifier: [
          {
            userPoolId: configService.get("COGNITO_USER_POOL_ID_1") as string,
            clientId: configService.get("COGNITO_CLIENT_ID_1"),
            tokenUse: "id",
          },
          {
            userPoolId: configService.get("COGNITO_USER_POOL_ID_2") as string,
            clientId: configService.get("COGNITO_CLIENT_ID_2"),
            tokenUse: "id",
          },
        ], */
        // You can also use jwtRsaVerifier instead of jwtVerifier
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Usage

This module allows you to interact with Amazon Cognito for functionalities like:

• Verifying JWT tokens issued by your Cognito user pool.
• (Optional) Utilizing the Cognito Identity Provider for managing user pools or users (if configured).

Consider using the @nestjs-cognito/auth module for authentication and authorization functionalities. It builds upon @nestjs-cognito/core and includes JWT verification functionality, eliminating the need to install aws-jwt-verify separately.

Cognito Identity Provider

import { CognitoIdentityProvider } from "@aws-sdk/client-cognito-identity-provider";
import { InjectCognitoIdentityProvider } from "@nestjs-cognito/core";

export class MyService {
  constructor(
    @InjectCognitoIdentityProvider()
    private readonly client: CognitoIdentityProvider
  ) {}
}

AWS JWT Verify

import {
  CognitoJwtVerifier,
  InjectCognitoJwtVerifier
} from "@nestjs-cognito/core";

export class MyService {
  constructor(
    @InjectCognitoJwtVerifier()
    private readonly jwtVerifier CognitoJwtVerifier
  ) {}
}

CognitoJwtVerifier

It's a wrapper for the aws-jwt-verify package. It provides a simplified interface for verifying JWT tokens from Amazon Cognito.

Methods

• verify(token: string): Promise<CognitoJwtPayload> | Promise<JwtPayload> - Verifies the given token.

Properties

• jwtVerifier: JwtVerifier - The instance of the JwtVerifier class from the aws-jwt-verify package.

• jwtRsaVerifier: JwtRsaVerifier - The instance of the JwtRsaVerifier class from the aws-jwt-verify package.