🔒 Authorization: Role-Based Access

🎯 Introduction

Welcome to this exciting tutorial on role-based authorization! 🎉 In this guide, we’ll explore how to build secure, scalable authorization systems that control who can access what in your applications.

You’ll discover how role-based access control (RBAC) can transform your TypeScript applications from security nightmares into fortress-like systems. Whether you’re building APIs 🌐, admin dashboards 🖥️, or user management systems 👥, understanding RBAC is essential for protecting your application’s resources.

By the end of this tutorial, you’ll feel confident implementing rock-solid authorization in your own projects! Let’s dive in! 🏊‍♂️

📚 Understanding Role-Based Authorization

🤔 What is Role-Based Authorization?

Role-based authorization is like a VIP club system 🎭. Think of it as a bouncer at a nightclub who checks your membership card before letting you into different areas. Some people get basic access to the main floor, while others get VIP access to exclusive areas.

In TypeScript terms, RBAC controls what authenticated users can access based on their assigned roles 🛡️. This means you can:

✨ Control access to specific resources
🚀 Scale permissions across large teams
🛡️ Maintain security without complexity
📊 Audit who accessed what and when

💡 Why Use Role-Based Authorization?

Here’s why developers love RBAC:

Scalability 📈: Manage permissions for thousands of users
Maintainability 🔧: Change role permissions once, affect all users
Security 🔒: Principle of least privilege built-in
Clarity 👁️: Clear understanding of who can do what

Real-world example: Imagine building a hospital management system 🏥. With RBAC, doctors can access patient records, nurses can update vital signs, and admin staff can only view billing information.

🔧 Basic Syntax and Usage

📝 Simple Example

Let’s start with a friendly authorization system:

// 👋 Hello, secure TypeScript!
enum Role {
  ADMIN = "admin",     // 👑 Full access
  USER = "user",       // 👤 Basic access
  GUEST = "guest"      // 👀 View only
}

// 🎨 Creating a user type
interface User {
  id: string;
  name: string;
  email: string;
  role: Role;          // 🎭 Their assigned role
  isActive: boolean;   // ✅ Account status
}

// 🛡️ Authorization decorator
function requireRole(allowedRoles: Role[]) {
  return function (target: any, propertyName: string, descriptor: PropertyDescriptor) {
    const method = descriptor.value;
    
    descriptor.value = function (...args: any[]) {
      const user: User = this.currentUser; // 👤 Get current user
      
      if (!allowedRoles.includes(user.role)) {
        throw new Error(`🚫 Access denied. Required roles: ${allowedRoles.join(', ')}`);
      }
      
      return method.apply(this, args);
    };
  };
}

💡 Explanation: The requireRole decorator checks if the current user has permission before executing any method!

🎯 Common Authorization Patterns

Here are patterns you’ll use daily:

// 🏗️ Pattern 1: Resource-based permissions
interface Permission {
  resource: string;    // 📋 What resource (users, posts, etc.)
  action: string;      // ⚡ What action (read, write, delete)
  conditions?: any;    // 🎯 Optional conditions
}

// 🎨 Pattern 2: Role definitions
interface RoleDefinition {
  name: Role;
  permissions: Permission[];
  description: string;
}

// 🔄 Pattern 3: Authorization service
class AuthorizationService {
  private rolePermissions = new Map<Role, Permission[]>();
  
  // 🎯 Check if user can perform action
  canAccess(user: User, resource: string, action: string): boolean {
    const permissions = this.rolePermissions.get(user.role) || [];
    return permissions.some(p => 
      p.resource === resource && p.action === action
    );
  }
}

💡 Practical Examples

🏥 Example 1: Hospital Management System

Let’s build something real and important:

// 🏥 Define hospital roles
enum HospitalRole {
  DOCTOR = "doctor",
  NURSE = "nurse", 
  ADMIN = "admin",
  PATIENT = "patient"
}

