Laravel Sanctum là giải pháp xác thực được Laravel cung cấp cho các ứng dụng cần bảo vệ API. Sanctum đặc biệt phù hợp với SPA, ứng dụng mobile và các API đơn giản cần xác thực bằng token mà không nhất thiết phải triển khai một hệ thống OAuth2 phức tạp. Bài viết dưới đây tập trung vào cách Sanctum hoạt động, cách triển khai và những điểm cần lưu ý khi sử dụng trong dự án thực tế.
Laravel Sanctum là gì?
Laravel Sanctum là package hỗ trợ xác thực người dùng cho ứng dụng Laravel, chủ yếu thông qua hai cơ chế:
- Xác thực SPA bằng cookie và session.
- Xác thực API bằng personal access token.
Nhờ đó, Sanctum có thể đáp ứng nhiều mô hình ứng dụng khác nhau mà không cần xây dựng cơ chế authentication từ đầu.
Một API được bảo vệ bằng Sanctum thường sử dụng middleware:
Route::middleware(‘auth:sanctum’)->group(function () {
Route::get(‘/user’, function (Request $request) {
return $request->user();
});
});
Khi request đi vào route, Sanctum kiểm tra thông tin xác thực trước khi cho phép truy cập tài nguyên.
Sanctum hoạt động như thế nào?
Có thể hình dung luồng xác thực API bằng token như sau:
User đăng nhập
↓
Laravel xác thực tài khoản
↓
Tạo Personal Access Token
↓
Client lưu token
↓
Client gửi token trong request
↓
auth:sanctum kiểm tra token
↓
Cho phép hoặc từ chối request
Ví dụ client gửi: Authorization: Bearer 1|xxxxxxxxxxxxxxxx
Sanctum kiểm tra token và xác định người dùng tương ứng.
Nếu token hợp lệ, bạn có thể lấy user hiện tại:
$request->user();
Cài đặt Laravel Sanctum
Ở các phiên bản Laravel hiện đại, Sanctum có thể được cài đặt thông qua Artisan: php artisan install:api
Tùy phiên bản Laravel, cách cài đặt và các file được tạo có thể khác nhau. Vì vậy khi triển khai dự án cụ thể, nên đối chiếu với tài liệu của phiên bản Laravel đang sử dụng.
Sau khi cài đặt, chạy migration:
php artisan migrate
Sanctum cần bảng lưu personal access token để có thể quản lý token của người dùng.
Tạo API Token với Sanctum
Model User cần sử dụng trait HasApiTokens:
use Laravel\Sanctum\HasApiTokens;
class User extends Authenticatable
{
use HasApiTokens;
}
Sau khi người dùng đăng nhập thành công, có thể tạo token:
$token = $user->createToken(‘mobile-app’)->plainTextToken;
Sau đó trả token về client:
return response()->json([
‘token’ => $token
]);
Client sử dụng token này cho những request cần authentication.
Bảo vệ API bằng auth:sanctum
Đây là phần quan trọng nhất khi sử dụng Sanctum.
Ví dụ:
Route::middleware(‘auth:sanctum’)->get(‘/profile’, function (Request $request) {
return $request->user();
});
Nếu request không có thông tin xác thực hợp lệ, API sẽ từ chối truy cập.
Có thể nhóm nhiều endpoint:
Route::middleware(‘auth:sanctum’)->group(function () {
Route::get(‘/profile’, [ProfileController::class, ‘index’]);
Route::get(‘/orders’, [OrderController::class, ‘index’]);
Route::post(‘/orders’, [OrderController::class, ‘store’]);
});
Khi triển khai phần này, việc nắm rõ Route, Middleware, Request và User Model rất quan trọng. Nếu cần củng cố các thành phần nền trước khi xử lý authentication, bạn có thể tham khảo nội dung Laravel cơ bản để hiểu rõ hơn cách request đi qua middleware và controller.
Xác thực SPA bằng Cookie và Session
Với SPA được xây dựng cùng Laravel, Sanctum có thể sử dụng cookie/session thay vì yêu cầu frontend tự quản lý API token.
Luồng thường có dạng:
SPA
↓
Nhận CSRF Cookie
↓
Gửi thông tin đăng nhập
↓
Laravel tạo session
↓
Các request tiếp theo gửi cookie
↓
Sanctum xác thực user
Cách này phù hợp khi frontend và backend được thiết kế để phối hợp với nhau. Điểm cần lưu ý là SPA authentication của Sanctum khác với personal access token authentication. Không nên trộn hai cơ chế này trong cùng một luồng mà không hiểu rõ cách chúng hoạt động.
Xác thực Mobile bằng Personal Access Token
Ứng dụng Android hoặc iOS thường phù hợp với personal access token.
Sau khi đăng nhập:
$token = $user->createToken(‘mobile’)->plainTextToken;
Mobile app nhận token và gửi trong header:
Authorization: Bearer TOKEN
Các API cần bảo vệ sử dụng:
Route::middleware(‘auth:sanctum’)->group(function () {
// Protected API
});
Với mô hình này, token trở thành thông tin xác thực mà ứng dụng mobile sử dụng cho những request tiếp theo.
Thu hồi Token khi đăng xuất
Sanctum cho phép xóa token hiện tại:
$request->user()->currentAccessToken()->delete();
Hoặc xóa toàn bộ token của user:
$request->user()->tokens()->delete();
Hai cách có ý nghĩa khác nhau:
- currentAccessToken() → thu hồi token đang sử dụng.
- tokens()->delete() → thu hồi toàn bộ token.
Ví dụ, nếu một người dùng đăng nhập trên nhiều thiết bị, xóa toàn bộ token sẽ đăng xuất tài khoản khỏi tất cả thiết bị.
Token Abilities để giới hạn quyền
Sanctum hỗ trợ token abilities để giới hạn những gì một token được phép thực hiện.
Khi tạo token:
$token = $user->createToken(
‘mobile’,
[‘orders:read’, ‘orders:create’]
)->plainTextToken;
Sau đó có thể kiểm tra ability:
if ($request->user()->tokenCan(‘orders:read’)) {
// Cho phép đọc đơn hàng
}
Cách này hữu ích khi một người dùng hoặc một ứng dụng có nhiều loại token với phạm vi quyền khác nhau. Tuy nhiên, Authentication và Authorization vẫn là hai vấn đề riêng. Sanctum xác định request đến từ ai; việc user đó được phép thực hiện hành động nào cần được thiết kế thêm bằng Policy, Gate hoặc cơ chế phân quyền phù hợp.
Một số lỗi thường gặp khi dùng Sanctum
1. API trả về 401 Unauthorized
Kiểm tra:
Route::middleware(‘auth:sanctum’)
và đảm bảo client gửi đúng thông tin authentication.
Với token:
Authorization: Bearer TOKEN
Ngoài ra cần kiểm tra token có tồn tại và còn hiệu lực hay không.
2. User luôn trả về null
Kiểm tra route có sử dụng auth:sanctum hay chưa:
Route::middleware(‘auth:sanctum’)->get(‘/user’, function (Request $request) {
return $request->user();
});
Nếu không có middleware xác thực, Laravel không nhất thiết xác định được user từ request.
3. Token không hoạt động
Kiểm tra:
- Sanctum đã được cài đặt đúng chưa.
- Migration đã chạy chưa.
- User đã sử dụng HasApiTokens chưa.
- Token có được gửi đúng header không.
- Route có sử dụng auth:sanctum không.
4. Nhầm SPA Authentication với Token Authentication
Đây là lỗi về kiến trúc hơn là lỗi code.
SPA do Laravel phục vụ có thể sử dụng cookie/session, trong khi mobile app thường sử dụng personal access token. Trước khi triển khai cần xác định rõ client thuộc mô hình nào.
Khi thực hành các luồng authentication và API trong một project hoàn chỉnh, website Học Laravel có thể được sử dụng như nguồn tham khảo để kết nối Sanctum với các thành phần khác của framework thay vì học authentication như một phần độc lập.
Kết luận
Laravel Sanctum là giải pháp authentication gọn nhẹ cho nhiều ứng dụng Laravel hiện đại. Điểm quan trọng nhất là phân biệt đúng hai mô hình:
- SPA: ưu tiên cookie/session.
- Mobile hoặc API client: có thể sử dụng personal access token.
Sanctum phù hợp khi ứng dụng không cần đầy đủ OAuth2 nhưng vẫn cần cơ chế xác thực API rõ ràng, dễ triển khai và dễ quản lý. Khi hệ thống yêu cầu OAuth2 chuyên sâu, Passport sẽ phù hợp hơn.
