Module Configuration

The @nestjs-cognito/core module provides flexible configuration options for AWS Cognito integration and JWT verification. For detailed configuration options and examples, see the Core Package Documentation.

Async Configuration

For dynamic configuration using environment variables or other async providers:

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

@Module({
  imports: [
    CognitoModule.registerAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        identityProvider: {
          region: configService.get('AWS_REGION'),
        },
        jwtVerifier: {
          userPoolId: configService.get('COGNITO_USER_POOL_ID'),
          clientId: configService.get('COGNITO_CLIENT_ID'),
          tokenUse: 'id',
        },
      }),
      inject: [ConfigService],
    })
  ]
})
export class AppModule {}

Module Options

CognitoModuleOptions

Core configuration interface:

interface CognitoModuleOptions {
  identityProvider?: CognitoIdentityProviderClientConfig;
  jwtVerifier?: CognitoJwtVerifierProperties | CognitoJwtVerifierMultiProperties[];
  jwtRsaVerifier?: JwtRsaVerifierProperties | JwtRsaVerifierMultiProperties[];
}

Async Configuration Options

interface CognitoModuleAsyncOptions {
  imports?: Array<Type<any>>;
  useFactory?: (...args: any[]) => Promise<CognitoModuleOptions> | CognitoModuleOptions;
  inject?: any[];
  useClass?: Type<CognitoModuleOptionsFactory>;
  useExisting?: Type<CognitoModuleOptionsFactory>;
  extraProviders?: Provider[];
}

Basic Configuration

To use the Cognito module, you need to configure it in your application's root module:

import { CognitoModule } from '@nestjs-cognito/core';

@Module({
  imports: [
    CognitoModule.register({
      identityProvider: {
        region: 'us-east-1',
        credentials: {
          accessKeyId: 'xxxxx',
          secretAccessKey: 'xxxxx',
        },
      },
      // JWT verification configuration...
    }),
  ],
})
export class AppModule {}

Identity Provider Configuration

The identityProvider configuration sets up the AWS Cognito Identity Provider client:

identityProvider: {
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'xxxxx',
    secretAccessKey: 'xxxxx',
  },
}

JWT Verification Configuration

You can configure either Cognito JWT verification or RSA JWT verification, but not both simultaneously.

Cognito JWT Verification

Single User Pool

jwtVerifier: {
  userPoolId: 'us-east-1_xxxxx',
  clientId: 'xxxxx',
  tokenUse: 'access', // 'access', 'id', or null
  additionalProperties: {
    jwksCache: {
      expiryTimeInHours: 24
    }
  }
}

Multiple User Pools

jwtVerifier: [
  {
    userPoolId: 'us-east-1_pool1',
    clientId: 'client1',
    tokenUse: 'access'
  },
  {
    userPoolId: 'us-east-1_pool2',
    clientId: 'client2',
    tokenUse: 'id',
    additionalProperties: {
      jwksCache: {
        expiryTimeInHours: 24
      }
    }
  }
]

RSA JWT Verification

Single Issuer

jwtRsaVerifier: {
  issuer: 'https://your-issuer.com',
  jwksUri: 'https://your-jwks-uri.com/.well-known/jwks.json',
  additionalProperties: {
    jwksCache: {
      expiryTimeInHours: 24
    }
  }
}

Multiple Issuers

jwtRsaVerifier: [
  {
    issuer: 'https://issuer1.com',
    jwksUri: 'https://issuer1.com/.well-known/jwks.json'
  },
  {
    issuer: 'https://issuer2.com',
    jwksUri: 'https://issuer2.com/.well-known/jwks.json',
    additionalProperties: {
      jwksCache: {
        expiryTimeInHours: 24
      }
    }
  }
]

JWK Cache Configuration

Both verification methods support JWK caching through the additionalProperties.jwksCache configuration:

additionalProperties: {
  jwksCache: {
    expiryTimeInHours: 24 // Cache duration in hours
  }
}

This helps optimize performance by reducing the number of JWKS endpoint calls.

Important Notes

Choose either jwtVerifier or jwtRsaVerifier based on your needs
JWK cache configuration is optional but recommended for production
When using multiple pools/issuers, each can have its own cache configuration