Auth0 Next.js SDK: Hướng Dẫn Xác Thực Next.js

Auth0 Next.js SDK Là Gì?

Auth0 Next.js SDK là thư viện TypeScript thêm xác thực người dùng dựa trên Auth0 vào ứng dụng Next.js, phát hành dưới tên gói @auth0/nextjs-auth0 trên npm. Nó cung cấp một Auth0Client để khởi tạo phía server cùng một middleware (hoặc proxy) handler chặn request ngay tại network boundary để quản lý các route login, callback, và logout. SDK này hỗ trợ cả mô hình middleware của App Router dùng trong Next.js 15 lẫn quy ước proxy.ts mới ở Next.js 16.

Các Tùy Chọn Xác Thực Có Thể Cấu Hình

• ✓Tùy chọn `domain` chấp nhận một chuỗi tĩnh hoặc một hàm `DomainResolver`, cho phép bạn phục vụ nhiều custom domain Auth0 từ một lần deploy.
• ✓Tùy chọn `logoutStrategy` (`auto`, `oidc`, hoặc `v2`) quyết định logout gọi endpoint OIDC end-session hay endpoint `/v2/logout` của Auth0, endpoint sau hỗ trợ wildcard URL.
• ✓Kiểm soát rolling session qua tùy chọn `session`, bao gồm predicate `beforeSessionRolled` để quyết định theo từng request có gia hạn session hay không.
• ✓`enableParallelTransactions` bật mặc định; mỗi lần đăng nhập diễn ra đồng thời sẽ nhận một transaction cookie gắn giá trị state riêng thay vì mọi lần đăng nhập dùng chung một cookie dễ xung đột.
• ✓Interface `sessionStore` cho phép cắm vào cơ chế lưu session dựa trên database của riêng bạn thay vì cookie mã hoá mặc định.
• ✓Hook `beforeSessionSaved` và `onCallback` cho phép chỉnh sửa session trước khi lưu, hoặc tự xử lý lỗi và redirect ở bước callback.
• ✓`pushedAuthorizationRequests` bật giao thức PAR khi giao tiếp với authorization server, còn `clientAssertionSigningKey`/`clientAssertionSigningAlg` hỗ trợ xác thực client kiểu `private_key_jwt`.

Cài Đặt Auth0 Next.js SDK

Cài đặt package bằng `npm i @auth0/nextjs-auth0`. README nói SDK này cần Node.js 20 LTS hoặc các bản LTS mới hơn; không có tuyên bố hỗ trợ cho phiên bản cũ hơn. Sau khi cài, thêm bốn biến môi trường vào `.env.local`: `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`, và `AUTH0_SECRET`, cùng `APP_BASE_URL` tùy chọn cho môi trường có domain cố định. Domain, client ID, và secret lấy từ một ứng dụng trên Auth0 Dashboard, ứng dụng đó phải được tạo dưới dạng 'Regular Web Application' — các loại ứng dụng khác không được tài liệu ghi là tương thích. Tạo `AUTH0_SECRET` — dùng để mã hoá session và transaction cookie — bằng lệnh `openssl rand -hex 32`.

Bắt Đầu Với Xác Thực Next.js

Tạo file `lib/auth0.ts` và khởi tạo `new Auth0Client()`; nó tự lấy bốn biến môi trường và áp dụng những gì README gọi là cấu hình cookie an toàn mặc định. Tiếp theo là thiết lập network boundary: trên Next.js 15 đó là file `middleware.ts` ở thư mục gốc dự án (nằm trong `src/` nếu bạn dùng cấu trúc đó) gọi `auth0.middleware(request)`, với matcher loại trừ `_next/static`, `_next/image`, và vài file metadata. Trên Next.js 16, `proxy.ts` thay cho `middleware.ts` làm file được khuyến nghị, hàm `proxy` của nó nhận kiểu `Request` chuẩn thay vì `NextRequest`. README ghi rằng `middleware.ts` vẫn chạy được trên Next.js 16 dưới Edge runtime để tương thích ngược, nhưng nó đã bị đánh dấu deprecated trên Node runtime và sẽ bị gỡ bỏ sau này. Sau khi thiết lập xong, đưa người dùng tới `/auth/login` để bắt đầu luồng đăng nhập, và gọi `auth0.getSession()` trong server component để đọc thông tin người dùng đã đăng nhập — README nói rõ nên dùng thẻ anchor thường thay vì component `<Link>` của Next.js cho các route auth để tránh việc điều hướng bị xử lý phía client. Nếu bạn không set `APP_BASE_URL`, SDK sẽ suy ra base URL từ request gửi tới để giữ cho preview URL trên Vercel và Netlify hoạt động mà không cần cấu hình riêng; nhưng ở production, việc này buộc SDK bật secure cookie, và sẽ ném lỗi `InvalidConfigurationError` nếu bạn cố tắt nó.

Giải Pháp Xác Thực Next.js Thay Thế

Câu Hỏi Thường Gặp Về Auth0 Next.js SDK

Vấn đề Auth0 Next.js SDK giải quyết

Tích hợp OAuth vào một ứng dụng Next.js App Router nghĩa là bạn phải tự viết redirect đăng nhập, một callback handler đổi code lấy token, session cookie mã hoá, và logout, trong khi các quy ước routing của Next.js liên tục thay đổi (App Router, rồi middleware.ts, giờ là proxy.ts ở Next.js 16). Tài liệu setup của Auth0 Next.js SDK tồn tại vì phần đấu nối đó phải nằm đúng chỗ tại network boundary, nếu không cả luồng auth sẽ hỏng, và phải làm lại mỗi khi Next.js đổi cách network boundary hoạt động. SDK này gói gọn Auth0Client cùng middleware/proxy handler để phần đấu nối đó, việc mã hoá cookie, và đường di chuyển Next.js 15 sang 16 là việc của Auth0 phải cập nhật, không phải của bạn.

Trường hợp sử dụng tốt nhất

• •Thêm đăng nhập cho site Next.js App Router đã dùng Auth0 (hoặc đang chuyển sang Auth0) làm identity provider, thay vì tự viết luồng OAuth riêng.
• •Server component cần đọc thông tin người dùng đã đăng nhập trực tiếp qua `auth0.getSession()` mà không cần kiểm tra auth riêng phía client.
• •Quy trình preview deploy trên Vercel hoặc Netlify, nơi base URL đổi theo từng branch và bạn không muốn hardcode `APP_BASE_URL` cho từng bản.
• •Setup multi-tenant cần nhiều custom domain Auth0, dùng hàm `DomainResolver` thay vì một chuỗi domain tĩnh duy nhất.
• •Team đang chuyển một app Next.js 15 có sẵn `middleware.ts` cho auth sang Next.js 16 và quy ước `proxy.ts` của nó.

Ai nên dùng — và ai nên bỏ qua

Hãy thử Auth0 Next.js SDK nếu team bạn đã dùng Auth0, hoặc đang chọn một identity provider được host sẵn, và muốn phần đấu nối middleware/proxy của App Router, mã hoá session cookie, và đường di chuyển sang Next.js 16 được lo sẵn thay vì tự xây từ đầu. Bỏ qua nếu bạn không muốn phụ thuộc vào identity provider bên ngoài — Auth.js hoặc một lựa chọn tự host như authentik bỏ được sự phụ thuộc tài khoản đó — hoặc nếu ứng dụng của bạn không chạy Next.js, vì SDK này gắn chặt với quy ước middleware và proxy của framework đó.

Repo liên quan