Acapadev SDK
Sincronização de Sessão (Single Logout)
Apesar do Acapadev SDK disponibilizar webhooks que enviam notificações em tempo real quando um utilizador encerra a sessão centralmente, os webhooks podem falhar (falhas de rede, servidor em baixo, etc.). Para uma segurança absoluta ("Zero Trust"), o SDK fornece o middleware EnsureAcapadevSession.
O Que Faz?
Sempre que um utilizador autenticado tentar abrir uma página protegida da tua aplicação, o middleware vai contactar invisivelmente o Acapadev ID (via Facade Acapadev, no endpoint /users/{id}/status) para garantir que a conta dele continua ativa e a sessão não expirou. Para não deixar a tua aplicação lenta, a resposta desta validação é mantida em cache durante 5 minutos (300 segundos).
Como Utilizar
Regista o middleware no ficheiro bootstrap/app.php (no Laravel 11+), criando um alias:
->withMiddleware(function (Middleware $middleware) {
$middleware->alias([
'acapadev.session' => \Acapadev\Sdk\Http\Middleware\EnsureAcapadevSession::class,
]);
})Depois, protege as tuas rotas principais aplicando este middleware, geralmente logo a seguir ao middleware auth:
Route::middleware(['auth', 'acapadev.session'])->group(function () {
Route::get('/dashboard', [DashboardController::class, 'index']);
});Se o middleware detetar que o utilizador foi banido ou fez logout na central, ele força o encerramento da sessão local (Auth::logout(), invalidação da sessão e regeneração do token CSRF) e redireciona o utilizador para a página de login.
Utilizadores não autenticados (guests) passam diretamente pelo middleware sem qualquer chamada à API — só há verificação para sessões autenticadas.
Comportamento em Caso de Indisponibilidade da API
Se a chamada ao Acapadev ID falhar (timeout, servidor em baixo), o middleware assume fail-open: considera a sessão válida temporariamente para não bloquear todos os utilizadores durante uma pequena indisponibilidade da central. Combina este middleware com os webhooks (para reatividade imediata) em vez de depender só de um dos dois mecanismos.
Webhooks vs. Middleware — Quando Usar Cada Um
| Mecanismo | Latência | Fiabilidade |
|---|---|---|
Evento WebhookReceived | Quase imediata (assíncrona) | Depende de entrega de rede — pode falhar |
Middleware EnsureAcapadevSession | Até 5 minutos (cache) | Rede de segurança síncrona, sempre corre no pedido |
Usar os dois mecanismos em conjunto garante que a tua aplicação nunca fica com uma sessão local "presa" a um utilizador já desativado na central, mesmo que um webhook se perca.