// 🧑‍⚕️ Hospital user
interface HospitalUser {
  id: string;
  name: string;
  role: HospitalRole;
  department?: string;  // 🏢 Which department
  licenseNumber?: string; // 📜 Professional license
}

// 📋 Patient record interface
interface PatientRecord {
  id: string;
  patientName: string;
  diagnosis: string;
  medications: string[];
  assignedDoctor: string;
  isConfidential: boolean; // 🔒 Sensitive cases
}

// 🛡️ Hospital authorization service
class HospitalAuth {
  private currentUser: HospitalUser;
  
  constructor(user: HospitalUser) {
    this.currentUser = user;
  }
  
  // 👀 Can read patient records?
  canReadPatientRecord(record: PatientRecord): boolean {
    switch (this.currentUser.role) {
      case HospitalRole.DOCTOR:
        return record.assignedDoctor === this.currentUser.id || !record.isConfidential;
      
      case HospitalRole.NURSE:
        return !record.isConfidential; // 🚫 No confidential records
      
      case HospitalRole.ADMIN:
        return true; // 👑 Full access
      
      case HospitalRole.PATIENT:
        return false; // 🚫 Patients can't read others' records
      
      default:
        return false;
    }
  }
  
  // ✏️ Can modify patient records?
  canModifyPatientRecord(record: PatientRecord): boolean {
    switch (this.currentUser.role) {
      case HospitalRole.DOCTOR:
        return record.assignedDoctor === this.currentUser.id;
      
      case HospitalRole.NURSE:
        return true; // ✅ Nurses can update vital signs
      
      case HospitalRole.ADMIN:
        return true; // 👑 Full access
      
      default:
        return false; // 🚫 Others can't modify
    }
  }
  
  // 💊 Can prescribe medications?
  canPrescribeMedication(): boolean {
    return this.currentUser.role === HospitalRole.DOCTOR && 
           !!this.currentUser.licenseNumber; // 📜 Must have license
  }
}

// 🎮 Let's use it!
const drSmith: HospitalUser = {
  id: "doc001",
  name: "Dr. Smith",
  role: HospitalRole.DOCTOR,
  department: "Cardiology",
  licenseNumber: "MD123456"
};

const nurseJones: HospitalUser = {
  id: "nurse001", 
  name: "Nurse Jones",
  role: HospitalRole.NURSE,
  department: "Emergency"
};

const patientRecord: PatientRecord = {
  id: "patient001",
  patientName: "John Doe",
  diagnosis: "Hypertension",
  medications: ["Lisinopril"],
  assignedDoctor: "doc001",
  isConfidential: false
};

// 🧪 Test authorization
const doctorAuth = new HospitalAuth(drSmith);
const nurseAuth = new HospitalAuth(nurseJones);

console.log("👨‍⚕️ Doctor can read:", doctorAuth.canReadPatientRecord(patientRecord)); // ✅ true
console.log("👩‍⚕️ Nurse can read:", nurseAuth.canReadPatientRecord(patientRecord));   // ✅ true
console.log("💊 Doctor can prescribe:", doctorAuth.canPrescribeMedication());        // ✅ true
console.log("💊 Nurse can prescribe:", nurseAuth.canPrescribeMedication());          // ❌ false

🎯 Try it yourself: Add a canViewBilling method that only allows admin and billing staff!

🏪 Example 2: E-commerce Admin System

Let’s make it practical for business:

// 🛒 E-commerce roles
enum EcommerceRole {
  SUPER_ADMIN = "super_admin",
  STORE_ADMIN = "store_admin", 
  INVENTORY_MANAGER = "inventory_manager",
  CUSTOMER_SERVICE = "customer_service",
  VIEWER = "viewer"
}

// 📦 Product interface
interface Product {
  id: string;
  name: string;
  price: number;
  stock: number;
  category: string;
  isActive: boolean;
}

