Pular para o conteúdo principal

Proteja sua API Laravel com RBAC (controle de acesso baseado em papel) e validação de JWT

Este guia irá ajudá-lo a implementar autorização para proteger suas APIs Laravel usando controle de acesso baseado em papel (RBAC) e JSON Web Tokens (JWTs) emitidos pelo Logto.

Antes de começar​

Seus aplicativos cliente precisam obter tokens de acesso (Access tokens) do Logto. Se você ainda não configurou a integração do cliente, confira nossos Guias rápidos para React, Vue, Angular ou outros frameworks de cliente, ou veja nosso Guia máquina para máquina para acesso servidor a servidor.

Este guia foca na validação no lado do servidor desses tokens em seu aplicativo Laravel.

Uma figura mostrando o foco deste guia

O que você vai aprender​

  • Validação de JWT: Aprenda a validar tokens de acesso (Access tokens) e extrair informações de autenticação (Authentication)
  • Implementação de middleware: Crie middleware reutilizável para proteção de API
  • Modelos de permissão: Entenda e implemente diferentes padrões de autorização (Authorization):
    • Recursos de API globais para endpoints de aplicação
    • Permissões de organização para controle de funcionalidades específicas do locatário
    • Recursos de API em nível de organização para acesso a dados multi-inquilino
  • Integração com RBAC: Implemente permissões e escopos baseados em papel (Role-based access control (RBAC)) em seus endpoints de API

Pré-requisitos​

  • Última versão estável do PHP instalada
  • Compreensão básica de Laravel e desenvolvimento de API web
  • Um aplicativo Logto configurado (veja Guias rápidos se necessário)

Visão geral dos modelos de permissão​

Antes de implementar a proteção, escolha o modelo de permissão que se encaixa na arquitetura do seu aplicativo. Isso está alinhado com os três principais cenários de autorização do Logto:

RBAC de recursos globais de API
  • Caso de uso: Proteger recursos de API compartilhados em todo o seu aplicativo (não específicos de organização)
  • Tipo de token: Token de acesso (Access token) com público global (global audience)
  • Exemplos: APIs públicas, serviços principais do produto, endpoints de administração
  • Melhor para: Produtos SaaS com APIs usadas por todos os clientes, microsserviços sem isolamento de locatário
  • Saiba mais: Proteger recursos globais de API

💡 Escolha seu modelo antes de prosseguir – a implementação fará referência à abordagem escolhida ao longo deste guia.

Passos rápidos de preparação​

