Role-based guards in NestJS - Step-by-Step Execution

Concept Flow - Role-based guards

Request comes in

↓

Guard checks user roles

↓

Has Role

↓

Allow

↓

Controller

The guard intercepts a request, checks if the user has the required role, then allows or denies access accordingly.

Execution Sample

NestJS

import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
@Injectable()
export class RolesGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const user = request.user;
    return user?.roles?.includes('admin');
  }
}

This guard checks if the user has the 'admin' role to allow access.

Execution Table

Step	Action	User Roles	Condition	Result
1	Request received	['user', 'admin']	Check if 'admin' in roles	True
2	Guard allows access	['user', 'admin']	Return true	Access granted
3	Request received	['user']	Check if 'admin' in roles	False
4	Guard denies access	['user']	Return false	Access denied

💡 Execution stops after guard returns true or false to allow or deny access.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4
user.roles	undefined	['user', 'admin']	['user', 'admin']	['user']	['user']
condition ('admin' in roles)	undefined	true	true	false	false
guard result	undefined	undefined	true	undefined	false

Key Moments - 2 Insights

Why does the guard deny access even if the user has other roles?

The guard specifically checks for the 'admin' role only (see execution_table step 3 and 4). If 'admin' is missing, it denies access regardless of other roles.

What happens if the user object is missing roles?

If user.roles is undefined, the guard will throw an error or deny access because it cannot find 'admin' in roles. Always ensure roles exist before checking.

Visual Quiz - 3 Questions

Look at the execution table, what is the guard result at step 2?

A false

B true

C undefined

D throws error

💡 Hint

Check the 'guard result' column after step 2 in variable_tracker.

At which step does the guard deny access?

A Step 4

B Step 2

C Step 1

D Step 3

💡 Hint

Look at the 'Result' column in execution_table for 'Access denied'.

If the user roles were ['admin', 'editor'], how would the condition in step 1 evaluate?

A False

B Undefined

C True

D Error

💡 Hint

The condition checks if 'admin' is included in roles array.

Concept Snapshot

Role-based guards in NestJS check user roles before allowing access.
Use canActivate method to inspect request user roles.
Return true to allow, false to deny.
Ensure user roles exist to avoid errors.
Common pattern: user.roles.includes('requiredRole').

Full Transcript

Role-based guards in NestJS work by intercepting incoming requests and checking if the user has the required role to access a resource. The guard uses the canActivate method to get the request and user roles. It then checks if the required role, such as 'admin', is present in the user's roles array. If yes, it returns true and allows access to the controller. If not, it returns false and denies access. The execution table shows steps where the guard checks roles and decides access. Variables like user.roles and the guard result change during execution. Beginners often get confused why access is denied if the user has other roles or if roles are missing. The guard strictly checks for the required role only. This visual trace helps understand how role-based guards control access in NestJS.

Practice

1. What is the main purpose of a role-based guard in NestJS?

easy

A. To manage application configuration

B. To handle database connections

C. To format HTTP responses

D. To restrict access to routes based on user roles

Solution

1. Step 1: Understand role-based guard function

   Role-based guards check user roles before allowing access to routes.

2. Step 2: Identify the correct purpose

   Restricting access based on roles matches the guard's role in security.

3. Final Answer:

   To restrict access to routes based on user roles -> Option D

4. Quick Check:

   Role-based guard = restrict access by roles [OK]

Hint: Guards control access; roles limit who can enter [OK]

Common Mistakes:

• Confusing guards with database or config management
• Thinking guards format responses
• Assuming guards handle unrelated tasks

2. Which of the following is the correct way to apply a role-based guard to a route in NestJS?

easy

A. @UseGuards(RolesGuard)\n@Get('profile')

B. @Controller('profile')\n@RolesGuard()

C. @Roles('admin')\n@UseGuards(AuthGuard)

D. @UseGuards(AuthGuard)\n@Get('profile')

Solution

1. Step 1: Identify correct guard usage syntax

   Use @UseGuards with the guard class to apply it to routes.

2. Step 2: Match with role-based guard usage

   @UseGuards(RolesGuard) is correct; @Roles decorator marks roles separately.

3. Final Answer:

   @UseGuards(RolesGuard)\n@Get('profile') -> Option A

4. Quick Check:

   @UseGuards(RolesGuard) applies guard [OK]

Hint: Use @UseGuards with guard class to protect routes [OK]

Common Mistakes:

• Using @RolesGuard() instead of @UseGuards
• Mixing @Roles and @UseGuards incorrectly
• Applying guards without @UseGuards decorator

3. Given this guard code snippet, what will be the result if the user role is 'user' and the route requires 'admin' role?

canActivate(context: ExecutionContext) {
  const roles = this.reflector.get('roles', context.getHandler());
  const request = context.switchToHttp().getRequest();
  const user = request.user;
  return roles.includes(user.role);
}

medium

A. Access granted

B. Access denied

C. Runtime error due to missing roles

D. Always returns true

Solution

1. Step 1: Understand role check logic

   The guard checks if the user's role is included in the allowed roles array.

2. Step 2: Apply given roles and user role

   User role is 'user', route requires 'admin', so roles.includes('user') is false.

3. Final Answer:

   Access denied -> Option B

4. Quick Check:

   User role not in allowed roles = deny access [OK]

Hint: Check if user role is in allowed roles array [OK]

Common Mistakes:

• Assuming access is granted if roles differ
• Thinking roles includes user role always
• Ignoring roles array presence

4. Identify the error in this role-based guard implementation:

canActivate(context: ExecutionContext) {
  const roles = this.reflector.get('roles', context.getHandler());
  const request = context.switchToHttp().getRequest();
  const user = request.user;
  if (!roles) {
    return false;
  }
  return roles.includes(user.role);
}

medium

A. Returns false if no roles metadata, blocking all access

B. Missing async keyword causes runtime error

C. Incorrect use of context.getHandler()

D. Should check user permissions instead of roles

Solution

1. Step 1: Analyze roles metadata check

   If roles metadata is missing, the guard returns false blocking access.

2. Step 2: Understand typical behavior for missing roles

   Usually, missing roles means no restriction, so returning false is too strict.

3. Final Answer:

   Returns false if no roles metadata, blocking all access -> Option A

4. Quick Check:

   No roles metadata should allow access, not block [OK]

Hint: Missing roles metadata should not block access by default [OK]

Common Mistakes:

• Assuming missing roles means deny access
• Forgetting to handle undefined roles gracefully
• Confusing async necessity in this context

5. You want to create a role-based guard that allows access if the user has any one of multiple roles specified on a route. Which approach correctly implements this behavior?

hard

A. Use multiple guards each checking one role and combine them with @UseGuards

B. Check only the first role in roles array against user.role in canActivate

C. Use @Roles('admin', 'editor') decorator and check if user.role is included in roles array inside canActivate

D. Ignore roles and allow access to all authenticated users

Solution

1. Step 1: Understand multiple roles in @Roles decorator

   @Roles can accept multiple roles as arguments to specify allowed roles.

2. Step 2: Implement canActivate to check inclusion

   Checking if user.role is in roles array allows access if user has any allowed role.

3. Final Answer:

   Use @Roles('admin', 'editor') decorator and check if user.role is included in roles array inside canActivate -> Option C

4. Quick Check:

   Check user role in roles array for multiple allowed roles [OK]

Hint: Check if user role is in roles array for multiple roles [OK]

Common Mistakes:

• Checking only first role ignores others
• Using multiple guards unnecessarily
• Allowing all authenticated users ignores roles