// 🎭 Permission system
class EcommercePermissions {
  private static permissions = new Map<EcommerceRole, string[]>([
    [EcommerceRole.SUPER_ADMIN, ["*"]], // 🌟 Everything
    [EcommerceRole.STORE_ADMIN, [
      "products:read", "products:write", "products:delete",
      "orders:read", "orders:write", 
      "users:read"
    ]],
    [EcommerceRole.INVENTORY_MANAGER, [
      "products:read", "products:write",
      "inventory:read", "inventory:write"
    ]],
    [EcommerceRole.CUSTOMER_SERVICE, [
      "orders:read", "orders:write",
      "users:read", "returns:write"
    ]],
    [EcommerceRole.VIEWER, ["products:read", "orders:read"]]
  ]);
  
  // 🔍 Check permission
  static hasPermission(role: EcommerceRole, permission: string): boolean {
    const rolePermissions = this.permissions.get(role) || [];
    
    // 🌟 Super admin has everything
    if (rolePermissions.includes("*")) {
      return true;
    }
    
    return rolePermissions.includes(permission);
  }
  
  // 🎯 Require permission decorator
  static requirePermission(permission: string) {
    return function (target: any, propertyName: string, descriptor: PropertyDescriptor) {
      const method = descriptor.value;
      
      descriptor.value = function (...args: any[]) {
        const user = this.currentUser;
        
        if (!EcommercePermissions.hasPermission(user.role, permission)) {
          throw new Error(`🚫 Permission denied: ${permission}`);
        }
        
        return method.apply(this, args);
      };
    };
  }
}

// 🏪 Product service with authorization
class ProductService {
  currentUser: { role: EcommerceRole; name: string };
  
  constructor(user: { role: EcommerceRole; name: string }) {
    this.currentUser = user;
  }
  
  // 👀 Read products (most roles can do this)
  @EcommercePermissions.requirePermission("products:read")
  getProducts(): Product[] {
    console.log(`📋 ${this.currentUser.name} is viewing products`);
    return [
      { id: "1", name: "TypeScript Book", price: 29.99, stock: 100, category: "books", isActive: true }
    ];
  }
  
  // ✏️ Create product (restricted)
  @EcommercePermissions.requirePermission("products:write")
  createProduct(product: Omit<Product, "id">): Product {
    const newProduct: Product = {
      ...product,
      id: Math.random().toString(36).substr(2, 9)
    };
    console.log(`✨ ${this.currentUser.name} created product: ${newProduct.name}`);
    return newProduct;
  }
  
  // 🗑️ Delete product (very restricted)
  @EcommercePermissions.requirePermission("products:delete")
  deleteProduct(productId: string): void {
    console.log(`🗑️ ${this.currentUser.name} deleted product: ${productId}`);
  }
}

// 🎮 Test different user roles
const superAdmin = { role: EcommerceRole.SUPER_ADMIN, name: "Alice" };
const inventoryManager = { role: EcommerceRole.INVENTORY_MANAGER, name: "Bob" };
const viewer = { role: EcommerceRole.VIEWER, name: "Charlie" };

const adminService = new ProductService(superAdmin);
const inventoryService = new ProductService(inventoryManager);
const viewerService = new ProductService(viewer);

try {
  // ✅ These will work
  adminService.getProducts();
  inventoryService.getProducts();
  viewerService.getProducts();
  
  // ✅ These will work
  adminService.createProduct({ name: "New Book", price: 19.99, stock: 50, category: "books", isActive: true });
  inventoryService.createProduct({ name: "Another Book", price: 24.99, stock: 30, category: "books", isActive: true });
  
  // 🚫 This will fail!
  viewerService.createProduct({ name: "Forbidden Book", price: 39.99, stock: 10, category: "books", isActive: true });
} catch (error) {
  console.log("⚠️ Authorization failed:", error.message);
}

🚀 Advanced Concepts

🧙‍♂️ Advanced Topic 1: Dynamic Permissions

When you’re ready to level up, try this advanced pattern:

