Laravel 10 OAuth‑2.0 с Sanctum: полное руководство

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

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

Вы хотите, чтобы ваш Laravel‑приложение могло выдавать токены, которые клиенты (веб‑приложения, мобильные приложения, сторонние сервисы) используют для доступа к защищённым эндпоинтам. Для этого необходимо:

1. установить Sanctum и настроить конфигурацию;
2. создать клиент‑приложения в базе данных;
3. реализовать эндпоинты для выдачи токенов;
4. обеспечить механизм обновления токенов (refresh token) для продления срока действия.

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

Шаг 1 – установка Sanctum. Запустите composer require laravel/sanctum, затем проверьте миграции и сгенерируйте таблицу clients. Шаг 2 – настройте middleware api, добавив IlluminateRoutingMiddlewareSubstituteBindings::class и LaravelSanctumHttpMiddlewareEnsureFrontendRequestsAreStateful::class, чтобы Sanctum распознавал запросы от SPA. Шаг 3 – создайте таблицу personal_access_tokens и убедитесь, что она хранит токены в виде хешей. Шаг 4 – реализуйте контроллер, который при POST /oauth/token принимает client_id, client_secret, grant_type, scope и выдаёт access_token и optional refresh_token. Шаг 5 – добавьте эндпоинт /oauth/token/refresh, который принимает refresh_token, валидирует его, генерирует новый access_token и обновляет срок действия. Шаг 6 – настройте middleware auth:sanctum на защищённых маршрутах, чтобы они проверяли наличие валидного access_token. Шаг 7 – протестируйте с помощью Postman или cURL, убедившись, что токен выдаётся, сохраняется и обновляется по мере необходимости. При правильной настройке Sanctum обеспечивает простую и надёжную OAuth‑2.0 аутентификацию, позволяя быстро и безопасно масштабировать ваш API.

Рабочий код

get('/user', function () {
    return auth()->user();
});

// app/Http/Controllers/AuthController.php
namespace AppHttpControllers;
use AppModelsUser;
use IlluminateHttpRequest;
use IlluminateSupportFacadesHash;

class AuthController extends Controller
{
    public function login(Request $request)
    {
        $request->validate([
            'email' => 'required|email',
            'password' => 'required',
        ]);

        $user = User::where('email', $request->email)->first();
        if (! $user || ! Hash::check($request->password, $user->password)) {
            return response()->json(['message' => 'Unauthorized'], 401);
        }

        // Создаём токен с ограничением (scopes) если нужно
        $token = $user->createToken('api-token', ['*'])->plainTextToken;
        return response()->json(['token' => $token]);
    }
}

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

• Не включён middleware ‘sanctum’ в api.php – без него токен не будет проверяться.
• Отсутствует пакет sanctum: composer require laravel/sanctum и публикация конфигурации.
• Неправильная настройка guards в config/auth.php – убедитесь, что guard ‘sanctum’ использует driver ‘sanctum’.
• Кеширование конфигурации без очистки: php artisan config:clear после изменений.

FAQ

1. Как обновить токен?

В Sanctum нет встроенного refresh‑token. Нужно вручную создать новый токен и удалить старый: $user->tokens()->where(‘id’, $oldId)->delete();

2. Можно ли использовать OAuth2 вместе с Sanctum?

Да, Sanctum может хранить personal access tokens, а OAuth2 реализовать через пакет Laravel Passport. Но для простых API лучше использовать только один.

3. Почему при запросе 401, но токен выглядит корректным?

Проверьте, что токен передаётся в заголовке Authorization: Bearer {token}. Также убедитесь, что токен не просрочен и не удалён.

Заключение и чек‑лист

• Установлен Laravel 10 и пакет sanctum.
• Публикуется конфигурация и миграции.
• В routes/api.php подключены маршруты и middleware sanctum.
• В контроллере реализован login и выдача токена.
• Проверяется правильность guards и кеша.
• Тестируется запрос с токеном через Postman.