Если вы создаете API в Laravel, вы примете решение в первую неделю: Sanctum или Passport. Вопрос звучит как незначительный выбор пакета, но он требует более серьезного вопроса: кто использует этот API и насколько вам нужно доверять им? Если вы ошибетесь, вы потратите недели на подключение сервера OAuth2, о котором никто не просил, или отправите систему токенов, которая не сможет поддерживать сторонние интеграции, которые уже обещает ваша дорожная карта. В этом посте мы пропускаем краткое описание брошюры и сразу переходим к производственному решению: для чего на самом деле предназначен каждый пакет, в чем команды ошибаются в выборе и как перейти, если вы сделали неправильный выбор.

Что такое Санктум на самом деле

Laravel Sanctum — это облегченный пакет аутентификации для двух сценариев: «собственные» SPA или мобильные приложения — то есть вы контролируете как интерфейсную, так и внутреннюю часть — и простую выдачу токенов API для межмашинного использования. Sanctum не реализует OAuth2: нет сервера авторизации, нет экрана согласия, нет регистрации клиента. Он предоставляет вам два механизма: аутентификацию сеанса на основе файлов cookie с отслеживанием состояния для SPA в одном и том же домене верхнего уровня и таблицу  personal_access_tokens  для хешированных токенов, отправленных в виде заголовка Bearer.

В этой простоте и есть суть. Sanctum существует потому, что Passport был излишним в подавляющем большинстве ситуаций «наш собственный интерфейс взаимодействует с нашим собственным API». Если вы создаете React или Vue SPA на   app.yourcompany.com  , общаясь с   api.yourcompany.com   , или мобильное приложение, которое поставляет только ваша компания, Sanctum доставит вас туда практически без церемоний.

Что такое паспорт на самом деле

Laravel Passport — это полная реализация сервера OAuth2, построенная на пакете League OAuth2 Server: регистрация клиентов, коды авторизации, токены обновления, области действия и отзыв токенов, поддерживаемые собственной схемой. Passport существует по одной причине — позволяет приложениям, которые вы не контролируете, получать доступ к вашему API от имени пользователя с явным, отзывным согласием этого пользователя. Это другая проблема, чем «мой собственный SPA должен войти в систему». Это правильный инструмент, когда ваш API сам по себе является платформой, а не просто серверной частью для вашего собственного клиента.

SPA Cookie Auth против токенов API: выбор правильного режима Sanctum

Sanctum поддерживает два стиля аутентификации, и выбор неправильного создает реальные проблемы. Аутентификация SPA на основе файлов cookie предназначена для случаев, когда SPA и API используют один и тот же домен верхнего уровня. Laravel выдает зашифрованный файл cookie сеанса HttpOnly после входа в систему, а промежуточное программное обеспечение Sanctum  EnsureFrontendRequestsAreStateful  аутентифицирует запросы от настроенных доменов SPA через сеанс вместо токена — ни один токен не затрагивает ваш интерфейсный JavaScript, что значительно снижает поверхность атаки XSS.

Токены API предназначены для всего остального: мобильных приложений, инструментов CLI, межсерверной интеграции и любого клиента, который не является SPA на основе браузера, совместно использующего ваш домен файлов cookie. Ошибка, которую мы видим чаще всего, заключается в том, что команды используют токены API для своего собственного SPA, когда им это не нужно — это больше кода, токен должен жить где-то в браузере, и он ничего не дает вам по сравнению с аутентификацией на основе файлов cookie, когда интерфейс и серверная часть принадлежат вам и используют общий домен.

Собственные и сторонние потребители: реальная точка принятия решения

Если отбросить сравнения функций, решение сводится к одному вопросу: являются ли приложения, вызывающие ваш API, приложениями, которые вы создаете и развертываете, или приложениями, созданными другими людьми? Только собственные приложения, и Sanctum почти всегда прав — это касается большинства реальных проектов: собственное веб-приложение компании плюс ее собственные приложения для iOS/Android, внутренняя панель администратора, использующая внутренний API, продукт SaaS с единственным официальным клиентом.

Сторонние потребители, и вам нужен Passport (или эквивалентный сервер OAuth2). Это проявляется, когда вы создаете платформу с общедоступным API, с которым интегрируются другие компании, торговую площадку, где партнерские приложения действуют от имени пользователя, или любой продукт, где «Подключение вашей учетной записи» является реальной, обязательной функцией дорожной карты.

Код: Настройка аутентификации Sanctum SPA

 // config/sanctum.php
'stateful' => explode(',', env(
    'SANCTUM_STATEFUL_DOMAINS',
    'localhost,localhost:3000,app.yourcompany.com'
)),
'guard' => ['web'],

// bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
    $middleware->statefulApi();
})

// routes/api.php
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', fn (Request $request) => $request->user());
});
 

Ваш SPA нажимает   GET /sanctum/csrf-cookie   перед входом в систему, чтобы активировать защиту CSRF, а затем отправляет форму входа с  withCredentials: true  (Axios) или  credentials: 'include'  (fetch) при каждом запросе, поэтому файл cookie сеанса отправляется автоматически.