// 🎯 Dynamic permission system
interface DynamicPermission {
  resource: string;
  action: string;
  conditions: (user: any, resource: any) => boolean; // 🧠 Smart conditions
}

// 🪄 Context-aware authorization
class AdvancedAuthService {
  private permissions: DynamicPermission[] = [];
  
  // 📝 Add dynamic permission
  addPermission(permission: DynamicPermission): void {
    this.permissions.push(permission);
  }
  
  // 🎯 Check with context
  canAccess(user: any, action: string, resource: any): boolean {
    return this.permissions.some(permission => 
      permission.action === action &&
      permission.resource === resource.type &&
      permission.conditions(user, resource)
    );
  }
}

// 🎮 Usage example
const advancedAuth = new AdvancedAuthService();

// 📋 Users can only edit their own posts
advancedAuth.addPermission({
  resource: "post",
  action: "edit",
  conditions: (user, post) => user.id === post.authorId
});

// 👥 Managers can edit posts in their department
advancedAuth.addPermission({
  resource: "post", 
  action: "edit",
  conditions: (user, post) => user.role === "manager" && user.department === post.department
});

🏗️ Advanced Topic 2: Hierarchical Roles

For the brave developers:

// 🚀 Role hierarchy system
class RoleHierarchy {
  private hierarchy = new Map<Role, Role[]>([
    [Role.ADMIN, [Role.USER, Role.GUEST]], // 👑 Admin inherits from user and guest
    [Role.USER, [Role.GUEST]]              // 👤 User inherits from guest
  ]);
  
  // 🔍 Get all inherited roles
  getInheritedRoles(role: Role): Role[] {
    const inherited = this.hierarchy.get(role) || [];
    const allRoles = [role, ...inherited];
    
    // 🔄 Recursively get inherited roles
    inherited.forEach(inheritedRole => {
      const deeper = this.getInheritedRoles(inheritedRole);
      allRoles.push(...deeper.filter(r => !allRoles.includes(r)));
    });
    
    return allRoles;
  }
  
  // ✅ Check if role has permission through inheritance
  hasPermissionThroughInheritance(userRole: Role, requiredRole: Role): boolean {
    const inheritedRoles = this.getInheritedRoles(userRole);
    return inheritedRoles.includes(requiredRole);
  }
}

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Hard-coded Permissions

// ❌ Wrong way - hard-coded everywhere!
function deleteUser(userId: string, currentUser: User) {
  if (currentUser.role !== "admin") { // 💥 Hard-coded!
    throw new Error("Not allowed");
  }
  // Delete logic...
}

// ✅ Correct way - centralized authorization!
class UserService {
  constructor(private auth: AuthorizationService) {}
  
  @requireRole([Role.ADMIN])
  deleteUser(userId: string): void {
    console.log(`🗑️ Deleted user: ${userId}`);
  }
}

🤯 Pitfall 2: Forgetting to Check Authorization

// ❌ Dangerous - no authorization check!
async function sensitiveOperation(data: any) {
  return await database.deleteAllData(); // 💥 Anyone can do this!
}

// ✅ Safe - always check first!
@requireRole([Role.SUPER_ADMIN])
async function sensitiveOperation(data: any) {
  console.log("🛡️ Authorization passed, proceeding...");
  return await database.deleteAllData(); // ✅ Only super admins!
}

🚨 Pitfall 3: Role Information in Frontend

// ❌ Wrong - trusting the frontend!
// Frontend sends: { role: "admin" }
// Server believes it without verification 💥

// ✅ Correct - server-side verification!
class SecureUserService {
  async getCurrentUser(token: string): Promise<User> {
    const decoded = jwt.verify(token, SECRET_KEY); // 🔑 Verify token
    return await database.users.findById(decoded.userId); // 🛡️ Get from DB
  }
}

🛠️ Best Practices

