Authorization

Authentication verifies who the user is. Authorization determines what they can access.

Cognito stores users in groups. The @Authorization decorator checks if a user belongs to the right groups before allowing access to a route.

Note: @Authorization includes authentication, so you don't need both decorators.

Require specific groups

Only users in these groups can access the route:

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

@Controller('admin')
export class AdminController {
  @Authorization(['admin'])
  @Get('settings')
  manageSettings() {
    return 'Admin settings panel';
  }

  @Authorization(['editor', 'admin'])
  @Post('content')
  createContent() {
    return 'Create new content';
  }
}

Complex rules

You can combine multiple conditions:

@Controller('projects')
export class ProjectController {
  @Authorization({
    requiredGroups: ['project-member'],     // Must have this group
    allowedGroups: ['manager', 'lead'],     // AND one of these
    prohibitedGroups: ['suspended']         // AND none of these
  })
  @Put(':id')
  updateProject() {
    return 'Update project details';
  }
}

Using the guard directly

If you prefer guards over decorators:

import { AuthorizationGuard } from '@nestjs-cognito/auth';

@Controller('cats')
export class CatsController {
  @UseGuards(
    AuthorizationGuard({
      allowedGroups: ['user', 'admin'],
      requiredGroups: ['moderator'],
      prohibitedGroups: ['visitor'],
    })
  )
  @Get()
  findAll() {
    return 'This action requires specific permissions';
  }
}

How the rules work

requiredGroups: User must belong to ALL of these groups.

allowedGroups: User must belong to AT LEAST ONE of these groups.

prohibitedGroups: User must NOT belong to ANY of these groups.

When you combine them, all conditions must pass:

@Authorization({
  requiredGroups: ['authenticated'],      // Must be authenticated
  allowedGroups: ['premium', 'vip'],     // AND (premium OR vip)
  prohibitedGroups: ['banned']           // AND not banned
})

If you just pass an array, it behaves like allowedGroups:

@Authorization(['admin', 'moderator'])  // Admin OR moderator