As web developers, we understand the significance of having a secure and dependable authentication system for our applications. In today's world, where security threats are on the rise, it is imperative to ensure that our users' data is protected. But building an authentication system from scratch can be a challenging and time-consuming task, especially when we want to make it scalable and maintainable.
This is where NestJS and AWS Cognito come in. NestJS, the powerful Node.js framework developed by Kamil Myśliwiec, and AWS Cognito, the managed authentication service from AWS, can be integrated to create a robust authentication system with ease.
To make this integration simpler, we have the @nestjs-cognito package collection. It includes @nestjs-cognito/core, @nestjs-cognito/auth, @nestjs-cognito/graphql, and @nestjs-cognito/testing.
If you're looking for a secure, dependable, and scalable solution for authentication and authorization in your NestJS application, then @nestjs-cognito is the right choice for you. Start using @nestjs-cognito today and simplify your development process. And don't forget to give it a star on GitHub to support the project and show your appreciation!
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.
To install the @nestjs-cognito/core module, run the following command:
npm install @nestjs-cognito/coreIn 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-verifyThe 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-providerpackage. - jwtVerifier is an optional configuration object for the
aws-jwt-verifypackage.
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;
}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 {}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 {}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.
import {
CognitoIdentityProvider,
CognitoIdentityProviderClient,
} from "@aws-sdk/client-cognito-identity-provider";
import {
InjectCognitoIdentityProvider,
InjectCognitoIdentityProviderClient,
} from "@nestjs-cognito/core";
export class MyService {
constructor(
@InjectCognitoIdentityProvider()
private readonly client: CognitoIdentityProvider,
@InjectCognitoIdentityProviderClient()
private readonly cognitoIdentityProviderClient: CognitoIdentityProviderClient
) {}
}import {
CognitoJwtVerifier,
InjectCognitoJwtVerifier,
} from "@nestjs-cognito/core";
export class MyService {
constructor(
@InjectCognitoJwtVerifier()
private readonly jwtVerifier: CognitoJwtVerifier
) {}
}@nestjs-cognito/core is MIT licensed.
@nestjs-cognito/auth is a library for NestJS that provides authentication and authorization decorators and guards for applications using AWS Cognito. This library is built on top of @nestjs-cognito/core and aws-jwt-verify.
To install the library, use npm:
npm install @nestjs-cognito/authThe @nestjs-cognito/auth library offers both synchronous and asynchronous configuration options. To use the library, a few configuration parameters are required, including the AWS Cognito user pool ID and client ID. Detailed information about the available options can be found in the @nestjs-cognito/core documentation.
The @nestjs-cognito/auth library can be easily integrated into your NestJS application by importing the CognitoAuthModule from the @nestjs-cognito/auth package.
Use the CognitoAuthModule.register method with options from the CognitoModuleOptions interface
Here's an example of how you can import the CognitoAuthModule into your NestJS application:
import { CognitoAuthModule } from "@nestjs-cognito/auth";
import { Module } from "@nestjs/common";
@Module({
imports: [
CognitoAuthModule.register({
jwtVerifier: {
userPoolId: "user_pool_id",
clientId: "client_id",
tokenUse: "id",
},
}),
],
})
export class AppModule {}In this example, the CognitoAuthModule is imported and registered with the following configuration options:
jwtVerifier:userPoolId: The ID of your AWS Cognito user pool.clientId: The client ID of your AWS Cognito user pool.tokenUse: The type of token to be used. It is recommended to use "id" instead of "access" token.
Note: You can also define an identity provider without importing the CognitoModule module by using the CognitoAuthModule.
With CognitoModule.registerAsync you can import a ConfigModule and inject ConfigService to use it in useFactory method.
Alternatively, you can use useExisting or useClass.
You can find more information about asynchronous configuration in the NestJS documentation.
import { CognitoAuthModule } from "@nestjs-cognito/auth";
import { Module } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";
@Module({
imports: [
CognitoAuthModule.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",
},
}),
inject: [ConfigService],
}),
],
})
export class AppModule {}Once the @nestjs-cognito/auth module is installed and configured, you can use the following decorators and guards to protect your controllers and routes.
- Use the
@Authenticationdecorator or the@UseGuards(AuthenticationGuard)syntax to apply theAuthenticationGuardto a controller and ensure that the user is authenticated. - Use the
@Authorizationdecorator or the@UseGuards(AuthorizationGuard)syntax to apply theAuthorizationGuardto a controller and ensure that the user is authorized. - Decorate method arguments with the
@CognitoUserdecorator to retrieve the payload information extracted from the JWT.
Note: During the authorization process, the authentication of the user is already checked, so there's no need to use the authentication guard or decorator.
In addition, you can find more details about @UseGuards decorator from the official NestJS documentation.
To configure the authentication, you'll need to use the @Authentication decorator. You can add the @Authentication decorator to controllers or routes:
import { Authentication } from "@nestjs-cognito/auth";
import { Controller } from "@nestjs/common";
@Controller("dogs")
@Authentication()
export class DogsController {
// Your routes here
}You can also use the AuthenticationGuard to secure individual routes or endpoint.
To use the AuthenticationGuard, you'll need to use the @UseGuards decorator:
import { Authentication } from "@nestjs-cognito/auth";
import { UseGuards } from "@nestjs/common";
@Controller("dogs")
@UseGuards(AuthenticationGuard)
export class DogsController {
// Your routes here
}Examples of using authentication:
import {
Authentication,
AuthenticationGuard,
CognitoUser,
} from "@nestjs-cognito/auth";
import { Controller, Get, UseGuards } from "@nestjs/common";
import { CognitoJwtPayload } from "aws-jwt-verify/jwt-model";
@Controller("dogs")
@Authentication()
export class DogsController {
@Get()
findAll(@CognitoUser("email") email: string): string {
return "This action returns all my dogs";
}
}
@Controller("cats")
@UseGuards(AuthenticationGuard)
export class CatsController {
@Get()
findAll(@CognitoUser(["groups", "email", "username"]) me): string {
return "This action returns all my cats";
}
}
@Controller("dogs")
export class DogsController {
@Get()
@Authentication()
findAll(@CognitoUser() CognitoJwtPayload): string {
return "This action returns all my dogs";
}
}
@Controller("cats")
export class CatsController {
@Get()
@UseGuards(AuthenticationGuard)
findAll(@CognitoUser(["groups", "email", "username"]) me): string {
return "This action returns all my cats";
}
}The @Authorization decorator can be used to secure an entire controller. You can specify the allowedGroups, requiredGroups, and/or prohibitedGroups for a given controller.
For example:
@Controller("dogs")
@Authorization({
allowedGroups: ["user", "admin"],
requiredGroups: ["moderator"],
prohibitedGroups: ["visitor"],
})
export class DogsController {
@Get()
findAll(@CognitoUser() CognitoJwtPayload): string {
return "This action returns all my dogs";
}
}You can also specify the allowedGroups as an array of strings:
@Controller("cats")
@Authorization(["user"]) // allowedGroups by default
export class CatsController {
@Get()
findAll(@CognitoUser("username") username: string): string {
return "This action returns all my cats";
}
}The AuthorizationGuard can be used to secure a single route, allowing you to specify the allowedGroups, requiredGroups, and/or prohibitedGroups for a given endpoint.
For example:
@Controller("cats")
@UseGuards(
AuthorizationGuard({
allowedGroups: ["user", "admin"],
requiredGroups: ["moderator"],
prohibitedGroups: ["visitor"],
})
)
export class CatsController {
@Get()
findAll(@CognitoUser("email") email: string): string {
return "This action returns all my cats";
}
}You can also use the AuthorizationGuard directly on a route:
@Controller("cats")
export class CatsController {
@Get()
@UseGuards(AuthorizationGuard(["user", "admin"]))
findAll(@CognitoUser() me: CognitoJwtPayload): string {
return "This action returns all my cats";
}
}Examples of using authorization:
import {
Authorization,
AuthorizationGuard,
CognitoUser,
} from "@nestjs-cognito/auth";
import { Controller, Get, UseGuards } from "@nestjs/common";
import { CognitoJwtPayload } from "aws-jwt-verify/jwt-model";
@Controller("dogs")
@Authorization({
allowedGroups: ["user", "admin"],
requiredGroups: ["moderator"],
prohibitedGroups: ["visitor"],
})
export class DogsController {
@Get()
findAll(@CognitoUser() CognitoJwtPayload): string {
return "This action returns all my dogs";
}
}
@Controller("cats")
@Authorization(["user"]) // allowedGroups by default
export class CatsController {
@Get()
findAll(@CognitoUser("username") username: string): string {
return "This action returns all my cats";
}
}
@Controller("cats")
@UseGuards(
AuthorizationGuard({
allowedGroups: ["user", "admin"],
requiredGroups: ["moderator"],
prohibitedGroups: ["visitor"],
})
)
export class CatsController {
@Get()
findAll(@CognitoUser("email") email: string): string {
return "This action returns all my cats";
}
}
@Controller("cats")
export class CatsController {
@Get()
@UseGuards(AuthorizationGuard(["user", "admin"]))
findAll(@CognitoUser() me: CognitoJwtPayload): string {
return "This action returns all my cats";
}
}To retrieve the cognito user from an incoming request, you'll need to use the @CognitoUser decorator. You can use the decorator to inject the entire CognitoJwtPayload object or specific properties from the payload, such as the username or email. Note that the cognito: namespace is automatically managed, so you don't need to include it when accessing properties such as cognito:username or cognito:groups.
It's important to note that this decorator must be used in conjunction with an authentication guard, such as Authentication or Authorization.
For example:
@Controller()
@Authentication()
export class YourController {
@Get()
findAll(@CognitoUser() cognitoJwtPayload: CognitoJwtPayload): string {
return "This action returns all the data";
}
}You can specify the name of the property to inject the user into by passing a string as an argument.
import { Authentication, CognitoUser } from "@nestjs-cognito/auth";
@Controller()
@Authentication()
export class YourController {
@Get()
getData(@CognitoUser("email") email: string): any {
// Use the `email` string
}
}You can extract multiple properties from the cognito user by passing an array of strings.
import { Authentication, CognitoUser } from "@nestjs-cognito/auth";
@Controller()
@Authentication()
export class YourController {
@Get()
getData(
@CognitoUser(["groups", "email", "username"])
{
groups,
email,
username,
}: {
groups: string[];
email: string;
username: string;
}
): any {
// Use the `groups` and/or `username` and `email` strings
}
}@nestjs-cognito/auth is MIT licensed.
This package is a complement to @nestjs-cognito/auth and adds GraphQL support for Amazon Cognito authentication and authorization. It does not expose a CognitoGraphqlModule.
This package includes a GraphQL middleware that provides the authenticated user information in the GraphQL context. The middleware checks the presence of an Authorization header in the request and verifies the token with aws-jwt-verify. If the token is valid, the middleware adds the user information to the context.
In addition to the middleware, this package also includes guards (AuthenticationGuard and AuthorizationGuard) and decorators (GqlCognitoUser, GqlAuthentication and GqlAuthorization) that can be used to restrict access to certain resolvers based on the user's authentication status or role.
It's recommended to use the decorators instead of guards coupled with UseGuards NestJS decorator.
To install the library, use npm:
npm install @nestjs-cognito/graphql
To use this package, you need to configure the @nestjs-cognito/auth module. Once the authentication module is configured, you can use the following exports from this package to handle Cognito authentication and authorization in your GraphQL resolvers.
This is a GraphQL middleware that provides the authenticated user information in the GraphQL context. The middleware checks the presence of a Authorization header in the request and verifies the token with Amazon Cognito. If the token is valid, the middleware adds the user information to the context.
import { GqlAuthentication } from "@nestjs-cognito/graphql";
@Resolver()
@GqlAuthentication()
export class MyResolver {
@Query()
public async myQuery() {
// Only authenticated user can access this resolver
}
}Examples of using authentication:
import { UseGuards } from "@nestjs/common";
import { Args, Query, Resolver } from "@nestjs/graphql";
import {
GqlAuthentication,
AuthenticationGuard,
GqlCognitoUser,
} from "@nestjs-cognito/graphql";
import { CognitoJwtPayload } from "aws-jwt-verify/jwt-model";
@Resolver("dogs")
@GqlAuthentication()
export class DogsResolver {
@Query(() => String)
findAll(@GqlCognitoUser() me: CognitoJwtPayload): string {
return "This action returns all my dogs";
}
}
@Resolver("cats")
@UseGuards(AuthenticationGuard)
export class CatsResolver {
@Query(() => String)
findAll(@GqlCognitoUser() me: CognitoJwtPayload): string {
return "This action returns all my cats";
}
}
@Resolver("dogs")
export class DogsResolver {
@Query(() => String)
@UseGuards(AuthenticationGuard)
findAll(@GqlCognitoUser() me: CognitoJwtPayload): string {
return "This action returns all my dogs";
}
}This is a decorator that can be used to enforce authorization rules in your GraphQL resolvers. The decorator takes a list of authorized groups and checks if the authenticated user is a member of any of the groups. If the user is not a member of any of the groups, an error is thrown.
import { GqlAuthorization } from "@nestjs-cognito/graphql";
@Resolver()
export class MyResolver {
@Query()
@GqlAuthorization(["group1", "group2"])
public async myQuery() {
// only users in group1 or group2 can access this resolver
}
}Examples of using authorization:
import { UseGuards } from "@nestjs/common";
import { Args, Query, Resolver } from "@nestjs/graphql";
import {
GqlAuthorization,
AuthorizationGuard,
GqlCognitoUser,
} from "@nestjs-cognito/graphql";
import { CognitoJwtPayload } from "aws-jwt-verify/jwt-model";
@Resolver("dogs")
@GqlAuthorization({
allowedGroups: ["user", "admin"],
requiredGroups: ["moderator"],
prohibitedGroups: ["visitor"],
})
export class DogsResolver {
@Query(() => String)
findAll(@GqlCognitoUser() me: CognitoJwtPayload): string {
return "This action returns all my dogs";
}
}
@Resolver("cats")
@GqlAuthorization(["user"]) // allowedGroups by default
export class CatsResolver {
@Query(() => String)
findAll(@GqlCognitoUser() me: CognitoJwtPayload): string {
return "This action returns all my cats";
}
}
@Resolver("cats")
@UseGuards(
AuthorizationGuard({
allowedGroups: ["user", "admin"],
requiredGroups: ["moderator"],
prohibitedGroups: ["visitor"],
})
)
export class CatsResolver {
@Query(() => String)
findAll(@GqlCognitoUser() me: CognitoJwtPayload): string {
return "This action returns all my cats";
}
}
@Resolver("cats")
export class CatsResolver {
@Query(() => String)
@UseGuards(AuthorizationGuard(["user", "admin"]))
findAll(@GqlCognitoUser() me: CognitoJwtPayload): string {
return "This action returns all my cats";
}
}This is a decorator that can be used in your GraphQL resolvers to access the authenticated user information from the context.
import { GqlCognitoUser } from "@nestjs-cognito/graphql";
import { CognitoJwtPayload } from "aws-jwt-verify/jwt-model";
@Resolver()
export class MyResolver {
@Query()
public async myQuery(@GqlCognitoUser() user: CognitoJwtPayload) {
// user information from Cognito
}
}For a complete example of how to use these guards and decorators, you can check out the @nestjs-cognito/auth package.
@nestjs-cognito/graphql is MIT licensed.
This module is a solution for NestJS which facilitates the integration with Amazon Cognito for end-to-end and integration testing purposes. It includes a module, a controller, and a service that simplify testing your authentication and authorization code based on Amazon Cognito.
npm install @nestjs-cognito/testingTo use the CognitoTestingModule, you will need to import it and use either the register or registerAsync method to set up its dependencies:
@Module({
imports: [
CognitoTestingModule.register({
identityProvider: {
region: "eu-west-1",
},
}),
],
})
export class AppModule {}The CognitoTestingController is a simple controller that accepts a username and password and returns an access token. The code is shown below:
Controller Source Code
import { Body, Controller, Post } from "@nestjs/common";
import { CognitoTestingService } from "@nestjs-cognito/testing";
@Controller()
export class CognitoTestingController {
constructor(private readonly authService: CognitoTestingService) {}
@Post("cognito-testing-login")
login(@Body() body: Record<string, string>) {
return this.authService.getAccessToken(
{
username: body.username,
password: body.password,
},
body.clientId
);
}
}The CognitoTestingService is a service that uses the CognitoIdentityProvider client to get an access token. To call the method cognito-testing-login, you need to pass the following information in the request body:
username: The username of the test userpassword: The password of the test userclientId: Required for using the initiateAuth method provided by@aws-sdk/client-cognito-identity-provider.
import { CognitoTestingModule } from "@nestjs-cognito/testing";
import { INestApplication } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";
import { Test } from "@nestjs/testing";
import { request, spec } from "pactum";
describe("Cognito Module : Testing", () => {
let app: INestApplication;
let config: ConfigService;
beforeAll(async () => {
const moduleFixture = await Test.createTestingModule({
imports: [
ConfigModule.forRoot(),
CognitoTestingModule.register({
region: "eu-west-1",
}),
],
}).compile();
app = moduleFixture.createNestApplication();
config = moduleFixture.get<ConfigService>(ConfigService);
await app.listen(0);
const url = (await app.getUrl()).replace("[::1]", "localhost");
request.setBaseUrl(url);
});
afterAll(async () => {
await app.close();
});
describe("authentication", () => {
it("should be able to access the private route", async () => {
await spec()
.post("/cognito-testing-login")
.withBody({
username: config.get("COGNITO_USER_EMAIL"),
password: config.get("COGNITO_USER_PASSWORD"),
clientId: config.get("COGNITO_CLIENT_ID"),
})
.expectStatus(201)
.expectBodyContains("AccessToken").
.stores('token', 'AccessToken');
await spec()
.get('/private')
.withHeaders('Authorization', 'Bearer $S{token}')
.expectStatus(200);
});
});
});@nestjs-cognito/testing is MIT licensed.
@nestjs-cognito is MIT licensed.