🎯 Principle of Least Privilege: Give minimum permissions needed
📝 Centralized Authorization: Keep all permission logic in one place
🛡️ Server-side Verification: Never trust the client
🔑 Secure Token Storage: Use HTTPOnly cookies or secure storage
📊 Audit Everything: Log all authorization decisions
🔄 Regular Reviews: Periodically review user permissions
🧪 Test Authorization: Write tests for permission edge cases

🧪 Hands-On Exercise

🎯 Challenge: Build a School Management System

Create a type-safe school administration system:

📋 Requirements:

🎓 Students can view their own grades and schedules
👨‍🏫 Teachers can manage their classes and grade students
👑 Principals can access everything
📚 Librarians can manage library resources
👥 Parents can view their child’s information
🔒 Sensitive information (disciplinary records) restricted to admin

🚀 Bonus Points:

Add grade-level restrictions (elementary vs high school)
Implement subject-specific teacher permissions
Create a parent-student relationship system
Add audit logging for sensitive operations

💡 Solution

🔍 Click to see solution

// 🎯 Our type-safe school system!
enum SchoolRole {
  STUDENT = "student",
  TEACHER = "teacher", 
  PRINCIPAL = "principal",
  LIBRARIAN = "librarian",
  PARENT = "parent"
}

// 👤 School user interface
interface SchoolUser {
  id: string;
  name: string;
  role: SchoolRole;
  gradeLevel?: number;     // 📚 For students (K-12)
  subjects?: string[];     // 📖 For teachers
  childrenIds?: string[];  // 👨‍👩‍👧‍👦 For parents
}

// 📊 Student record
interface StudentRecord {
  studentId: string;
  grades: { subject: string; grade: string; teacherId: string }[];
  schedule: { subject: string; time: string; teacherId: string }[];
  disciplinaryRecords: string[]; // 🔒 Sensitive
  parentIds: string[];
}

// 📚 Library resource
interface LibraryResource {
  id: string;
  title: string;
  type: "book" | "digital" | "equipment";
  isAvailable: boolean;
  borrowedBy?: string;
}

// 🛡️ School authorization service
class SchoolAuthService {
  private currentUser: SchoolUser;
  
  constructor(user: SchoolUser) {
    this.currentUser = user;
  }
  
  // 📊 Can view student grades?
  canViewGrades(studentRecord: StudentRecord): boolean {
    switch (this.currentUser.role) {
      case SchoolRole.STUDENT:
        return studentRecord.studentId === this.currentUser.id;
      
      case SchoolRole.TEACHER:
        // 👨‍🏫 Can see grades for subjects they teach
        return studentRecord.grades.some(grade => 
          this.currentUser.subjects?.includes(grade.subject)
        );
      
      case SchoolRole.PRINCIPAL:
        return true; // 👑 Full access
      
      case SchoolRole.PARENT:
        return studentRecord.parentIds.includes(this.currentUser.id);
      
      default:
        return false;
    }
  }
  
  // ✏️ Can modify grades?
  canModifyGrades(studentRecord: StudentRecord, subject: string): boolean {
    switch (this.currentUser.role) {
      case SchoolRole.TEACHER:
        return this.currentUser.subjects?.includes(subject) ?? false;
      
      case SchoolRole.PRINCIPAL:
        return true; // 👑 Can override any grade
      
      default:
        return false;
    }
  }
  
  // 🔒 Can view disciplinary records?
  canViewDisciplinaryRecords(studentRecord: StudentRecord): boolean {
    switch (this.currentUser.role) {
      case SchoolRole.PRINCIPAL:
        return true; // 👑 Full access to sensitive records
      
      case SchoolRole.TEACHER:
        // 🤔 Only if they teach the student
        return studentRecord.grades.some(grade => 
          this.currentUser.subjects?.includes(grade.subject)
        );
      
      default:
        return false; // 🚫 Sensitive information
    }
  }
  
  // 📚 Can manage library resources?
  canManageLibrary(): boolean {
    return this.currentUser.role === SchoolRole.LIBRARIAN || 
           this.currentUser.role === SchoolRole.PRINCIPAL;
  }
  
