A comprehensive educational project demonstrating authentication, authorization, and security guards in NestJS. This project showcases best practices for implementing various security patterns using JWT tokens, role-based access control (RBAC), and API key authentication.

This project serves as a complete reference for implementing security in NestJS applications, featuring:

• JWT Authentication with login/logout functionality
• Role-based Authorization (RBAC) with multiple user roles
• API Key Authentication for service-to-service communication
• Custom Security Guards with detailed implementations
• Parameter Decorators for clean, reusable code
• Comprehensive Swagger Documentation for all endpoints
• Educational Comments explaining every security concept

• ✅ JWT-based authentication with secure token handling
• ✅ Role-based access control (User, Admin, Moderator)
• ✅ API key authentication for external services
• ✅ Public endpoint exemptions with @Public() decorator
• ✅ Custom parameter decorators (@CurrentUser(), @Roles())

• ✅ JwtAuthGuard - JWT token validation
• ✅ RolesGuard - Role-based authorization
• ✅ ApiKeyGuard - API key validation

• ✅ Complete Swagger/OpenAPI documentation
• ✅ Interactive API testing interface
• ✅ Detailed code comments and examples
• ✅ TypeScript type safety throughout
• ✅ Educational README with examples

src/
├── auth/                              # Authentication module
│   ├── decorators/                    # Custom decorators
│   │   ├── current-user.decorator.ts  # Extract current user from JWT
│   │   ├── public.decorator.ts        # Mark endpoints as public
│   │   └── roles.decorator.ts         # Define required roles
│   ├── guards/                        # Security guards
│   │   ├── jwt-auth.guard.ts          # JWT authentication
│   │   ├── roles.guard.ts             # Role-based authorization
│   │   └── api-key.guard.ts           # API key validation
│   ├── dto/                           # Data transfer objects
│   │   └── auth.dto.ts                # Login, response DTOs
│   ├── interfaces/                    # TypeScript interfaces
│   │   └── auth.interface.ts          # JWT payload, user types
│   ├── auth.controller.ts             # Authentication endpoints
│   ├── auth.service.ts                # Authentication logic
│   ├── auth.module.ts                 # Auth module configuration
│   └── constants.ts                   # Role definitions, secrets
├── users/                             # User management module
│   ├── interfaces/                    # User-related interfaces
│   ├── users.controller.ts            # User endpoints
│   ├── users.service.ts               # User business logic
│   └── users.module.ts                # Users module configuration
├── app.controller.ts                  # Main application endpoints
├── app.service.ts                     # Main application service
├── app.module.ts                      # Root application module
└── main.ts                            # Application bootstrap + Swagger setup

• Node.js (v18 or higher)
• pnpm (recommended) or npm

1. Clone the repository:

   git clone <repository-url>
   cd nestjs-guards

2. Install dependencies:

   pnpm install

3. Configure environment variables:

   # Copy the environment template
   cp .env.example .env
   
   # Edit the .env file with your values
   nano .env  # or use your preferred editor

   Required variables:

   JWT_SECRET=your-super-secret-jwt-key-here
   JWT_EXPIRES_IN=1h
   API_KEY=your-api-key-here

   ⚠️ Security Note: Use strong, randomly generated secrets in production. See ENVIRONMENT_CONFIG.md for detailed configuration guide.

4. Start the development server:

   pnpm run start:dev

5. Access the application:

   • API Base URL: http://localhost:3000
   • Swagger Documentation: http://localhost:3000/api
   • API JSON Schema: http://localhost:3000/api-json

Available demo API keys for testing:

• demo-api-key-123
• another-valid-key-456
• test-key-789

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "userId": 1,
    "username": "admin",
    "roles": ["admin"],
    "createdAt": "2024-01-01T12:00:00.000Z"
  }
}

curl -X GET http://localhost:3000/auth/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN_HERE"

curl -X GET http://localhost:3000/auth/admin \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN_HERE"

