QuanthumSingle Sign-On · Documentação

Quanthum SSO

Provedor central de identidade do ecossistema Quanthum: um único lugar para criar contas, autenticar pessoas (senha, e-mail de confirmação e TOTP) e entregar a identidade às aplicações por OpenID Connect.

1. Visão geral

O Quanthum SSO é um Identity Provider (IdP) baseado em Laravel 13, PHP 8.3 e MySQL. Ele autentica a pessoa uma única vez, mantém uma sessão central e emite tokens para cada aplicação que a pessoa usa. As aplicações não guardam senha: elas delegam o login ao SSO e recebem de volta uma identidade verificável.

O que o SSO fazCadastro e ciclo de vida de contas, login com risco adaptativo, MFA TOTP, sessões, provedor OIDC, API de administração e trilha de auditoria.
O que o SSO não fazPapéis, permissões, licenciamento e dados de negócio. Isso continua em cada sistema consumidor, que usa o sub como chave externa.
Quem usaPessoas (telas de login, MFA, sessões), aplicações (protocolo OIDC) e operadores (API de controle, consumida pelo Quanthum Services).
ItemValor
Issuer (produção)https://sso.quanthum.tec.br (sem barra final, imutável)
Perfil OIDCquanthum-oidc-profile 1.0
StackLaravel 13, PHP 8.3, MySQL, Laravel Passport (OIDC), Laravel Sanctum (API), Blade
PublicaçãoDokploy + Nixpacks; Traefik (TLS) na frente do Nginx do contêiner
Identificador de usuáriosub opaco (ULID). O e-mail pode mudar e nunca é chave de relacionamento.

2. Arquitetura

