@nestjs-cognito/core
v1.2.3
Published
Cognito Provider for NestJS
Downloads
13,739
Readme
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.
/**
* @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.