Mục lục nội dung

Trong xu hướng kiến trúc web hiện đại, việc tách biệt hoàn toàn giữa Frontend (Next.js) và Backend (Laravel API) mang lại khả năng mở rộng linh hoạt và trải nghiệm người dùng tối ưu. Tuy nhiên, khi triển khai xác thực (Authentication), nhà phát triển thường đứng trước hai lựa chọn lớn: Token-based (Bearer JWT) hoặc Cookie-based (HttpOnly Cookie).

Mặc dù JWT truyền thống rất phổ biến vì tính vô trạng (stateless), nó lại bộc lộ điểm yếu nghiêm trọng về mặt bảo mật. Việc lưu trữ JWT trong localStorage khiến ứng dụng dễ bị tấn công XSS (Cross-Site Scripting). Ngược lại, cơ chế Cookie-based Authentication kết hợp với HttpOnly cookie giúp ẩn hoàn toàn dữ liệu phiên làm việc khỏi JavaScript phía client, loại bỏ nguy cơ XSS đánh cắp token.

Tuy nhiên, triển khai Cookie-based Authentication giữa Next.js (đặc biệt là phiên bản App Router hỗ trợ Server Components) và Laravel Backend lại tạo ra nhiều bài toán kỹ thuật phức tạp:

  • CORS & SameSite Cookies: Trình duyệt chặn gửi cookie cross-site nếu cấu hình domain, protocol hoặc thuộc tính SameSite không tương thích.
  • CSRF Protection: Cơ chế chống tấn công Cross-Site Request Forgery đòi hỏi sự phối hợp nhịp nhàng giữa hai hệ thống độc lập.
  • Bất đồng bộ trong Server Side Rendering (SSR): Server Components trong Next.js App Router chạy trên Server Node.js, không có đối tượng window hay trình duyệt tự động đính kèm cookie. Do đó, việc chuyển tiếp (forward) cookie từ client đến Next.js Server rồi từ Next.js Server tới Laravel API đòi hỏi kỹ thuật xử lý ngữ cảnh chính xác.

Laravel Sanctum cung cấp hệ thống xác thực nhẹ cho các ứng dụng đơn trang (SPA) hoặc frontend độc lập dựa trên stateful cookies. Thay vì tạo ra API Token dài vô tận, Sanctum lợi dụng cơ chế session native của Laravel kết hợp với mã bảo mật CSRF.

Luồng hoạt động chuẩn bao gồm 3 bước chính:

  1. CSRF Handshake: Client gửi request GET tới endpoint /sanctum/csrf-cookie trên Laravel. Laravel khởi tạo một CSRF token và trả về cookie XSRF-TOKEN cho client.
  2. Login Handshake: Client gửi request POST tới /login mang theo thông tin đăng nhập cùng cookie XSRF-TOKEN (được trình duyệt tự động đính kèm hoặc đọc từ header X-XSRF-TOKEN). Khởi tạo thành công, Laravel sẽ thiết lập cookie phiên làm việc laravel_session dưới dạng HttpOnly.
  3. Authenticated Requests: Mọi request sau đó từ Client tới API sẽ mang theo laravel_session cookie để xác thực danh tính người dùng.

Hướng dẫn triển khai từng bước chi tiết

1. Cấu hình Laravel Backend (CORS, Statefulness, Session Domain)

Đầu tiên, bạn cần cấu hình tệp config/sanctum.php để khai báo các domain được phép coi là stateful domains (miền lưu trữ trạng thái):

'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', sprintf(
    '%s%s',
    'localhost,localhost:3000,127.0.0.1,127.0.0.1:8000',
    env('APP_URL') ? ','.parse_url(env('APP_URL'), PHP_URL_HOST) : ''
))),

Tiếp theo, hiệu chỉnh tệp config/cors.php để đảm bảo trình duyệt cho phép truyền dữ liệu xác thực (credentials):

return [
    'paths' => ['api/*', 'sanctum/csrf-cookie', 'login', 'logout'],
    'allowed_methods' => ['*'],
    'allowed_origins' => ['http://localhost:3000', 'https://your-frontend-domain.com'],
    'allowed_origins_patterns' => [],
    'allowed_headers' => ['*'],
    'exposed_headers' => [],
    'max_age' => 0,
    'supports_credentials' => true,
];

Trong tệp .env của Laravel, lưu ý cài đặt cấu hình domain cho session và chuẩn hóa cookie:

SESSION_DRIVER=database
SESSION_DOMAIN=.yourdomain.com
SANCTUM_STATEFUL_DOMAINS=frontend.yourdomain.com
SESSION_SECURE_COOKIE=true
SESSION_HTTP_ONLY=true
SESSION_SAME_SITE=lax

2. Xử lý Client-Side Fetching và CSRF Handshake trong Next.js