Configure recursos e permissões do Logto​

  1. Criar recurso de API: Vá para Console → Recursos de API e registre sua API (ex: https://api.seuapp.com)
  2. Definir permissões: Adicione escopos como read:products, write:orders – veja Definir recursos de API com permissões
  3. Criar papéis globais: Vá para Console → Papéis e crie papéis que incluam as permissões da sua API – veja Configurar papéis globais
  4. Atribuir papéis: Atribua papéis a usuários ou aplicativos M2M que precisam de acesso à API
Novo no RBAC?:

Comece com nosso guia de controle de acesso baseado em papel para instruções passo a passo de configuração.

Atualize seu aplicativo cliente​

Solicite os escopos apropriados em seu cliente:

O processo geralmente envolve atualizar a configuração do seu cliente para incluir um ou mais dos seguintes:

  • Parâmetro scope nos fluxos OAuth
  • Parâmetro resource para acesso a recursos de API
  • organization_id para contexto de organização
Antes de codificar:

Certifique-se de que o usuário ou app M2M que você está testando recebeu os papéis ou papéis de organização adequados que incluam as permissões necessárias para sua API.

Inicialize seu projeto de API​

Para inicializar um novo projeto Laravel, você pode usar o instalador do Laravel ou o Composer:

Usando o instalador do Laravel (recomendado):

composer global require laravel/installer
laravel new seu-nome-da-api
cd seu-nome-da-api

Ou usando o Composer diretamente:

composer create-project laravel/laravel seu-nome-da-api
cd seu-nome-da-api

Inicie o servidor de desenvolvimento:

php artisan serve

Isso criará uma estrutura básica de projeto Laravel. Para desenvolvimento de API, talvez você queira remover alguns middlewares e rotas específicas da web:

bootstrap/app.php
<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        // Configure o middleware da API conforme necessário
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();
nota:

Consulte a documentação do Laravel para mais detalhes sobre como configurar controllers, middlewares e outros recursos.

Inicialize constantes e utilitários​

Defina as constantes e utilitários necessários em seu código para lidar com a extração e validação do token. Uma solicitação válida deve incluir um cabeçalho Authorization no formato Bearer <token de acesso (access token)>.

AuthConstants.php
<?php

class AuthConstants
{
    public const JWKS_URI = 'https://your-tenant.logto.app/oidc/jwks';
    public const ISSUER = 'https://your-tenant.logto.app/oidc';
}
AuthInfo.php
<?php

class AuthInfo
{
    public function __construct(
        public readonly string $sub,
        public readonly ?string $clientId = null,
        public readonly ?string $organizationId = null,
        public readonly array $scopes = [],
        public readonly array $audience = []
    ) {}

    public function toArray(): array
    {
        return [
            'sub' => $this->sub,
            'client_id' => $this->clientId,
            'organization_id' => $this->organizationId,
            'scopes' => $this->scopes,
            'audience' => $this->audience,
        ];
    }
}
AuthorizationException.php
<?php

class AuthorizationException extends Exception
{
    public function __construct(
        string $message,
        public readonly int $statusCode = 403
    ) {
        parent::__construct($message);
    }
}
AuthHelpers.php
<?php

trait AuthHelpers
{
    protected function extractBearerToken(array $headers): string
    {
        $authorization = $headers['authorization'][0] ?? $headers['Authorization'][0] ?? null;

        if (!$authorization) {
            throw new AuthorizationException('O cabeçalho de autorização está ausente (Authorization header is missing)', 401);
        }

        if (!str_starts_with($authorization, 'Bearer ')) {
            throw new AuthorizationException('O cabeçalho de autorização deve começar com "Bearer " (Authorization header must start with "Bearer ")', 401);
        }

        return substr($authorization, 7); // Remove o prefixo 'Bearer ' (Remove 'Bearer ' prefix)
    }
}

Recupere informações sobre seu tenant Logto​

Você precisará dos seguintes valores para validar tokens emitidos pelo Logto:

  • URI do JSON Web Key Set (JWKS): A URL para as chaves públicas do Logto, usada para verificar assinaturas de JWT.
  • Emissor (Issuer): O valor esperado do emissor (URL OIDC do Logto).

Primeiro, encontre o endpoint do seu tenant Logto. Você pode encontrá-lo em vários lugares:

  • No Logto Console, em Configurações → Domínios.
  • Em qualquer configuração de aplicativo onde você configurou no Logto, Configurações → Endpoints & Credenciais.

Buscar no endpoint de descoberta do OpenID Connect​

Esses valores podem ser obtidos no endpoint de descoberta do OpenID Connect do Logto:

https://<seu-endpoint-logto>/oidc/.well-known/openid-configuration

Aqui está um exemplo de resposta (outros campos omitidos para brevidade):

{
  "jwks_uri": "https://your-tenant.logto.app/oidc/jwks",
  "issuer": "https://your-tenant.logto.app/oidc"
}

Como o Logto não permite personalizar o URI do JWKS ou o emissor, você pode definir esses valores manualmente no seu código. No entanto, isso não é recomendado para aplicações em produção, pois pode aumentar a sobrecarga de manutenção caso alguma configuração mude no futuro.

  • URI do JWKS: https://<seu-endpoint-logto>/oidc/jwks
  • Emissor: https://<seu-endpoint-logto>/oidc

Valide o token e as permissões​

Após extrair o token e buscar a configuração OIDC, valide o seguinte:

  • Assinatura: O JWT deve ser válido e assinado pelo Logto (via JWKS).
  • Emissor (Issuer): Deve corresponder ao emissor do seu tenant Logto.
  • Público (Audience): Deve corresponder ao indicador de recurso da API registrado no Logto, ou ao contexto da organização se aplicável.
  • Expiração: O token não pode estar expirado.
  • Permissões (escopos) (Permissions (scopes)): O token deve incluir os escopos necessários para sua API / ação. Os escopos são strings separadas por espaço na reivindicação scope.
  • Contexto da organização: Se estiver protegendo recursos de API em nível de organização, valide a reivindicação organization_id.

Veja JSON Web Token para saber mais sobre a estrutura e reivindicações do JWT.

O que verificar para cada modelo de permissão​

As reivindicações e regras de validação diferem conforme o modelo de permissão:

  • Reivindicação de público (aud): Indicador de recurso de API
  • Reivindicação de organização (organization_id): Não presente
  • Escopos (permissões) a verificar (scope): Permissões do recurso de API

Para permissões de organização que não são de API, o contexto da organização é representado pela reivindicação aud (por exemplo, urn:logto:organization:abc123). A reivindicação organization_id só está presente para tokens de recursos de API em nível de organização.
dica:

Sempre valide tanto as permissões (escopos) quanto o contexto (público, organização) para APIs multi-tenant seguras.

Adicione a lógica de validação​

Usamos firebase/php-jwt para validar JWTs. Instale-o usando o Composer:

composer require firebase/php-jwt

Primeiro, adicione estas utilidades compartilhadas para lidar com a validação de JWT:

JwtValidator.php
<?php

use Firebase\JWT\JWT;
use Firebase\JWT\JWK;
use Firebase\JWT\Key;

class JwtValidator
{
    use AuthHelpers;

    private static ?array $jwks = null;

    public static function fetchJwks(): array
    {
        if (self::$jwks === null) {
            $jwksData = file_get_contents(AuthConstants::JWKS_URI);
            if ($jwksData === false) {
                throw new AuthorizationException('Falha ao buscar JWKS', 401);
            }

            self::$jwks = json_decode($jwksData, true);
        }

        return self::$jwks;
    }

    public static function validateJwt(string $token): array
    {
        try {
            $jwks = self::fetchJwks();
            $keys = JWK::parseKeySet($jwks);

            $decoded = JWT::decode($token, $keys);
            $payload = (array) $decoded;

            // Verificar emissor
            if (($payload['iss'] ?? '') !== AuthConstants::ISSUER) {
                throw new AuthorizationException('Emissor inválido', 401);
            }

            self::verifyPayload($payload);
            return $payload;

        } catch (AuthorizationException $e) {
            throw $e;
        } catch (Exception $e) {
            throw new AuthorizationException('Token inválido: ' . $e->getMessage(), 401);
        }
    }

    public static function createAuthInfo(array $payload): AuthInfo
    {
        $scopes = !empty($payload['scope']) ? explode(' ', $payload['scope']) : [];
        $audience = $payload['aud'] ?? [];

        if (is_string($audience)) {
            $audience = [$audience];
        }

        return new AuthInfo(
            sub: $payload['sub'],
            clientId: $payload['client_id'] ?? null,
            organizationId: $payload['organization_id'] ?? null,
            scopes: $scopes,
            audience: $audience
        );
    }

    private static function verifyPayload(array $payload): void
    {
        // Implemente sua lógica de verificação aqui com base no modelo de permissão
        // Isso será mostrado na seção de modelos de permissão abaixo
    }
}

Em seguida, implemente o middleware para verificar o token de acesso:

app/Http/Middleware/VerifyAccessToken.php
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class VerifyAccessToken
{
    use AuthHelpers;

    public function handle(Request $request, Closure $next): Response
    {
        try {
            $token = $this->extractBearerToken($request->headers->all());
            $payload = JwtValidator::validateJwt($token);

            // Armazene as informações de autenticação nos atributos da requisição para uso genérico
            $request->attributes->set('auth', JwtValidator::createAuthInfo($payload));

            return $next($request);

        } catch (AuthorizationException $e) {
            return response()->json(['error' => $e->getMessage()], $e->statusCode);
        }
    }
}

Registre o middleware em app/Http/Kernel.php:

app/Http/Kernel.php
protected $middlewareAliases = [
    // ... outros middlewares
    'auth.token' => \App\Http\Middleware\VerifyAccessToken::class,
];

De acordo com seu modelo de permissão, implemente a lógica de verificação apropriada em JwtValidator:

JwtValidator.php
private static function verifyPayload(array $payload): void
{
    // Verifique se a reivindicação de público corresponde ao seu indicador de recurso de API
    $audiences = $payload['aud'] ?? [];
    if (is_string($audiences)) {
        $audiences = [$audiences];
    }

    if (!in_array('https://your-api-resource-indicator', $audiences)) {
        throw new AuthorizationException('Público inválido');
    }

    // Verifique os escopos necessários para recursos globais de API
    $requiredScopes = ['api:read', 'api:write']; // Substitua pelos escopos realmente necessários
    $scopes = !empty($payload['scope']) ? explode(' ', $payload['scope']) : [];

    foreach ($requiredScopes as $scope) {
        if (!in_array($scope, $scopes)) {
            throw new AuthorizationException('Escopo insuficiente');
        }
    }
}

Aplique o middleware à sua API​

Agora, aplique o middleware às suas rotas de API protegidas.

routes/api.php
<?php

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::middleware('auth.token')->group(function () {
    Route::get('/api/protected', function (Request $request) {
        // Acesse as informações de autenticação a partir dos atributos da requisição
        $auth = $request->attributes->get('auth');
        return ['auth' => $auth->toArray()];
    });
});

Ou usando controllers:

app/Http/Controllers/Api/ProtectedController.php
<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;

class ProtectedController extends Controller
{
    public function __construct()
    {
        $this->middleware('auth.token');
    }

    public function index(Request $request)
    {
        // Acesse as informações de autenticação a partir dos atributos da requisição
        $auth = $request->attributes->get('auth');
        return ['auth' => $auth->toArray()];
    }

    public function show(Request $request)
    {
        // Sua lógica de endpoint protegido
        $auth = $request->attributes->get('auth');
        return [
            'auth' => $auth->toArray(),
            'message' => 'Dados protegidos acessados com sucesso'
        ];
    }
}

Teste sua API protegida​

Obter tokens de acesso (Access tokens)​

Do seu aplicativo cliente: Se você configurou uma integração de cliente, seu aplicativo pode obter tokens automaticamente. Extraia o token de acesso e use-o nas requisições de API.

Para testes com curl / Postman:

  1. Tokens de usuário: Use as ferramentas de desenvolvedor do seu aplicativo cliente para copiar o token de acesso do localStorage ou da aba de rede.

  2. Tokens máquina para máquina: Use o fluxo de credenciais do cliente. Aqui está um exemplo não normativo usando curl:

    curl -X POST https://your-tenant.logto.app/oidc/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials" \
      -d "client_id=your-m2m-client-id" \
      -d "client_secret=your-m2m-client-secret" \
      -d "resource=https://your-api-resource-indicator" \
      -d "scope=api:read api:write"

    Pode ser necessário ajustar os parâmetros resource e scope de acordo com seu recurso de API e permissões; um parâmetro organization_id também pode ser exigido se sua API for voltada para organização.

dica:

Precisa inspecionar o conteúdo do token? Use nosso decodificador de JWT para decodificar e verificar seus JWTs.

Testar endpoints protegidos​

Requisição com token válido
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://localhost:3000/api/protected

Resposta esperada:

{
  "auth": {
    "sub": "user123",
    "clientId": "app456",
    "organizationId": "org789",
    "scopes": ["api:read", "api:write"],
    "audience": ["https://your-api-resource-indicator"]
  }
}
Token ausente
curl http://localhost:3000/api/protected

Resposta esperada (401):

{
  "error": "Authorization header is missing"
}
Token inválido
curl -H "Authorization: Bearer invalid-token" \
  http://localhost:3000/api/protected

Resposta esperada (401):

{
  "error": "Invalid token"
}

Testes específicos do modelo de permissão​

Cenários de teste para APIs protegidas com escopos globais:

  • Escopos válidos: Teste com tokens que incluam os escopos de API necessários (por exemplo, api:read, api:write)
  • Escopos ausentes: Espere 403 Proibido quando o token não tiver os escopos necessários
  • Público errado: Espere 403 Proibido quando o público não corresponder ao recurso de API
# Token sem escopos necessários - espera-se 403
curl -H "Authorization: Bearer token-without-required-scopes" \
  http://localhost:3000/api/protected

Leitura adicional​

RBAC na prática: Implementando autorização segura para seu aplicativo

Construa um aplicativo SaaS multi-inquilino: Um guia completo do design à implementação