nestjs-cognito

Protect routes:

import { Authentication, Authorization, CognitoUser } from '@nestjs-cognito/auth';

@Controller('admin')
@Authorization(['admin'])
export class AdminController {
  @Get('dashboard')
  getDashboard(@CognitoUser() user: CognitoJwtPayload) {
    return { message: `Welcome ${user['cognito:username']}` };
  }
}

Done.

Packages

Examples

Role-based authorization

@Controller('content')
export class ContentController {
  @Get()
  @Authorization({ allowedGroups: ['user', 'admin'] })
  list() {
    return { content: [] };  // Either user OR admin can access
  }

  @Post()
  @Authorization({ requiredGroups: ['moderator', 'admin'] })
  create() {
    return { created: true };  // Must be BOTH moderator AND admin
  }

  @Delete(':id')
  @Authorization({
    allowedGroups: ['admin'],
    prohibitedGroups: ['banned']  // Admins yes, banned users no
  })
  delete() {
    return { deleted: true };
  }
}

Public routes with optional auth

@Controller('products')
@Authentication()
export class ProductsController {
  @Get(':id')
  @PublicRoute()
  getProduct(@Param('id') id: string, @CognitoUser() user?: CognitoJwtPayload) {
    const product = this.findProduct(id);

    return {
      ...product,
      price: user ? this.getMemberPrice(product) : product.regularPrice,
      memberBenefits: user ? this.getBenefits(product) : null,
    };
  }
}

GraphQL

import { GqlAuthentication, GqlAuthorization, GqlCognitoUser } from '@nestjs-cognito/graphql';

@Resolver()
@GqlAuthentication()
export class UserResolver {
  @Query(() => User)
  me(@GqlCognitoUser() user: CognitoJwtPayload) {
    return {
      id: user.sub,
      username: user['cognito:username'],
      email: user.email,
    };
  }

  @Query(() => [User])
  @GqlAuthorization(['admin'])
  users() {
    return this.userService.findAll();
  }
}

Multiple user pools

CognitoAuthModule.register({
  jwtVerifier: [
    {
      userPoolId: 'us-east-1_customers',
      clientId: 'customer-app-client',
      tokenUse: 'access',
    },
    {
      userPoolId: 'us-east-1_employees',
      clientId: 'admin-app-client',
      tokenUse: 'id',
    },
  ],
})

Cookie authentication

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

CognitoAuthModule.register({
  jwtExtractor: new CookieJwtExtractor('access_token'),
  jwtVerifier: {
    userPoolId: 'us-east-1_xxxxx',
    clientId: 'your-client-id',
    tokenUse: 'id',
  },
})

Testing

import { CognitoTestingModule } from '@nestjs-cognito/testing';

const module = await Test.createTestingModule({
  imports: [
    CognitoTestingModule.register({}, {
      enabled: true,
      user: {
        username: 'test-user',
        email: 'test@example.com',
        groups: ['users'],
      },
    }),
    AppModule,
  ],
})
  .overrideProvider(COGNITO_JWT_VERIFIER_INSTANCE_TOKEN)
  .useFactory({ factory: CognitoTestingModule.createJwtVerifierFactory })
  .compile();

Contributing

Found a bug? Have an idea? Pull requests are welcome.

1. Fork the repo
2. Create your feature branch
3. Commit your changes
4. Push and open a PR

See CONTRIBUTING.md for details.

Documentation

Full documentation →

Package READMEs:

• Core
• Auth
• GraphQL
• Testing
• Examples

License

MIT

Made by @Lokicoule