curl -X GET http://localhost:3000/auth/api-protected \
  -H "X-API-Key: demo-api-key-123"

curl -X GET http://localhost:3000/auth/double-protected \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-Key: demo-api-key-123"

Purpose: Validates JWT tokens and extracts user information.

Implementation:

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  constructor(private reflector: Reflector) {
    super();
  }

  canActivate(context: ExecutionContext) {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    
    if (isPublic) return true;
    return super.canActivate(context);
  }
}

Usage:

@UseGuards(JwtAuthGuard)
@Get('profile')
getUserProfile(@CurrentUser() user: JwtPayload) {
  return { user };
}

Purpose: Implements role-based access control.

Implementation:

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.getAllAndOverride<UserRole[]>(ROLES_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    
    if (!requiredRoles) return true;
    
    const { user } = context.switchToHttp().getRequest();
    return requiredRoles.some((role) => user.roles?.includes(role));
  }
}

Usage:

@Roles('admin', 'moderator')
@Get('admin-data')
@UseGuards(JwtAuthGuard, RolesGuard)
getAdminData() {
  return { message: 'Admin-only data' };
}

Purpose: Validates API keys from request headers.

Implementation:

@Injectable()
export class ApiKeyGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const apiKey = request.headers['x-api-key'];
    return VALID_API_KEYS.includes(apiKey);
  }
}

Usage:

@UseGuards(ApiKeyGuard)
@Get('api-protected')
getApiProtectedData() {
  return { message: 'API Key protected data' };
}

Marks endpoints as publicly accessible, bypassing JWT authentication:

export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

Usage:

@Public()
@Get('public-endpoint')
getPublicData() {
  return { message: 'This is public!' };
}

Defines required roles for endpoint access:

export const ROLES_KEY = 'roles';
export const Roles = (...roles: UserRole[]) => SetMetadata(ROLES_KEY, roles);

Usage:

@Roles('admin')
@Get('admin-only')
getAdminOnlyData() {
  return { message: 'Admin only!' };
}

Extracts current user information from JWT payload:

export const CurrentUser = createParamDecorator(
  (data: unknown, ctx: ExecutionContext): JwtPayload => {
    const request = ctx.switchToHttp().getRequest();
    return request.user;
  },
);

Usage:

@Get('me')
getCurrentUser(@CurrentUser() user: JwtPayload) {
  return { user };
}

1. Global JWT Guard - Applied to all routes by default
2. Public Decorator Check - Bypasses authentication if @Public()
3. JWT Token Validation - Validates and decodes JWT tokens
4. Roles Guard - Checks user roles against required roles
5. API Key Guard - Validates API keys when required

Request → JWT Guard → Public Check → Token Validation → Roles Guard → API Key Guard → Route Handler
                ↓              ↓              ↓              ↓               ↓
             If @Public     Validate JWT   Check User     Validate API    Execute
             → Skip Auth    → Extract User   Roles          Key (if req.)   Endpoint

1. Navigate to http://localhost:3000/api
2. Use the "Authorize" button to input JWT tokens
3. Test endpoints interactively with provided examples

All the cURL examples are provided in the Usage Examples section above.

# 1. Login
TOKEN=$(curl -s -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}' \
  | jq -r '.access_token')

# 2. Use token to access protected endpoint
curl -X GET http://localhost:3000/auth/profile \
  -H "Authorization: Bearer $TOKEN"

Create a .env file in the root directory:

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRES_IN=24h

# API Keys
VALID_API_KEYS=demo-api-key-123,another-valid-key-456,test-key-789

# Application
PORT=3000
NODE_ENV=development

Located in src/auth/constants.ts:

/**
 * JWT Configuration Factory
 *
 * This function creates JWT configuration using environment variables.
 * Environment variables should be defined in .env file:
 * - JWT_SECRET: Secret key for signing JWT tokens
 * - JWT_EXPIRES_IN: Token expiration time (default: '1h')
 */
