Laravel Passport for PHP: Complete Guide to OAuth2 Server

\n\n

1. What It Is and Why You Need It

\n\n

Laravel Passport is a full-featured OAuth2 server implementation for the Laravel framework (PHP). It provides a ready-made set of tools for creating API authentication, allowing developers to quickly implement protection for their RESTful APIs using standard access tokens and refresh tokens. The library is built on top of the powerful League OAuth2 Server package, which is adapted to the Laravel ecosystem, including migrations, facades, Artisan commands, and Eloquent models.

\n\n

The main goal of Passport is to relieve the developer from having to write complex logic for generating, verifying, and storing tokens manually. Instead, you get ready-made routes for issuing tokens (via grant types), middleware for protecting routes, and convenient methods for managing clients (applications) and tokens. Passport is ideal for building Single Page Applications (SPAs), mobile applications, and server-side clients that require secure access to your API.

\n\n

Why use Passport instead of a custom solution? First, security: the library implements all requirements of the OAuth2 specification, including CSRF protection, proper scope handling, and PKCE (Proof Key for Code Exchange). Second, development speed: you get ready-made migrations, models, and controllers. Third, flexibility: Passport supports all major grant types (authorization code, client credentials, password grant, personal access tokens) and can be easily extended for specific needs.

\n\n

2. Installation

\n\n

Installing Laravel Passport is done via Composer, the standard package manager for PHP. Run the following command in the root of your Laravel project:

\n\n

composer require laravel/passport

\n\n

After installing the package, you need to run migrations and publish the configuration. Passport uses its own migration system, which creates tables for storing clients, tokens, authorization codes, and personal access tokens:

\n\n

php artisan migrate

\n\n

Then run the passport:install command, which will create encryption keys and clients for personal access tokens and password grant:

\n\n

php artisan passport:install

\n\n

After running the command, you will see two client_id and client_secret values in the console. The first is for Personal Access Client, the second for Password Grant Client. Save them to the .env file:

\n\n

PASSPORT_PERSONAL_ACCESS_CLIENT_ID=1\nPASSPORT_PERSONAL_ACCESS_CLIENT_SECRET=your-secret-here\nPASSPORT_PASSWORD_GRANT_CLIENT_ID=2\nPASSPORT_PASSWORD_GRANT_CLIENT_SECRET=your-secret-here

\n\n

Next, add the Laravel\\Passport\\HasApiTokens trait to the User model (app/Models/User.php):

\n\n

<?php\n\nnamespace App\\Models;\n\nuse Illuminate\\Foundation\\Auth\\User as Authenticatable;\nuse Illuminate\\Notifications\\Notifiable;\nuse Laravel\\Passport\\HasApiTokens;\n\nclass User extends Authenticatable\n{\n    use HasApiTokens, Notifiable;\n\n    protected $fillable = [\n        'name', 'email', 'password',\n    ];\n\n    protected $hidden = [\n        'password', 'remember_token',\n    ];\n}

\n\n

In the config/auth.php file, change the authentication driver to passport:

\n\n

'guards' => [\n    'api' => [\n        'driver' => 'passport',\n        'provider' => 'users',\n    ],\n],

\n\n

Finally, in the app/Providers/AuthServiceProvider.php file, add the Passport::routes() call in the boot() method:

\n\n

<?php\n\nna