Tại phía Next.js Frontend, chúng ta cần một HTTP client như Axios hoặc wrapper dựa trên fetch có cấu hình tự động gửi kèm credentials. Dưới đây là ví dụ triển khai bằng Axios Client phía Client-Side Component:

import axios from 'axios';

const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_BACKEND_URL,
  headers: {
    'X-Requested-With': 'XMLHttpRequest',
    'Accept': 'application/json',
  },
  withCredentials: true, // Bắt buộc phải bật để đính kèm cookie
  withXSRFToken: true,   // Yêu cầu Axios tự đọc XSRF-TOKEN cookie để gửi header X-XSRF-TOKEN
});

export const csrf = () => api.get('/sanctum/csrf-cookie');

export const login = async (credentials) => {
  await csrf(); // Gọi handshake CSRF trước khi thực hiện POST request
  return api.post('/login', credentials);
};

export const getUser = () => api.get('/api/user');

3. Đồng bộ hóa Authentication State trong Server Components (Next.js App Router)

Điểm khác biệt cốt lõi của Next.js App Router so với Pages Router chính là khái niệm Server Components (RSC). Khi một Server Component cần render dữ liệu riêng tư của người dùng từ Laravel API, Node.js server của Next.js phải đóng vai trò là một proxy đứng ra đọc cookie từ trình duyệt của client và forward toàn bộ chuỗi cookie đó tới Laravel API.

Dưới đây là phương thức triển khai lớp Data Fetching trên Server Component bằng cách sử dụng module cookies từ next/headers:

import { cookies } from 'next/headers';

export async function fetchUserProfileOnServer() {
  const cookieStore = await cookies();
  
  // Chuyển đổi danh sách cookie trong Next.js thành dạng chuỗi Cookie Header
  const cookieHeader = cookieStore
    .getAll()
    .map((c) => `${c.name}=${encodeURIComponent(c.value)}`)
    .join('; ');

  const response = await fetch(`${process.env.NEXT_PUBLIC_BACKEND_URL}/api/user`, {
    method: 'GET',
    headers: {
      'Accept': 'application/json',
      'X-Requested-With': 'XMLHttpRequest',
      'Cookie': cookieHeader, // Transfer cookie thủ công từ Next.js server sang Laravel API
    },
    cache: 'no-store', // Đảm bảo không lưu cache trang người dùng cá nhân
  });

  if (!response.ok) {
    if (response.status === 401) {
      return null; // Chưa xác thực
    }
    throw new Error('Failed to fetch user data');
  }

  return response.json();
}

Các lỗi phổ biến và Kinh nghiệm thực chiến (Best Practices)

Lỗi HTTP 419 (CSRF Token Mismatch)

Đây là lỗi phổ biến nhất khi tích hợp Laravel với các ứng dụng JS bên ngoài. Nguyên nhân chủ yếu xuất phát từ:

  • Chưa gọi endpoint /sanctum/csrf-cookie trước khi gửi form POST/PUT/DELETE.
  • Cấu hình SANCTUM_STATEFUL_DOMAINS thiếu cổng (port) hoặc thiếu sub-domain của Next.js app (ví dụ khai báo localhost nhưng frontend lại chạy trên localhost:3000).
  • Thiếu header X-Requested-With: XMLHttpRequest trong HTTP client khiến Laravel không nhận diện đây là yêu cầu AJAX/SPA.

Trong môi trường phát triển cục bộ (Local Development), trình duyệt thường nới lỏng chính sách cho localhost. Tuy nhiên trên Production:

  • Hãy đảm bảo cả Next.js và Laravel chạy trên cùng một top-level domain (ví dụ: app.domain.com cho Frontend và api.domain.com cho Backend).
  • Đảm bảo cấu hình SESSION_DOMAIN=.domain.com (có dấu chấm ở đầu) để cookie phiên làm việc chia sẻ được giữa các subdomain.
  • Bắt buộc bật SESSION_SECURE_COOKIE=true trên môi trường Production sử dụng chứng chỉ SSL (HTTPS). Nếu dùng HTTP bình thường mà bật flag này, trình duyệt sẽ tự động từ chối lưu cookie.

Kết luận

Triển khai xác thực Cookie-based giữa Next.js App Router và Laravel không chỉ nâng cao đáng kể độ bảo mật chống lại các đòn tấn công XSS mà còn mang tới trải nghiệm liền mạch cho người dùng. Bằng cách hiểu rõ luồng đi của HTTP Cookie giữa Client Browser, Next.js Node Server và Laravel API Server, bạn sẽ hoàn toàn làm chủ được kiến trúc Full-Stack tách biệt này.

Để tiếp thu trọn vẹn tư duy thiết kế hệ thống, cách tổ chức code bài bản và thực chiến xây dựng các dự án web quy mô thương mại từ nền tảng này, bạn có thể Tham khảo khóa học "Xây dựng ứng dụng kết hợp Laravel - ReactJS - NextJS" tại đây.