export const createJwtConfig = (configService: ConfigService) => ({
  secret:
    configService.get<string>('JWT_SECRET') ||
    'default-secret-change-in-production',
  expiresIn: configService.get<string>('JWT_EXPIRES_IN') || '1h',
});

Why use ConfigService?

• ✅ Type Safety: Proper TypeScript support for configuration values
• ✅ Environment Management: Better handling of different environments (dev, prod, test)
• ✅ Validation: Built-in validation for configuration values
• ✅ Dependency Injection: Integrates seamlessly with NestJS DI system
• ✅ Testability: Easier to mock configuration in tests

1. Guard Implementation - How to create and use custom guards
2. Decorator Composition - Building reusable parameter decorators
3. Role-Based Access Control - Implementing RBAC in NestJS
4. JWT Handling - Secure token management and validation
5. API Documentation - Comprehensive Swagger setup
6. Security Best Practices - Proper authentication flows

• Guards
• Authentication
• Authorization
• Custom Decorators
• OpenAPI/Swagger

This is an educational project. Contributions that improve the learning experience are welcome:

1. Fork the repository
2. Create a feature branch
3. Add your improvements with detailed comments
4. Ensure all examples are working
5. Submit a pull request

This project is for educational purposes. Feel free to use it as a reference for learning NestJS security patterns.

nestjs guards authentication authorization jwt rbac api-key security typescript swagger educational

Happy Learning! 🎓

This project demonstrates production-ready security patterns in NestJS. Use it as a foundation for building secure, scalable applications with proper authentication and authorization.

src/
├── auth/                     # Authentication module
│   ├── decorators/          
│   │   ├── current-user.decorator.ts  # Extract user from request
│   │   ├── public.decorator.ts        # Mark routes as public
│   │   └── roles.decorator.ts         # Define required roles
│   ├── guards/              
│   │   ├── jwt-auth.guard.ts          # JWT authentication
│   │   ├── roles.guard.ts             # Role-based authorization
│   │   └── api-key.guard.ts           # API key validation
│   ├── interfaces/          
│   │   └── auth.interface.ts          # TypeScript interfaces
│   ├── auth.controller.ts             # Auth endpoints
│   ├── auth.service.ts                # Auth business logic
│   ├── auth.module.ts                 # Auth module configuration
│   └── constants.ts                   # JWT config & user roles
├── users/                    # User management module
│   ├── interfaces/          
│   │   └── user.interface.ts          # User entity interface
│   ├── users.controller.ts            # User endpoints
│   ├── users.service.ts               # User business logic
│   └── users.module.ts                # User module configuration
├── app.controller.ts                  # Main app routes
├── app.service.ts                     # Main app service
├── app.module.ts                      # Root module
└── main.ts                           # Application entry point

1. Clone and install dependencies:

git clone <repository-url>
cd nestjs-guards
pnpm install

2. Start the development server:

pnpm run start:dev

3. The application will be available at:

http://localhost:3000

pnpm run start:dev    # Watch mode
pnpm run start:debug  # Debug mode

pnpm run build
pnpm run start:prod

pnpm run test         # Unit tests
pnpm run test:e2e     # End-to-end tests
pnpm run test:cov     # Coverage report

The application comes with pre-configured users for testing:

For API key authentication testing:

• demo-api-key-123
• another-valid-key-456
• test-key-789

Purpose: Validates JWT tokens and extracts user information.

Features:

• Extracts Bearer tokens from Authorization header
• Validates token signature and expiration
• Supports public routes with @Public() decorator
• Attaches user payload to request object

Usage:

@UseGuards(JwtAuthGuard)
@Get('protected')
getProtectedData(@CurrentUser() user: JwtPayload) {
  return { user };
}

Purpose: Implements role-based access control.

Features:

• Works with @Roles() decorator
• Checks user roles against required roles
• Supports multiple roles per route
• Must be used after authentication guard

Usage:

@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('admin', 'moderator')
@Get('admin-data')
getAdminData() {
  return { message: 'Admin only' };
}

