@nestjs-cognito/core

Description

A wrapper package for the @aws-sdk/client-cognito-identity-provider and aws-jwt-verify packages for use with NestJS applications.

This package provides a simplified and NestJS-friendly interface for integrating Amazon Cognito into your application. With this package, you can easily make API requests to Amazon Cognito and verify JWT tokens from Amazon Cognito.

Installation

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

npm install @nestjs-cognito/core

In addition to the @nestjs-cognito/core package, you will also need to install the @aws-sdk/client-cognito-identity-provider and/or aws-jwt-verify.

It's important to note that if you use the @nestjs-cognito/auth module, you won't need to install aws-jwt-verify manually. The choice of which package to use depends on your specific needs.

npm install @aws-sdk/client-cognito-identity-provider aws-jwt-verify

Configuration

Options params

The CognitoModuleOptions interface is the configuration options for the @nestjs-cognito/core module. It contains two properties: identityProvider and jwtVerifier.

• identityProvider is an optional configuration object for the @aws-sdk/client-cognito-identity-provider package.
• jwtVerifier is an optional configuration object for the aws-jwt-verify package.

You can use the CognitoModuleOptionsFactory interface for creating the CognitoModuleOptions in an asynchronous way, using imports, providers, exports, and name properties.

CognitoModuleAsyncOptions is another interface for creating the CognitoModuleOptions asynchronously. It contains properties such as imports, inject, useFactory, and extraProviders.

Definition

/**
 * @type CognitoJwtVerifier - The CognitoJwtVerifier instance
 * @property {CognitoJwtVerifierSingleUserPool<CognitoJwtVerifierProperties>} - The CognitoJwtVerifierSingleUserPool instance
 */
export type CognitoJwtVerifier =
  CognitoJwtVerifierSingleUserPool<CognitoJwtVerifierProperties>;

/**
 * @type CognitoModuleOptions - Options for the CognitoModule
 * @property {CognitoIdentityProviderClientConfig} region - The region to use
 * @property {CognitoJwtVerifierProperties} userPoolId - The user pool id to use
 * @property {CognitoJwtVerifierProperties} clientId - The client id to use
 * @property {CognitoJwtVerifierProperties} tokenUse - The token use to use
 * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityServiceProvider.html#constructor-property
 * @see https://github.com/awslabs/aws-jwt-verify#readme
 */
export type CognitoModuleOptions = {
  identityProvider?: CognitoIdentityProviderClientConfig;
  jwtVerifier?: CognitoJwtVerifierProperties;
};

/**
 * @interface CognitoModuleOptionsFactory - Metadata for the CognitoModule
 * @property {() => Promise<CognitoModuleOptions>} createCognitoModuleOptions - A factory function to create the CognitoModuleOptions
 * @property {Type<any>[]} imports - The imports to be used by the module
 * @property {Provider[]} providers - The providers to be used by the module
 * @property {(string | Provider)[]} exports - The exports to be used by the module
 * @property {string} name - The name of the module
 */
export interface CognitoModuleOptionsFactory {
  createCognitoModuleOptions():
    | Promise<CognitoModuleOptions>
    | CognitoModuleOptions;
}

/**
 * @interface CognitoModuleAsyncOptions - Options for the CognitoModule
 * @property {Function} imports - Imports the module asyncronously
 * @property {Function} inject - Injects the module asyncronously
 * @property {CognitoModuleOptions} useFactory - The factory function to create the CognitoModuleOptions
 * @property {CognitoModuleOptions} useClass - The class to create the CognitoModuleOptions
 * @property {CognitoModuleOptions} useExisting - The existing instance of the CognitoModuleOptions
 */
export interface CognitoModuleAsyncOptions
  extends Pick<ModuleMetadata, "imports"> {
  extraProviders?: Provider[];
  inject?: any[];
  useClass?: Type<CognitoModuleOptionsFactory>;
  useExisting?: Type<CognitoModuleOptionsFactory>;
  useFactory?: (
    ...args: any[]
  ) => Promise<CognitoModuleOptions> | CognitoModuleOptions;
}

Synchronously

Use CognitoModule.register method with options of CognitoModuleOptions interface The 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.

It's important to note that the identityProvider is used in the case where you want to use the Cognito identity provider. If you don't want to use the identity provider, you can omit this configuration from the options object and only specify the jwtVerifier configuration and vice-versa.

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

@Module({
  imports: [
    CognitoModule.register({
      jwtVerifier: {
        userPoolId: "user_pool_id",
        clientId: "client_id",
        tokenUse: "id",
      },
      identityProvider: {
        region: "us-east-1",
      },
    }),
  ],
})
export class AppModule {}

Asynchronously

With CognitoModule.registerAsync you can import your ConfigModule and inject ConfigService to use it in useFactory method. It's also possible to use useExisting or useClass. You can find more details here.

Here's an example:

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",
        },
        identityProvider: {
          region: configService.get("COGNITO_REGION"),
        },
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Usage

You can use this module to interact with Amazon Cognito and make use of its functionality. In case you need to handle authentication and authorization, you may consider using the @nestjs-cognito/auth module, which is built on top of @nestjs-cognito/core. In this case, you won't need to install aws-jwt-verify manually, as it is already included in the @nestjs-cognito/auth module.

Cognito Identity Provider

import {
  CognitoIdentityProvider,
  CognitoIdentityProviderClient,
} from "@aws-sdk/client-cognito-identity-provider";
import {
  InjectCognitoIdentityProvider,
  InjectMutableCognitoIdentityProviderAdapter,
  InjectCognitoIdentityProviderClient,
  InjectMutableCognitoIdentityProviderClientAdapter,
  CognitoIdentityProviderAdapter,
  CognitoIdentityProviderClientAdapter,
} from "@nestjs-cognito/core";

export class MyService {
  constructor(
    @InjectCognitoIdentityProvider()
    private readonly client: CognitoIdentityProvider,
    @InjectCognitoIdentityProviderClient()
    private readonly cognitoIdentityProviderClient: CognitoIdentityProviderClient,
    @InjectMutableCognitoIdentityProviderAdapter()
    private readonly clientMutable: CognitoIdentityProviderAdapter,
    @InjectCognitoIdentityProviderClient()
    private readonly cognitoIdentityProviderClientMutable: CognitoIdentityProviderClientAdapter
  ) {}
}

AWS JWT Verify

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

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

License

@nestjs-cognito/core is MIT licensed.