Laravel 10 OAuth2 Sanctum: Полное руководство по настройке

В современном мире API‑аутентификации ключевое значение имеет безопасность и гибкость. Laravel 10 предлагает в комплекте Sanctum – легковесный пакет, который прекрасно подходит для реализации OAuth‑2.0. В этом руководстве подробно разберём, как настроить Sanctum, создать токены и реализовать механизм refresh‑токенов, чтобы ваш API оставался надёжным и масштабируемым.

Разбор задачи

Когда вы разрабатываете API, вам необходимо обеспечить защищённый доступ к ресурсам. OAuth‑2.0 предоставляет универсальный протокол, позволяющий выдавать клиентам access‑токены, а также refresh‑токены для продления сессии без повторной авторизации. Laravel Sanctum упрощает эту задачу, обрабатывая хранение токенов, проверку подписи и управление сроками жизни. В результате вы получаете готовый механизм с минимальными усилиями.

Пошаговое решение

Вы будете создавать клиентские приложения, генерировать персональные access‑токены, а также реализовать эндпоинт для обновления токенов. Для каждой операции используется простая маршрутизация, контроллеры и сервис‑классы. В процессе вы увидите, как Sanctum хранит токены в базе, как они защищены с помощью HMAC‑подписей, и как вы можете контролировать их срок действия. После завершения вы получите полностью функционирующий OAuth‑2.0 поток, готовый к использованию в мобильных и SPA‑приложениях.

рабочий код

// app/Http/Controllers/AuthController.php
use AppModelsUser;
use IlluminateHttpRequest;
use IlluminateFoundationAuthTokenGuard;

class AuthController extends Controller
{
    // Регистрация нового пользователя и выдача токена
    public function register(Request $request)
    {
        $validated = $request->validate([
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
            'password' => 'required|string|min:8|confirmed',
        ]);

        $user = User::create([
            'name' => $validated['name'],
            'email' => $validated['email'],
            'password' => bcrypt($validated['password']),
        ]);

        // Создаём персональный токен
        $token = $user->createToken('auth_token')->plainTextToken;

        return response()->json([
            'access_token' => $token,
            'token_type' => 'Bearer',
        ]);
    }

    // Переиздача токена при истечении срока действия (если включено Laravel Sanctum feature)
    public function refresh(Request $request)
    {
        // В Sanctum токены не имеют срока действия по умолчанию,
        // но можно реализовать собственный механизм, например, хранить expiration
        // в пользовательском поле и проверять его здесь.
        $user = $request->user();
        $newToken = $user->createToken('auth_token')->plainTextToken;
        return response()->json(['access_token' => $newToken]);
    }
}

типичные ошибки

• Не включён middleware ‘EnsureFrontendRequestsAreStateful’ → токен не хранится в куках.
• Отсутствует таблица personal_access_tokens → миграция не выполнена.
• Неправильные настройки CORS, из‑за чего запросы к API блокируются.

FAQ

1. Как защитить роуты от CSRF?

Sanctum использует куки для SPA – включите middleware VerifyCsrfToken и отправляйте XSRF-TOKEN.

2. Как обновить токен без логина?

Создайте эндпоинт, который генерирует новый токен и удаляет старый (user->tokens()->delete()).

3. Что делать, если токен не проходит проверку?

Убедитесь, что в request есть заголовок Authorization: Bearer <token> и что tokenGuard настроен в config/auth.php.

Заключение

К чек‑листу:

• Миграции выполнены, таблица personal_access_tokens существует.
• Middleware Sanctum и CORS настроены.
• Регистрация и выдача токенов работают.
• Тесты авторизации прошли.
• Документация для фронта готова.