Purpose: Validates API keys for alternative authentication.

Features:

• Supports X-API-Key header
• Supports Authorization: ApiKey <key> format
• Independent of JWT authentication
• Configurable API key validation

Usage:

@UseGuards(ApiKeyGuard)
@Get('api-data')
getApiData() {
  return { message: 'API key protected' };
}

To enable global authentication (protect all routes by default):

// In auth.module.ts
providers: [
  {
    provide: APP_GUARD,
    useClass: JwtAuthGuard,
  },
]

Marks routes as public, bypassing global authentication.

@Public()
@Get('public-info')
getPublicInfo() {
  return { info: 'This is public' };
}

Specifies required roles for route access.

@Roles('admin')
@Get('admin-only')
getAdminOnly() {
  return { data: 'Admin only' };
}

Extracts authenticated user from request.

// Get full user object
@Get('profile')
getProfile(@CurrentUser() user: JwtPayload) {
  return user;
}

// Extract specific property
@Get('username')
getUsername(@CurrentUser('username') username: string) {
  return { username };
}

# Login
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "john", "password": "changeme"}'

# Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "userId": 1,
    "username": "john",
    "email": "[email protected]",
    "roles": ["user"]
  }
}

# Use the token from login
curl -H "Authorization: Bearer <your-jwt-token>" \
  http://localhost:3000/auth/profile

# Admin only route (use admin credentials)
curl -H "Authorization: Bearer <admin-jwt-token>" \
  http://localhost:3000/auth/admin

# Using X-API-Key header
curl -H "X-API-Key: demo-api-key-123" \
  http://localhost:3000/auth/api-protected

# Using Authorization header
curl -H "Authorization: ApiKey demo-api-key-123" \
  http://localhost:3000/auth/api-protected

# Requires both JWT and API key
curl -H "Authorization: Bearer <jwt-token>" \
     -H "X-API-Key: demo-api-key-123" \
     http://localhost:3000/auth/double-protected

pnpm run test

pnpm run test:e2e

Use the provided curl commands to test all endpoints.

• ✅ Use strong, random secrets
• ✅ Set appropriate token expiration
• ✅ Implement token refresh mechanism
• ✅ Validate tokens on every request

• ✅ Hash passwords with bcrypt
• ✅ Use salt rounds (10+ recommended)
• ✅ Never store plain text passwords
• ✅ Remove passwords from API responses

• ✅ Always validate input data
• ✅ Handle errors gracefully
• ✅ Use proper HTTP status codes
• ✅ Log security events

• ⚠️ Store secrets in environment variables
• ⚠️ Use HTTPS in production
• ⚠️ Implement rate limiting
• ⚠️ Add request logging
• ⚠️ Use proper CORS configuration

• NestJS Guards
• NestJS Authentication
• NestJS Authorization

• Guards: Route protection and access control
• Decorators: Metadata and parameter extraction
• JWT: Token-based authentication
• RBAC: Role-based authorization
• Middleware vs Guards: Understanding the differences

• Custom guard implementation
• Guard composition strategies
• Global vs route-level protection
• Multiple authentication methods
• Error handling in guards

This is an educational project. Contributions that improve the learning experience are welcome:

1. Fork the repository
2. Create a feature branch
3. Add comprehensive comments to your code
4. Update documentation if needed
5. Create a pull request

This project is licensed under the MIT License - see the LICENSE file for details.

After exploring this demo, consider:

1. Database Integration: Replace mock data with real database
2. Refresh Tokens: Implement proper refresh token strategy
3. Rate Limiting: Add request rate limiting
4. Email Verification: Add email confirmation flow
5. Password Reset: Implement password reset functionality
6. OAuth Integration: Add third-party authentication
7. Audit Logging: Track authentication events

Happy Learning! 🚀

This project demonstrates production-ready patterns for authentication and authorization in NestJS. Use it as a foundation for your own applications and as a reference for implementing security in enterprise applications.