Laravel Passport para PHP: guia completo do servidor OAuth2

1. O que é e para que serve

Laravel Passport é uma implementação completa de servidor OAuth2 para o framework Laravel (PHP). Ele fornece um conjunto pronto de ferramentas para criar autenticação de APIs, permitindo que desenvolvedores implementem rapidamente a proteção de suas APIs RESTful usando tokens de acesso (access tokens) e tokens de atualização (refresh tokens) padrão. A biblioteca é construída sobre o poderoso pacote League OAuth2 Server, adaptado ao ecossistema Laravel, incluindo migrations, facades, comandos Artisan e modelos Eloquent.

O principal objetivo do Passport é eliminar a necessidade de o desenvolvedor escrever manualmente a lógica complexa de geração, validação e armazenamento de tokens. Em vez disso, você obtém rotas prontas para emissão de tokens (através de grant types), middleware para proteger rotas e métodos convenientes para gerenciar clientes (aplicações) e tokens. O Passport é ideal para criar Single Page Applications (SPA), aplicativos móveis e clientes servidores que precisam de acesso seguro à sua API.

Por que usar o Passport em vez de uma solução própria? Primeiro, segurança: a biblioteca implementa todos os requisitos da especificação OAuth2, incluindo proteção contra CSRF, tratamento correto de escopos e PKCE (Proof Key for Code Exchange). Segundo, velocidade de desenvolvimento: você obtém migrations, modelos e controladores prontos. Terceiro, flexibilidade: o Passport suporta todos os principais grant types (authorization code, client credentials, password grant, personal access tokens) e é facilmente extensível para necessidades específicas.

2. Instalação

A instalação do Laravel Passport é feita via Composer, o gerenciador de pacotes padrão para PHP. Execute o seguinte comando na raiz do seu projeto Laravel:

composer require laravel/passport

Após instalar o pacote, é necessário executar as migrations e publicar a configuração. O Passport usa seu próprio sistema de migrations, que cria tabelas para armazenar clientes, tokens, códigos de autorização e tokens pessoais:

php artisan migrate

Em seguida, execute o comando passport:install, que criará as chaves de criptografia e os clientes para tokens pessoais e password grant:

php artisan passport:install

Após executar o comando, você verá no console dois client_id e client_secret. O primeiro é para tokens pessoais (Personal Access Client), o segundo para password grant (Password Grant Client). Salve-os no arquivo .env:

PASSPORT_PERSONAL_ACCESS_CLIENT_ID=1
PASSPORT_PERSONAL_ACCESS_CLIENT_SECRET=seu-segredo-aqui
PASSPORT_PASSWORD_GRANT_CLIENT_ID=2
PASSPORT_PASSWORD_GRANT_CLIENT_SECRET=seu-segredo-aqui

Em seguida, adicione o trait Laravel\Passport\HasApiTokens ao modelo User (app/Models/User.php):

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;

    protected $fillable = [
        'name', 'email', 'password',
    ];

    protected $hidden = [
        'password', 'remember_token',
    ];
}

No arquivo config/auth.php, altere o driver de autenticação para passport:

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

Por fim, no arquivo app/Providers/AuthServiceProvider.php, adicione a chamada Passport::routes() no método boot():

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\AuthServi