O SSO expõe três superfícies independentes sobre o mesmo banco e a mesma base de código:

                       +--------------------------------------------+
  Pessoa (navegador) ->|  Telas web: /login /register /mfa /sessions |
                       |  Sessão central (cookie, MFA, step-up)      |
                       +--------------------------------------------+
  Aplicação (OIDC)   ->|  Provedor OIDC: /oauth/* e discovery        |
                       +--------------------------------------------+
  Services / operador->|  API de controle: /api/v1/admin, /api/v1/me |
                       +--------------------------------------------+
                                        |
                        MySQL (usuários, sessões, tokens, auditoria)
                                        |
             Worker (fila database) + Scheduler (publicação/retenção)

Componentes

ComponenteResponsabilidade
Telas web (Blade)Login, cadastro por intenção, verificação de e-mail, recuperação de senha, MFA, sessões reconhecidas, troca de e-mail e consentimento OIDC.
Provedor OIDCDiscovery, autorização, token, JWKS, UserInfo, revogação e logout. Laravel Passport com extensões próprias (perfil restrito, RS256, refresh rotacionado).
API de controleAdministração de usuários, organizações, aplicações, solicitações de integração e clients; autoatendimento do usuário; consulta de auditoria.
Serviços de domínioRiskEngine, TrustedContextService, EmailChallengeService, MfaService/TotpService, AuthSessionService, IntegrationWorkflowService, OidcClientManagementService, ApplicationAccessService, SecurityAuditService.
Workerqueue:work processa e-mails e a publicação da auditoria (fila em banco).
Schedulerschedule:work dispara publicação do outbox de auditoria, retenção, limpeza de intenções expiradas, tokens e chaves de idempotência.

Sem worker e scheduler o SSO funciona pela metade. Os e-mails (verificação, código de acesso, redefinição) e a publicação da auditoria dependem da fila. Em produção são três serviços a partir da mesma imagem: aplicação web, worker e scheduler.

Modelo de dados (entidades principais)

GrupoModelos
IdentidadeUser, UserProfile, UserDocument (CPF/CNPJ cifrado com blind index), RegistrationIntent, EmailChangeRequest
SegurançaUserMfaMethod, RecoveryCode, LoginChallenge, TrustedContext, AuthSession
GovernançaOrganization, Application, ApplicationPolicy, ApplicationUserAccess, IntegrationRequest, IntegrationRequestTransition
OIDCOidcClient, ClientRedirectUri, OidcAuthCode e as tabelas de tokens do Passport
APIApiConsumer, SelfApiIdentity, tokens Sanctum, ApiIdempotencyKey
AuditoriaAuditEvent, OutboxEvent, SecurityAuditEvent

3. Conceitos e glossário

TermoSignificado
IdP / RPO SSO é o Identity Provider; cada aplicação que delega o login é uma Relying Party.
subIdentificador estável e opaco da pessoa. Aplicações persistem issuer + sub com restrição de unicidade.
ApplicationProduto cadastrado no SSO (ex.: qai), com categoria, política de registro e estágio de homologação.
Client OIDCCredencial técnica (client_id + secret) de uma aplicação em um ambiente.
Integration requestSolicitação que percorre o workflow de homologação de uma aplicação.
Contexto confiávelCombinação dispositivo/navegador/rede previamente confirmada por um segundo fator, lembrada por cookie.
Step-upExigência de confirmação adicional (código por e-mail e/ou TOTP) quando o acesso é novo ou arriscado.
ApiConsumerIdentidade de máquina (ex.: Quanthum Services) dona dos tokens da API de controle, exclusiva por ambiente.
amrMétodos de autenticação usados: pwd, email, otp.

4. Contas e cadastro

Ciclo de vida

pending_verification --(e-mail verificado)--> active <--(reativar)-- suspended
        ^                                        |                        ^
        +----------(reativar conta nova)---------+------(suspender)-------+
  • pending_verification: conta criada; não conclui OIDC até verificar o e-mail.
  • active: pode autenticar e obter tokens.
  • suspended: incrementa a auth_version (as sessões centrais deixam de valer), bloqueia login e novas autorizações e leva à tela de conta suspensa. A suspensão sozinha não revoga tokens OIDC já emitidos; para isso use a revogação global (seção 8).

Cadastro por intenção (registration intent)

O cadastro público é desligado por padrão (SELF_REGISTRATION_ENABLED=false). Uma conta nasce de uma intenção de uso único, com token aleatório guardado apenas como hash e validade curta (60 minutos por padrão):

OrigemComo é emitida
Serviços (provisionamento)POST /api/v1/admin/users com users:manage; devolve registration_url para a pessoa abrir.
Plataforma MundoPOST /api/v1/registration-intents com self:register; devolve a URL de cadastro.
AutoatendimentoPOST /register/intent, só quando o cadastro público estiver habilitado.

A aplicação pode restringir a origem permitida por registration policy (open, intent, invitation, administrative, disabled). Com disabled, não envie application_id ao criar o convite.

Regras de cadastro

  • O e-mail é normalizado; se a intenção já vem com e-mail, ele não pode ser trocado na tela.
  • A senha é gravada com Argon2id. CPF/CNPJ (opcional) é cifrado e consultável só por blind index.
  • Ao concluir o cadastro, um e-mail de verificação é enviado (link assinado, 30 minutos). A conta só vira active depois do clique.
  • A senha nunca trafega por API: o SSO rejeita campos de senha, TOTP e recuperação vindos dos consumidores.

Recuperação de senha e troca de e-mail

  • Recuperação: /forgot-password responde igual exista ou não a conta (anti-enumeração) e envia link de uso único.
  • Troca de e-mail: exige autenticação recente e senha; o novo endereço recebe a confirmação e o antigo é avisado.

5. Autenticação e login

O login web é o mesmo para acesso direto ao SSO e para o início de um fluxo OIDC (quando o fluxo chega sem sessão, o destino é lembrado e retomado depois do login).

  1. A pessoa envia e-mail e senha em POST /login. O limite é de 8 tentativas por minuto por IP e 5 por conta.
  2. O SSO compara a senha (com hash de mesmo custo mesmo se a conta não existir) e responde de forma genérica em caso de falha.
  3. Conta suspensa: redireciona para /account/suspended.
  4. E-mail ainda não verificado: abre a sessão mínima e leva a /verify-email.
  5. O motor de risco avalia o contexto (seção seguinte).
    • Risco alto ou contexto novo: step-up por e-mail (/step-up/email).
    • Risco baixo e conta com TOTP: desafio TOTP (/step-up/totp).
    • Risco baixo e sem TOTP: login concluído.
  6. Login concluído: a sessão é regenerada, um registro AuthSession é criado e, se aplicável, o contexto confiável é renovado.

6. Risco, contexto e step-up

A cada login o RiskEngine soma pontos por sinais de risco e compara com o limiar (AUTH_RISK_THRESHOLD, padrão 40). Um contexto nunca visto sempre exige step-up.

SinalVariávelPadrãoQuando conta
untrusted_contextAUTH_RISK_UNTRUSTED_CONTEXT50Sem cookie de contexto confiável válido
network_changeAUTH_RISK_NETWORK_CHANGE10Rede (/24 IPv4) diferente da do contexto
user_agent_changeAUTH_RISK_USER_AGENT_CHANGE15Navegador/dispositivo diferente
application_changeAUTH_RISK_APPLICATION_CHANGE10Origem (aplicação) diferente
region_changeAUTH_RISK_REGION_CHANGE20Região geográfica diferente (só com cabeçalhos de geolocalização habilitados)
stale_authenticationAUTH_RISK_STALE_AUTHENTICATION30Última confirmação forte há mais de 30 dias
recent_failureAUTH_RISK_RECENT_FAILURE5 por falha (máx. 5)Falhas de login nos últimos 30 minutos

Mudança normal de IP é um sinal, não um bloqueio isolado: sozinha ela não ultrapassa o limiar.

Contexto confiável

Depois de uma confirmação forte, o SSO grava um TrustedContext (hash do token, rede, hash do user-agent) e entrega um cookie (quanthum_trusted_context, Secure, HttpOnly). Ele expira por inatividade em TRUSTED_CONTEXT_IDLE_DAYS (90 dias) e é renovado a cada uso.

Código por e-mail

ParâmetroPadrão
Formato6 dígitos, uso único, guardado só como hash
Validade10 minutos (EMAIL_CHALLENGE_TTL_MINUTES)
ReenvioIntervalo mínimo de 60 segundos
TentativasMáximo de 5 por desafio

O desafio é amarrado ao contexto do navegador: um código obtido em outro dispositivo não vale.

7. MFA (TOTP)

  • Voluntário: cada pessoa ativa em /mfa. A preparação mostra o secret uma única vez; a ativação só ocorre após confirmar um código válido.
  • Secret cifrado em repouso; janela de tolerância de ±1 passo (TOTP_WINDOW); reuso de um código já aceito é rejeitado (replay).
  • Códigos de recuperação: gerados em lote, guardados como hash, de uso único; regenerar invalida o lote anterior.
  • Remover o TOTP ou regenerar códigos exige a senha atual.
  • Reset administrativo pela API (mfa:reset): exige justificativa e é auditado com alta severidade; o administrador nunca vê o secret.

8. Sessões

Cada login gera uma AuthSession vinculada ao ID da sessão do navegador, com o rótulo do dispositivo e a auth_version do usuário.

  • Em cada requisição autenticada, o middleware recognized.session confere se a sessão existe, não foi revogada e tem a mesma auth_version do usuário; senão, faz logout.
  • Sessões reconhecidas (/sessions): a pessoa vê e revoga uma sessão ou todas.
  • Revogação global (sessions:revoke ou “Revogar todos os acessos”) incrementa a auth_version e, na mesma transação, invalida sessões, contextos confiáveis e desafios pendentes, apaga as sessões do navegador e revoga os access/refresh tokens OIDC e os tokens de API do usuário.
  • Cookie de sessão: Secure, HttpOnly, SameSite=Lax, criptografado, armazenado em banco.

9. Provedor OIDC

O SSO implementa um perfil restrito do OpenID Connect: apenas o fluxo Authorization Code com PKCE. Não existem implicit, password, client credentials, device code nem tokens pessoais.

Endpoints

FunçãoEndpointMétodo
Discovery/.well-known/openid-configurationGET
Authorization/oauth/authorizeGET (aprovar: POST, negar: DELETE)
Token/oauth/tokenPOST
JWKS/oauth/jwksGET
UserInfo/oauth/userinfoGET / POST (Bearer)
Revogação (RFC 7009)/oauth/revokePOST
Logout (RP-Initiated)/oauth/logoutGET / POST

As aplicações devem descobrir endpoints e JWKS pelo discovery e configurar apenas o issuer.

Capacidades anunciadas

Campo do discoveryValor
response_types_supportedcode
grant_types_supportedauthorization_code, refresh_token
id_token_signing_alg_values_supportedRS256
code_challenge_methods_supportedS256
scopes_supportedopenid, profile, email
token_endpoint_auth_methods_supportedclient_secret_basic, client_secret_post, none (público)

Regras para autorizar (gates)

  1. Requisição válida no perfil: response_type=code, nonce e PKCE S256 obrigatórios.
  2. redirect_uri idêntica, byte a byte, a uma URI cadastrada no client (sem curinga).
  3. Aplicação com status active e homologated_at preenchido.
  4. Client não suspenso e do mesmo ambiente do servidor (OIDC_ENVIRONMENT). O SSO de produção só aceita clients production.
  5. Pessoa autenticada (senão vai ao login), conta ativa e e-mail verificado.
  6. Aplicação exclusive: o usuário precisa de vínculo ativo e a organização precisa estar ativa e ligada ao produto.

Consentimento

Por padrão o SSO mostra a tela de autorização com os escopos pedidos. Se o client for confiável (trusted=true) e os escopos estiverem dentro de openid profile email, o consentimento é transparente e a pessoa volta direto à aplicação. Escopos já concedidos antes também dispensam a tela.

10. Fluxo Authorization Code + PKCE

Pessoa      Aplicação (backend)        Quanthum SSO
  |  clica "Entrar"   |                          |
  |------------------>| gera state, nonce,       |
  |                   | code_verifier/challenge  |
  |<-- 302 -----------|                          |
  |--------------- GET /oauth/authorize?... ----->|
  |                   |      (login, step-up se necessário, consentimento)
  |<-------------- 302 redirect_uri?code&state ---|
  |------------------>| valida state             |
  |                   |-- POST /oauth/token ----->|  (code + code_verifier + client auth)
  |                   |<-- id_token, access, refresh
  |                   | valida id_token (JWKS)   |
  |<-- sessão local --|  chave externa: issuer + sub

1) Redirecionar para a autorização

GET https://sso.quanthum.tec.br/oauth/authorize
  ?response_type=code
  &client_id=<client_id>
  &redirect_uri=https://app.exemplo.com/auth/callback
  &scope=openid%20profile%20email
  &state=<aleatorio>
  &nonce=<aleatorio>
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256

2) Trocar o código por tokens (backend)

curl -X POST https://sso.quanthum.tec.br/oauth/token \
  -H "Authorization: Basic $(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 -w0)" \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d redirect_uri=https://app.exemplo.com/auth/callback \
  -d code_verifier=<code_verifier>

A autenticação do client é HTTP Basic (client_secret_basic): base64(client_id:client_secret), com as credenciais vindas de variáveis de ambiente. Também é aceito client_secret_post (campos no corpo). Resposta: access_token, refresh_token, id_token e expires_in (Cache-Control: no-store). Clients públicos enviam client_id sem secret.

3) Validar o id_token (obrigatório)

  • Assinatura RS256 com a chave do JWKS escolhida pelo kid; recusar alg=none e HS*.
  • iss igual ao issuer configurado; aud igual ao seu client_id; azp quando presente.
  • exp, iat e tolerância de relógio pequena; nonce igual ao enviado.
  • Criar a sessão local usando issuer + sub como chave externa.

4) Renovar (refresh)

curl -X POST https://sso.quanthum.tec.br/oauth/token \
  -H "Authorization: Basic $(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 -w0)" \
  -d grant_type=refresh_token -d refresh_token=<refresh_token>

O refresh token é rotacionado a cada uso. Reutilizar um refresh já consumido é tratado como incidente: a família inteira é revogada e o evento OIDC.TOKEN.REFRESH.REUSE_DETECTED é registrado.

Por que o “Autorizar” não reagia? O Chrome aplica a política form-action do CSP a toda a cadeia de redirects de um formulário. O SSO acrescenta ao form-action apenas a origem de uma redirect_uri exatamente cadastrada, nas telas do fluxo; fora dele continua 'self'.

11. Tokens, claims e escopos

TokenValidade (padrão)Observação
Authorization code60 s (OIDC_AUTHORIZATION_CODE_TTL_SECONDS)Uso único; amarrado ao PKCE e ao client
Access token5 min (OIDC_ACCESS_TOKEN_TTL_MINUTES)Usado no UserInfo
ID token5 min (OIDC_ID_TOKEN_TTL_MINUTES)JWT RS256
Refresh token30 dias (OIDC_REFRESH_TOKEN_TTL_DAYS)Rotacionado; reuso revoga a família

Escopos e claims

EscopoClaims
openidsub, iss, aud, exp, iat, auth_time, nonce, amr
profilename, locale (quando disponíveis)
emailemail, email_verified

CPF/CNPJ, organizações, papéis, permissões e licenças não fazem parte do perfil padrão. Mudanças aditivas e opcionais não quebram o perfil; mudanças semânticas criam nova versão do perfil.

amr (métodos de autenticação)

  • pwd: senha. email: código por e-mail (step-up). otp: TOTP.
  • Aplicações que exigem segundo fator devem checar o amr. Veja as limitações na seção final.

12. Logout e revogação

RP-Initiated Logout

GET|POST /oauth/logout exige id_token_hint (assinado por uma chave do JWKS, com iss e aud corretos) e, se enviado, post_logout_redirect_uri idêntica a uma URI cadastrada. O SSO revoga os tokens do usuário naquele client, encerra a sessão central se for a mesma pessoa e redireciona, devolvendo state quando informado.

Revogação de token

POST /oauth/revoke segue a RFC 7009 e nunca revela se o token existia. Suspender um client revoga os tokens dele; suspender ou rejeitar uma aplicação revoga todos os seus clients. Para um usuário, use a revogação global (seção 8), que revoga os tokens emitidos.

Boas práticas na aplicação

  • Logout local sempre; chamar o SSO quando houver id_token ainda utilizável.
  • Tratar invalid_grant, usuário suspenso e indisponibilidade sem laços de redirecionamento.

13. Chaves e JWKS

  • Assinatura RS256. Par de chaves em PASSPORT_PRIVATE_KEY / PASSPORT_PUBLIC_KEY (secrets do ambiente, nunca no Git) e OIDC_KEY_ID (kid ativo).
  • /oauth/jwks publica a chave ativa e, durante a troca, as chaves em aposentadoria (OIDC_RETIRING_PUBLIC_KEYS, entradas kid:caminho).
  • Rotação normal: gerar novo par e novo kid, publicar a pública nova antes de assinar com ela, manter a antiga até expirar o último token.
  • Chave comprometida: remover a privada, ativar novo par, revogar tokens e publicar só chaves públicas.
  • As aplicações devem atualizar o JWKS por kid e tolerar a sobreposição.

14. Aplicações e homologação

Categorias e política

CategoriaRegra
ecosystem_standardProduto padrão do ecossistema. Não exige vínculo usuário×organização.
exclusiveExige requires_user_assignment=true, vínculo ativo do usuário e organização ativa ligada ao produto.
externalAplicação de terceiros; consentimento explícito quando os dados ultrapassarem o perfil básico.

Workflow da solicitação de integração

draft -> submitted -> security_review -> sandbox -> homologated -> active
                  \-> rejected        \-> rejected     \-> security_review
homologated | active -> suspended
suspended -> security_review | sandbox | homologated | active | rejected
rejected -> draft
  • Não se pulam etapas: de draft não se vai direto a sandbox.
  • rejected e suspended exigem reason; ambos revogam todos os clients da aplicação.
  • homologated grava homologated_at; active torna a aplicação active.

Ambientes e estágio exigido para emitir client

Ambiente do clientEstágio mínimo
sandboxsandbox, homologated ou active
homologationhomologated ou active
productionactive

As credenciais nunca atravessam ambientes. Cada servidor só autentica clients do seu OIDC_ENVIRONMENT; um client de homologação não funciona no SSO de produção.

URIs do client

  • Exatas; HTTPS obrigatório (em sandbox/homologação também http://localhost, 127.0.0.1 e [::1]).
  • Sem *, sem fragmento (#), sem usuário/senha, sem duplicatas; ao menos uma redirect_uri.
  • Esquemas nativos (customizados) apenas para plataformas mobile e desktop.
  • Mudar redirect, tipo de client ou tratamento de tokens exige nova revisão.

Tipos de client e secret

  • confidential (web com backend): o secret é exibido uma única vez, na criação ou rotação, e armazenado só como hash. Rotacionar revoga os tokens do client.
  • public (SPA, mobile, desktop): sem secret; PKCE obrigatório; tokens só em memória/keychain.

15. API de controle

Base: https://sso.quanthum.tec.br/api/v1. Privada, consumida pelo Quanthum Services e por operadores. Contrato OpenAPI 3.1 versionado no repositório (docs/openapi/sso-api-v1.json).

Autenticação

  • Authorization: Bearer <token>. O token Sanctum pertence a um ApiConsumer (slug + ambiente) e carrega abilities.
  • O consumidor só vale no ambiente igual a API_CONSUMER_ENVIRONMENT do servidor; senão 403 Invalid API consumer.
  • Tokens expiram (30 dias por padrão). Emissão, rotação e revogação são comandos Artisan (não há endpoint que emita token).
php artisan api-token:issue <consumidor> production --name="Postman" \
  --abilities=applications:read,applications:manage,integrations:approve,users:read,users:manage
php artisan api-token:rotate <consumidor> production --abilities=...
php artisan api-token:revoke <consumidor> production

Abilities

AbilityLibera
users:read / users:manageListar/consultar; criar convite, editar, suspender/ativar, link de redefinição de senha
applications:read / applications:manageAplicações, organizações, clients (criar, rotacionar, suspender/ativar, trocar URIs)
integrations:approveTransições do workflow de integração
sessions:revoke, mfa:resetRevogar todas as sessões de um usuário; resetar MFA (com justificativa)
audit:readConsultar auditoria e diagnóstico
self:registerCriar intenção de cadastro (Plataforma Mundo)
self:read|update|email|mfa|sessionsAutoatendimento do próprio usuário (token curto, 15 min)

Endpoints principais

Método e rotaFunção
GET|POST /admin/usersListar (filtros status, email) / criar convite (devolve registration_url)
POST /admin/users/{user}/suspend|activateSuspender / reativar
POST /admin/users/{user}/password-reset-linkGerar redefinição de senha
POST /admin/users/{user}/sessions/revoke-allRevogação global
POST /admin/users/{user}/mfa/resetReset de MFA
GET|POST|PATCH /admin/applicationsAplicações
GET /admin/integration-requests (filtro application_id), GET /admin/integration-requests/{id}Listar / detalhar solicitações de integração
POST /admin/applications/{app}/integration-requestsCriar a solicitação (draft); 409 se já houver uma aberta
POST /admin/integration-requests/{id}/transitionAvançar o workflow (status, reason)
GET /admin/clients, POST /admin/applications/{app}/clientsListar / emitir client
POST /admin/clients/{client}/rotate-secret|suspend|activateRotacionar secret / suspender / ativar
PUT /admin/clients/{client}/redirect-urisSubstituir URIs
GET /admin/audit, /audit/{id}, /audit/diagnosticsConsultar auditoria
GET|PATCH /me, /me/sessions, /me/mfa/totpAutoatendimento
GET /statusStatus técnico público

Idempotência, correlação e erros

  • Idempotency-Key é obrigatório em criações e comandos críticos. O SSO vincula chave, consumidor, rota e SHA-256 do corpo por 24 h. Repetição idêntica devolve a resposta guardada (Idempotency-Replayed: true); corpo diferente com a mesma chave dá 409.
  • X-Correlation-ID (UUID) é preservado ou gerado e aparece nos erros e na auditoria.
  • Erros seguem application/problem+json com correlation_id: 401 (token), 403 (ability ou consumidor), 404, 409 (idempotência), 422 (validação, transição, URI, estágio), 429 (limite).
  • Listas usam paginação por cursor (limit 1–100, padrão 25).

Fronteira segura. Senha, segredo TOTP e códigos de recuperação nunca são aceitos nem retransmitidos pela API. As ações de MFA do autoatendimento devolvem apenas uma action_url no domínio do SSO.

16. Integrando uma aplicação (passo a passo)

  1. Criar a aplicação — POST /admin/applications (name, slug, category, registration_policy, requires_user_assignment, trusted_consent).
  2. Criar a solicitação de integração — POST /admin/applications/{application}/integration-requests (status inicial draft; 409 se já existe uma aberta).
  3. Percorrer o workflow — submitted → security_review → sandbox → homologated → active com POST .../transition (uma chamada por etapa, cada uma com Idempotency-Key nova).
  4. Emitir o client do ambiente do servidor (production no SSO de produção) com as URIs exatas. Copiar client.id e secret na hora.
  5. Configurar a aplicação: issuer, client_id, client_secret, redirect_uri e post_logout_redirect_uri como variáveis de ambiente (nunca no Git).
  6. Testar o checklist abaixo e só então ativar para os usuários.

Checklist de homologação

  • Login novo e com sessão SSO existente; usuário sem conta local tratado.
  • PKCE ausente/incorreto, state/nonce errados e redirect_uri parecida ou com curinga são rejeitados.
  • Assinatura, iss, aud e exp inválidos rejeitados.
  • Refresh, rotação e reutilização; logout local e global; usuário e aplicação suspensos.
  • Logs sem tokens ou segredos; indisponibilidade do SSO não derruba o login local.

Regras por plataforma

PlataformaRegra
Web com backendClient confidencial; secret só no backend; tokens no servidor; cookie de sessão Secure/HttpOnly.
SPAPreferir BFF; sem BFF, client público com PKCE e token de acesso só em memória. Nunca refresh token em localStorage.
Mobile / DesktopNavegador do sistema (nunca WebView); PKCE; refresh no keychain/keystore; redirect por app link ou loopback registrado.

17. Auditoria e observabilidade

  • Cada evento relevante (login, falha, MFA, step-up, emissão/revogação de tokens, mudança de aplicação, cliente ou token de API) é gravado na mesma transação da ação, com código semântico (ex.: AUTH.LOGIN.SUCCEEDED, OIDC.TOKEN.REVOKED, INTEGRATION.STATUS.CHANGED, OIDC.CLIENT.SECRET.ROTATED).
  • Categorias: AUTH (autenticação), OIDC (IAM), ADMIN/APPLICATION/INTEGRATION (configuração), SECURITY (detecção).
  • Outbox: cada evento gera um item de saída publicado pelo scheduler, a cada minuto, no canal de log audit em NDJSON no formato ECS, pronto para Wazuh/SIEM.
  • Redaction: metadados passam por um redator antes de gravar; nunca entram senha, TOTP, códigos, tokens, cookies, chaves ou CPF/CNPJ. O IP é guardado como hash.
  • Retenção: 90 dias (AUDIT_RETENTION_DAYS); limpeza diária às 02:30 em lotes.
  • Consulta por API (audit:read) com filtros por código (inclusive *), resultado, severidade mínima, usuário, correlation ID e período; /admin/audit/diagnostics informa retenção, volume, severidade recente e estado do outbox.

Saúde

EndpointUso
GET /upLiveness (processo de pé).
GET /up/readyReadiness: testa banco e cache e verifica atraso do outbox. 200 ready, 503 quando degradado ou sem dependência.
GET /api/v1/statusStatus técnico público (nome, estado, horário).

18. Modelo de segurança

ControleComo funciona
SenhasArgon2id; comparação de tempo constante; sem enumeração de contas.
Segundo fatorStep-up por e-mail em contexto novo/arriscado; TOTP voluntário; recuperação por códigos de uso único.
Segredos em repousoTOTP e CPF/CNPJ cifrados; tokens, códigos e secrets de client guardados como hash.
Rate limitingPor IP e por conta: login 8/min (IP) e 5/min (conta); token 30/min (IP) e 20/min (client); step-up 8/min (IP) e 6/min (usuário); MFA 6/min; cadastro 10/h; recuperação de senha 6/h por IP e 3/h por e-mail; troca de e-mail 5/h; verificação 2/min.
CabeçalhosCSP (default-src 'self', script-src 'self', frame-ancestors 'none'), HSTS, X-Content-Type-Options, Referrer-Policy: no-referrer, Permissions-Policy, COOP.
CSRF e cookiesCSRF em todos os formulários; cookies Secure, HttpOnly, SameSite=Lax.
ProxyConfiança em proxy somente pelos CIDRs explícitos de TRUSTED_PROXIES; sem isso o IP real do cliente é perdido.
OIDCPKCE S256 e nonce obrigatórios, redirects exatos, RS256 com kid, refresh rotacionado com detecção de reuso, sem grants inseguros.
AmbientesClient e token de API presos ao ambiente do servidor.
PrivacidadeClaims mínimos; consentimento explícito para aplicações externas; dados pessoais fora de logs.

19. Operação e deploy

Processos (mesma imagem)

ServiçoComandoObservação
Webgerado pelo Nixpacks (PHP-FPM + Nginx)Health /up, readiness /up/ready
Workerphp artisan queue:work --sleep=3 --tries=3 --timeout=90 --max-time=36001 réplica; sem domínio
Schedulerphp artisan schedule:work1 réplica; sem domínio

Release

php artisan deploy:build   # migrate --force, caches (config, rotas, views, eventos) e queue:restart
php artisan deploy:build --skip-cache

O build do Nixpacks fixa o Node 22 (nixpacks.toml) e roda composer install e npm run build. As migrations não rodam sozinhas: use o deploy:build no terminal do contêiner web a cada release.

Tarefas agendadas

TarefaFrequência
Publicar outbox de auditoriaa cada minuto
Expurgar auditoria além da retençãodiária, 02:30
Limpar intenções de identidade expiradasdiária
Podar tokens Sanctum expirados, jobs falhos e chaves de idempotênciadiária

Variáveis de ambiente principais

GrupoVariáveis
AplicaçãoAPP_ENV, APP_URL, APP_KEY, APP_DEBUG=false
OIDCOIDC_ENVIRONMENT, OIDC_ISSUER, OIDC_KEY_ID, PASSPORT_PRIVATE_KEY, PASSPORT_PUBLIC_KEY, TTLs, OIDC_RETIRING_PUBLIC_KEYS
APIAPI_CONSUMER_ENVIRONMENT, API_ADMIN_TOKEN_TTL_MINUTES, API_SELF_TOKEN_TTL_MINUTES
SegurançaDOCUMENT_BLIND_INDEX_KEY (diferente de APP_KEY), limiares de risco, TRUSTED_PROXIES, TRUSTED_CONTEXT_*
Banco e filaDB_* (MySQL), SESSION_DRIVER=database, QUEUE_CONNECTION=database, CACHE_STORE=database
E-mailMAIL_* (SMTP), MAIL_FROM_ADDRESS, MAIL_EHLO_DOMAIN
AuditoriaAUDIT_RETENTION_DAYS, AUDIT_EXPORT_BATCH_SIZE, AUDIT_STALE_MINUTES

Segredos (chaves, senhas, tokens) ficam apenas nas variáveis do Dokploy. O arquivo .env.dokploy do repositório é só referência com placeholders.

20. Solução de problemas

SintomaCausa provávelAção
403 The application is not active and homologatedAplicação ainda não está active, ou client suspensoAvançar o workflow até active; verificar o client
403 The client credential belongs to another environmentClient de outro ambiente (ex.: homologation no SSO de produção)Criar client do ambiente do servidor
Tela de autorização “não reage” e depois 403 auth token ... differentRedirect final bloqueado por CSP form-action (corrigido) ou clique duploAtualizar o SSO; marcar o client como confiável para pular a tela
Cai em /verify-email sem ter sessãoRota de autorização sem auth (corrigido)Atualizar o SSO
Código de acesso não chegaWorker parado ou SMTP incorretoSubir o worker; conferir MAIL_*; ver fila de jobs
422 Transition from X to Y is not allowedEtapa pulada ou já executadaSeguir a ordem do workflow
403 Invalid API consumerAmbiente do token diferente de API_CONSUMER_ENVIRONMENTReemitir o token com o ambiente correto
409 na APIIdempotency-Key repetida com corpo diferenteGerar chave nova
IP do usuário aparece sempre o mesmoTRUSTED_PROXIES vazioInformar o CIDR da rede do Traefik
/up/ready devolve 503Banco/cache indisponível ou outbox atrasadoVer banco e scheduler; consultar /admin/audit/diagnostics
Timeout ao conectar no MySQLFirewall do servidor do bancoLiberar a porta só para o IP do servidor do SSO

21. Limitações conhecidas

  • amr=otp ainda não é emitido. O SSO registra pwd e email, mas o valor otp depende de um ajuste pendente. Aplicações que exigem segundo fator por amr devem usar o login local até a correção.
  • Logout com id_token_hint expirado é recusado (HTTP 400). Como o id_token vale poucos minutos, o logout pelo SSO costuma ser apenas local na aplicação.
  • Device Authorization Grant está desabilitado no perfil 1.0; clientes de linha de comando não são suportados.
  • O domínio do SSO não tem dashboard: ele serve telas de identidade, não um painel administrativo (a administração é feita pela API, via Quanthum Services).

Documentação complementar no repositório: docs/modules/sso-architecture.md, docs/modules/sso-integration-guide.md, docs/pages/api-v1-control-plane.md, docs/pages/oidc-provider.md, docs/operations/sso-runbooks.md e o OpenAPI em docs/openapi/sso-api-v1.json.