Autenticação

A API valida JWTs emitidos pelo Keycloak usando JWKS (chaves públicas buscadas remotamente e cacheadas pela lib jose). Há dois middlewares distintos, montados por prefixo de rota no AppModule:

Fluxo de usuário final (/api/*)

Destinado a usuários humanos autenticados no realm do Keycloak. O middleware:

1. Extrai e verifica o JWT contra o JWKS do realm (KEYCLOAK_REALM_URL).
2. Lê o sub (Keycloak subject) do token.
3. Consulta o cache Redis (user_auth:<sub>, TTL de 5 min). Em hit, usa o usuário cacheado.
4. Em miss, resolve o usuário local via idIdentity = sub e carrega suas permissões (UMA) e a flag isSuperAdmin (role de realm super_admin).

req.user (tipo IUser) carrega, entre outros, o id do usuário local, suas permissions e isSuperAdmin — consumidos pelo PermissionGuard.

Fluxo app-to-app (/service/*)

Destinado a comunicação entre serviços usando client credentials do Keycloak. O middleware:

1. Verifica o JWT contra o JWKS de KEYCLOAK_AUTH_URL.
2. Lê o azp (authorized party = client_id que chamou, ex.: app1-tenant-xyz).
3. Resolve o tenant correspondente àquele client (via keycloakClientId), populando req.service com o contexto de serviço (tenantId, escopos).

Cache de autenticação

O contexto de usuário é cacheado no Redis por 5 minutos (USER_CACHE_TTL_SECONDS). Alterações de permissão no Keycloak podem levar até esse intervalo para refletir na API.