  // 📖 Can borrow books?
  canBorrowBooks(): boolean {
    return [SchoolRole.STUDENT, SchoolRole.TEACHER].includes(this.currentUser.role);
  }
}

// 🎓 School management service
class SchoolService {
  constructor(private auth: SchoolAuthService) {}
  
  // 📊 Get student grades
  getGrades(studentId: string): any {
    const studentRecord: StudentRecord = {
      studentId,
      grades: [
        { subject: "Math", grade: "A", teacherId: "teacher001" },
        { subject: "Science", grade: "B+", teacherId: "teacher002" }
      ],
      schedule: [],
      disciplinaryRecords: ["Late to class on 2024-01-15"],
      parentIds: ["parent001"]
    };
    
    if (!this.auth.canViewGrades(studentRecord)) {
      throw new Error("🚫 Access denied: Cannot view grades");
    }
    
    return studentRecord.grades;
  }
  
  // ✏️ Update grade
  updateGrade(studentId: string, subject: string, newGrade: string): void {
    const studentRecord: StudentRecord = {
      studentId,
      grades: [{ subject, grade: "B", teacherId: "teacher001" }],
      schedule: [],
      disciplinaryRecords: [],
      parentIds: []
    };
    
    if (!this.auth.canModifyGrades(studentRecord, subject)) {
      throw new Error(`🚫 Access denied: Cannot modify ${subject} grades`);
    }
    
    console.log(`✅ Updated ${subject} grade to ${newGrade} for student ${studentId}`);
  }
  
  // 📚 Borrow book
  borrowBook(bookId: string): void {
    if (!this.auth.canBorrowBooks()) {
      throw new Error("🚫 Access denied: Cannot borrow books");
    }
    
    console.log(`📖 Book ${bookId} borrowed successfully`);
  }
}

// 🎮 Test the system!
const student: SchoolUser = {
  id: "student001",
  name: "Emma Smith",
  role: SchoolRole.STUDENT,
  gradeLevel: 10
};

const teacher: SchoolUser = {
  id: "teacher001", 
  name: "Mr. Johnson",
  role: SchoolRole.TEACHER,
  subjects: ["Math", "Physics"]
};

const parent: SchoolUser = {
  id: "parent001",
  name: "Mrs. Smith",
  role: SchoolRole.PARENT,
  childrenIds: ["student001"]
};

// 🧪 Test different permissions
const studentAuth = new SchoolAuthService(student);
const teacherAuth = new SchoolAuthService(teacher);
const parentAuth = new SchoolAuthService(parent);

const studentService = new SchoolService(studentAuth);
const teacherService = new SchoolService(teacherAuth);
const parentService = new SchoolService(parentAuth);

try {
  // ✅ These should work
  console.log("📊 Student grades:", studentService.getGrades("student001"));
  teacherService.updateGrade("student001", "Math", "A+");
  studentService.borrowBook("book123");
  
  // 🚫 This should fail
  studentService.updateGrade("student001", "Math", "A+");
} catch (error) {
  console.log("⚠️ Authorization failed:", error.message);
}

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

✅ Create role-based authorization with confidence 💪
✅ Avoid common security mistakes that trip up beginners 🛡️
✅ Apply RBAC patterns in real projects 🎯
✅ Debug authorization issues like a pro 🐛
✅ Build secure applications with TypeScript! 🚀

Remember: Security is not a feature you add later - it’s a foundation you build on! 🏗️

🤝 Next Steps

Congratulations! 🎉 You’ve mastered role-based authorization!

Here’s what to do next:

💻 Practice with the school management exercise above
🏗️ Build a small project using RBAC (try a blog with admin/author/reader roles)
📚 Move on to our next tutorial: JWT Authentication Implementation
🌟 Share your secure applications with others!

Remember: Every security expert was once a beginner. Keep coding, keep learning, and most importantly, keep your applications secure! 🚀

Happy coding and stay secure! 🎉🔒✨

Prerequisites

What you'll learn