Код: Выдача токенов Sanctum API со способностями

 public function login(Request $request)
{
    $request->validate([
        'email' => 'required|email',
        'password' => 'required',
        'device_name' => 'required|string',
    ]);

    $user = User::where('email', $request->email)->first();

    if (! $user || ! Hash::check($request->password, $user->password)) {
        throw ValidationException::withMessages(['email' => ['Invalid credentials.']]);
    }

    $token = $user->createToken(
        $request->device_name,
        ['orders:read', 'orders:create', 'profile:read']
    );

    return response()->json(['token' => $token->plainTextToken]);
}
 

Обратите внимание, что значение в виде обычного текста доступно только во время создания — Sanctum хранит хеш SHA-256 в базе данных, поэтому рассматривайте этот ответ как единственный шанс, который клиент получает, чтобы его захватить.

Код: Настройка предоставления учетных данных клиента Passport

Для межмашинной интеграции, при которой серверная часть партнера проходит аутентификацию без участия пользователя: 

 // AuthServiceProvider.php
use Laravel\Passport\Passport;

public function boot(): void
{
    Passport::tokensCan([
        'reports:read' => 'Read partner reports',
        'orders:sync' => 'Sync order data',
    ]);
}

// routes/api.php
Route::middleware([
    'client',
    'scope:reports:read',
])->get('/partner/reports', [ReportController::class, 'index']);
 

Сервер партнера запрашивает токен напрямую, без перенаправления браузера, а Passport выдает токен, привязанный к этому клиенту и набору областей, который вы можете отозвать независимо, если интеграция будет прекращена.

Типы грантов OAuth2, поддерживаемые паспортом (и когда они вам действительно нужны)

Passport поддерживает полный набор стандартных грантов OAuth2, но большинству проектов требуется только один или два. Предоставление кода авторизации — это стандартный процесс для сторонних приложений, когда пользователь входит в систему и дает явное согласие — используйте вариант PKCE для общедоступных клиентов, которые не могут надежно хранить секрет. Предоставление пароля позволяет доверенному стороннему клиенту напрямую обменивать имя пользователя и пароль на токен; он соблазнителен своей простотой, но требует от клиента обработки необработанных учетных данных, что противоречит основной цели безопасности OAuth2 — его использование обычно означает, что вместо этого вам следует использовать Sanctum. Предоставление учетных данных клиента предназначено для межмашинной аутентификации без участия пользователя в цикле; Если это единственный грант, который нужен вашему проекту, сделайте паузу, прежде чем обращаться к Passport, поскольку токены API Sanctum служат той же цели «служебной учетной записи» с гораздо меньшими настройками.

Миграция между Sanctum и Passport

Оба пакета предоставляют модель аутентифицированного пользователя   User   и поддерживают проверки в стиле  tokenCan() , поэтому миграция между ними затрагивает меньше кода, чем люди ожидают — проблема почти полностью лежит на уровне аутентификации, а не в вашей бизнес-логике. Переход от Sanctum к Passport обычно означает установку Passport вместе с Sanctum, запуск  passport:install  для генерации ключей шифрования и регистрации ваших первых клиентов OAuth2, определение областей в  AuthServiceProvider , которые отражают ваши существующие возможности Sanctum, и построение потока кода авторизации только для новой поверхности. Переход от Passport к Sanctum обычно означает проверку того, какие клиенты OAuth2 на самом деле являются собственными, а какие внешними, замену потока кода авторизации прямой выдачей токенов Sanctum и удаление таблиц Passport  oauth_* , маршрутов и самого пакета.

Структура принятия решений

Разорвите дискуссию тремя вопросами, на которые честно ответьте о вашей реальной дорожной карте: будет ли приложению, которое вы не создаете и не контролируете, потребуется разрешение пользователя на доступ к вашему API? Каждый ли клиент — веб-, мобильный, CLI — разрабатывается вашей собственной командой? Вам нужен экран согласия, реестр клиентов или пользовательский интерфейс отзыва для внешних разработчиков? Чаще всего мы видим, что команды в первый же день обращаются к Passport, потому что «OAuth2» кажется правильным ответом, а затем тратят недели на поддержание сервера авторизации для продукта с одним собственным клиентом.

Sanctum и Passport не являются конкурирующими реализациями одной и той же функции — они решают разные проблемы доверия. Sanctum предполагает, что вы доверяете каждому клиенту, потому что вы его создали; Паспорт существует в тот момент, когда его нет. Большинство API Laravel, в том числе амбициозные, предназначены только для собственных разработчиков и должны оставаться в Sanctum до тех пор, пока это остается верным.

Если вы обдумываете это решение в реальном проекте и хотите получить второе мнение, прежде чем переходить к архитектуре, наша команда предлагает услуги по разработке API Laravel и может помочь правильно определить область действия уровня аутентификации, прежде чем вы будете основываться на неверном предположении.