Laravel Passport

Laravel Passport — это официальный пакет для фреймворка Laravel, предназначенный для реализации полной серверной реализации OAuth2.0. Он предоставляет механизмы для аутентификации API-запросов через токены доступа, позволяя разработчикам создавать защищённые интерфейсы для сторонних клиентов, мобильных приложений и одностраничных приложений (SPA). Passport является частью экосистемы Laravel и поддерживает все основные гранты (grant types) протокола OAuth2, включая авторизационный код, implicit grant, client credentials grant, password grant и personal access tokens.

История и контекст

Laravel Passport был впервые выпущен в 2016 году вместе с выходом Laravel 5.3. До этого момента встроенные средства аутентификации Laravel были ориентированы на традиционные сессионные веб-приложения, что создавало сложности для разработки API. Passport стал ответом на растущую потребность в безопасной аутентификации для мобильных и SPA-приложений, где использование сессий и cookies неудобно или невозможно.

В отличие от сторонних решений, таких как OAuth2 Server for PHP (The League of Extraordinary Packages), Passport предлагает более тесную интеграцию с Laravel: автоматическую миграцию базы данных, встроенные маршруты, middleware и Blade-шаблоны для управления токенами. В 2020 году, с выходом Laravel 8, была представлена альтернатива — Laravel Sanctum, более лёгкое решение для SPA и простых API. Однако Passport остаётся предпочтительным выбором для сложных систем, требующих полной реализации OAuth2.

Архитектура и компоненты

Модели и миграции

Passport использует несколько моделей Eloquent для хранения данных, связанных с OAuth2:

• Client — представляет зарегистрированное приложение (клиент), которое может запрашивать токены.
• Token — хранит выданные токены доступа, включая их срок действия и область видимости (scopes).
• AuthCode — используется в гранте авторизационного кода для временного хранения кода подтверждения.
• PersonalAccessClient — клиент, создаваемый для выдачи personal access tokens.

При установке Passport публикует миграции, которые создают соответствующие таблицы: oauth_clients, oauth_access_tokens, oauth_auth_codes, oauth_personal_access_clients и oauth_refresh_tokens.

Маршруты и middleware

Passport автоматически регистрирует маршруты для выдачи токенов (например, /oauth/token), их проверки, а также для управления клиентами через веб-интерфейс. Для защиты API-эндпоинтов используется middleware auth:api, который проверяет наличие и валидность токена.

Гранты (Grant Types)

Passport поддерживает все основные гранты OAuth2:

1. Authorization Code Grant — наиболее безопасный для сторонних приложений. Пользователь перенаправляется на сервер авторизации, где вводит логин/пароль, после чего получает код, который обменивается на токен.
2. Implicit Grant — упрощённая версия для SPA, где токен возвращается сразу после авторизации (без кода). В современных реализациях часто заменяется PKCE (Proof Key for Code Exchange).
3. Password Grant — пользователь передаёт логин/пароль напрямую клиенту, который обменивает их на токен. Используется в доверенных приложениях (например, мобильных).
4. Client Credentials Grant — для машинной аутентификации (сервер-сервер), без участия пользователя. Клиент получает токен на основе своих учётных данных (client_id и client_secret).
5. Personal Access Token — упрощённый механизм, при котором пользователь генерирует токен вручную через интерфейс и использует его для доступа к API.

Установка и настройка

Установка Passport в типичном проекте Laravel выполняется через Composer:

``bash composer require laravel/passport ``

После этого публикуются миграции и конфигурация:

``bash php artisan vendor:publish --tag=passport-migrations php artisan migrate ``

Далее генерируются ключи шифрования для токенов:

``bash php artisan passport:install ``

Эта команда создаёт клиент для выдачи personal access tokens и два клиента (для грантов авторизационного кода и password grant). В файле config/auth.php необходимо указать драйвер passport для API-аутентификации.

В модели User добавляется трейт Laravel\Passport\HasApiTokens, который предоставляет методы для управления токенами, такие как createToken(), tokenCan() и tokens().

Применение

Аутентификация API

Passport широко используется для защиты RESTful API в проектах, где требуется разграничение доступа между разными клиентами. Например, серверная часть мобильного приложения может использовать password grant для аутентификации пользователей, а сторонний сервис — client credentials grant для получения данных.

Управление областями видимости (Scopes)

Passport позволяет определять области видимости (scopes) — разрешения, которые могут быть запрошены при выдаче токена. Например, для социальной сети можно определить scopes read-posts, write-posts, read-profile. При запросе токена клиент указывает необходимые scopes, и API проверяет их при каждом запросе.

Одностраничные приложения (SPA)

Для SPA, работающих на одном домене с API, часто используется implicit grant или PKCE. Passport поддерживает оба варианта. В Laravel 8+ рекомендуется использовать Sanctum для SPA, но Passport также остаётся работоспособным решением.

Примеры использования

Выдача токена через password grant

```php use Illuminate\Support\Facades\Http;

$response = Http::post('http://your-app.com/oauth/token', [ 'grant_type' => 'password', 'client_id' => 'client-id', 'client_secret' => 'client-secret', 'username' => 'user@example.com', 'password' => 'user-password', 'scope' => '', ]);

return $response->json(); ```

Проверка токена в middleware

``php Route::middleware('auth:api')->get('/user', function (Request $request) { return $request->user(); }); ``

Создание personal access token

``php $user = User::find(1); $token = $user->createToken('MyApp')->accessToken; ``

Критика и ограничения

Несмотря на популярность, Passport подвергается критике за избыточность для простых проектов. Для небольших API или SPA, где не требуется полная реализация OAuth2, более лёгким решением является Laravel Sanctum. Кроме того, Passport требует хранения большого количества записей в базе данных (токены, коды, клиенты), что может замедлить работу при высоких нагрузках. Некоторые разработчики отмечают, что документация по Passport может быть неполной, особенно в части настройки PKCE и кастомных грантов.

Сравнение с альтернативами

Интересные факты

• Passport использует библиотеку league/oauth2-server под капотом, но предоставляет для неё удобную обёртку в стиле Laravel.
• Пакет поддерживает refresh-токены, которые позволяют обновлять токены доступа без повторного ввода учётных данных.
• В Laravel 11 Passport остаётся поддерживаемым, но для новых проектов рекомендуется оценить Sanctum, если не требуется полный OAuth2.

Источники

• Официальная документация Laravel: Laravel Passport
• Спецификация OAuth 2.0 (RFC 6749)
• Репозиторий пакета на GitHub: laravel/passport
• Статьи на Laravel News и Laravel Daily