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.
sub como chave externa.| Item | Valor |
|---|---|
| Issuer (produção) | https://sso.quanthum.tec.br (sem barra final, imutável) |
| Perfil OIDC | quanthum-oidc-profile 1.0 |
| Stack | Laravel 13, PHP 8.3, MySQL, Laravel Passport (OIDC), Laravel Sanctum (API), Blade |
| Publicação | Dokploy + Nixpacks; Traefik (TLS) na frente do Nginx do contêiner |
| Identificador de usuário | sub 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
| Componente | Responsabilidade |
|---|---|
| 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 OIDC | Discovery, autorização, token, JWKS, UserInfo, revogação e logout. Laravel Passport com extensões próprias (perfil restrito, RS256, refresh rotacionado). |
| API de controle | Administraçã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ínio | RiskEngine, TrustedContextService, EmailChallengeService, MfaService/TotpService, AuthSessionService, IntegrationWorkflowService, OidcClientManagementService, ApplicationAccessService, SecurityAuditService. |
| Worker | queue:work processa e-mails e a publicação da auditoria (fila em banco). |
| Scheduler | schedule: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)
| Grupo | Modelos |
|---|---|
| Identidade | User, UserProfile, UserDocument (CPF/CNPJ cifrado com blind index), RegistrationIntent, EmailChangeRequest |
| Segurança | UserMfaMethod, RecoveryCode, LoginChallenge, TrustedContext, AuthSession |
| Governança | Organization, Application, ApplicationPolicy, ApplicationUserAccess, IntegrationRequest, IntegrationRequestTransition |
| OIDC | OidcClient, ClientRedirectUri, OidcAuthCode e as tabelas de tokens do Passport |
| API | ApiConsumer, SelfApiIdentity, tokens Sanctum, ApiIdempotencyKey |
| Auditoria | AuditEvent, OutboxEvent, SecurityAuditEvent |
3. Conceitos e glossário
| Termo | Significado |
|---|---|
| IdP / RP | O SSO é o Identity Provider; cada aplicação que delega o login é uma Relying Party. |
sub | Identificador estável e opaco da pessoa. Aplicações persistem issuer + sub com restrição de unicidade. |
| Application | Produto cadastrado no SSO (ex.: qai), com categoria, política de registro e estágio de homologação. |
| Client OIDC | Credencial técnica (client_id + secret) de uma aplicação em um ambiente. |
| Integration request | Solicitação que percorre o workflow de homologação de uma aplicação. |
| Contexto confiável | Combinação dispositivo/navegador/rede previamente confirmada por um segundo fator, lembrada por cookie. |
| Step-up | Exigência de confirmação adicional (código por e-mail e/ou TOTP) quando o acesso é novo ou arriscado. |
| ApiConsumer | Identidade de máquina (ex.: Quanthum Services) dona dos tokens da API de controle, exclusiva por ambiente. |
amr | Mé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):
| Origem | Como é emitida |
|---|---|
| Serviços (provisionamento) | POST /api/v1/admin/users com users:manage; devolve registration_url para a pessoa abrir. |
| Plataforma Mundo | POST /api/v1/registration-intents com self:register; devolve a URL de cadastro. |
| Autoatendimento | POST /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
activedepois 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-passwordresponde 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).
- A pessoa envia e-mail e senha em
POST /login. O limite é de 8 tentativas por minuto por IP e 5 por conta. - 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.
- Conta suspensa: redireciona para
/account/suspended. - E-mail ainda não verificado: abre a sessão mínima e leva a
/verify-email. - 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.
- Risco alto ou contexto novo: step-up por e-mail (
- 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.
| Sinal | Variável | Padrão | Quando conta |
|---|---|---|---|
| untrusted_context | AUTH_RISK_UNTRUSTED_CONTEXT | 50 | Sem cookie de contexto confiável válido |
| network_change | AUTH_RISK_NETWORK_CHANGE | 10 | Rede (/24 IPv4) diferente da do contexto |
| user_agent_change | AUTH_RISK_USER_AGENT_CHANGE | 15 | Navegador/dispositivo diferente |
| application_change | AUTH_RISK_APPLICATION_CHANGE | 10 | Origem (aplicação) diferente |
| region_change | AUTH_RISK_REGION_CHANGE | 20 | Região geográfica diferente (só com cabeçalhos de geolocalização habilitados) |
| stale_authentication | AUTH_RISK_STALE_AUTHENTICATION | 30 | Última confirmação forte há mais de 30 dias |
| recent_failure | AUTH_RISK_RECENT_FAILURE | 5 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âmetro | Padrão |
|---|---|
| Formato | 6 dígitos, uso único, guardado só como hash |
| Validade | 10 minutos (EMAIL_CHALLENGE_TTL_MINUTES) |
| Reenvio | Intervalo mínimo de 60 segundos |
| Tentativas | Má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.sessionconfere se a sessão existe, não foi revogada e tem a mesmaauth_versiondo usuário; senão, faz logout. - Sessões reconhecidas (
/sessions): a pessoa vê e revoga uma sessão ou todas. - Revogação global (
sessions:revokeou “Revogar todos os acessos”) incrementa aauth_versione, 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ção | Endpoint | Método |
|---|---|---|
| Discovery | /.well-known/openid-configuration | GET |
| Authorization | /oauth/authorize | GET (aprovar: POST, negar: DELETE) |
| Token | /oauth/token | POST |
| JWKS | /oauth/jwks | GET |
| UserInfo | /oauth/userinfo | GET / POST (Bearer) |
| Revogação (RFC 7009) | /oauth/revoke | POST |
| Logout (RP-Initiated) | /oauth/logout | GET / POST |
As aplicações devem descobrir endpoints e JWKS pelo discovery e configurar apenas o issuer.
Capacidades anunciadas
| Campo do discovery | Valor |
|---|---|
response_types_supported | code |
grant_types_supported | authorization_code, refresh_token |
id_token_signing_alg_values_supported | RS256 |
code_challenge_methods_supported | S256 |
scopes_supported | openid, profile, email |
token_endpoint_auth_methods_supported | client_secret_basic, client_secret_post, none (público) |
Regras para autorizar (gates)
- Requisição válida no perfil:
response_type=code,noncee PKCES256obrigatórios. redirect_uriidêntica, byte a byte, a uma URI cadastrada no client (sem curinga).- Aplicação com status
activeehomologated_atpreenchido. - Client não suspenso e do mesmo ambiente do servidor (
OIDC_ENVIRONMENT). O SSO de produção só aceita clientsproduction. - Pessoa autenticada (senão vai ao login), conta ativa e e-mail verificado.
- 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; recusaralg=nonee HS*. issigual ao issuer configurado;audigual ao seuclient_id;azpquando presente.exp,iate tolerância de relógio pequena;nonceigual ao enviado.- Criar a sessão local usando
issuer + subcomo 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
| Token | Validade (padrão) | Observação |
|---|---|---|
| Authorization code | 60 s (OIDC_AUTHORIZATION_CODE_TTL_SECONDS) | Uso único; amarrado ao PKCE e ao client |
| Access token | 5 min (OIDC_ACCESS_TOKEN_TTL_MINUTES) | Usado no UserInfo |
| ID token | 5 min (OIDC_ID_TOKEN_TTL_MINUTES) | JWT RS256 |
| Refresh token | 30 dias (OIDC_REFRESH_TOKEN_TTL_DAYS) | Rotacionado; reuso revoga a família |
Escopos e claims
| Escopo | Claims |
|---|---|
openid | sub, iss, aud, exp, iat, auth_time, nonce, amr |
profile | name, locale (quando disponíveis) |
email | email, 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_tokenainda 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) eOIDC_KEY_ID(kidativo). /oauth/jwkspublica a chave ativa e, durante a troca, as chaves em aposentadoria (OIDC_RETIRING_PUBLIC_KEYS, entradaskid: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
kide tolerar a sobreposição.
14. Aplicações e homologação
Categorias e política
| Categoria | Regra |
|---|---|
ecosystem_standard | Produto padrão do ecossistema. Não exige vínculo usuário×organização. |
exclusive | Exige requires_user_assignment=true, vínculo ativo do usuário e organização ativa ligada ao produto. |
external | Aplicaçã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
draftnão se vai direto asandbox. rejectedesuspendedexigemreason; ambos revogam todos os clients da aplicação.homologatedgravahomologated_at;activetorna a aplicaçãoactive.
Ambientes e estágio exigido para emitir client
| Ambiente do client | Estágio mínimo |
|---|---|
sandbox | sandbox, homologated ou active |
homologation | homologated ou active |
production | active |
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.1e[::1]). - Sem
*, sem fragmento (#), sem usuário/senha, sem duplicatas; ao menos umaredirect_uri. - Esquemas nativos (customizados) apenas para plataformas
mobileedesktop. - 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 umApiConsumer(slug + ambiente) e carrega abilities.- O consumidor só vale no ambiente igual a
API_CONSUMER_ENVIRONMENTdo servidor; senão403 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
| Ability | Libera |
|---|---|
users:read / users:manage | Listar/consultar; criar convite, editar, suspender/ativar, link de redefinição de senha |
applications:read / applications:manage | Aplicações, organizações, clients (criar, rotacionar, suspender/ativar, trocar URIs) |
integrations:approve | Transições do workflow de integração |
sessions:revoke, mfa:reset | Revogar todas as sessões de um usuário; resetar MFA (com justificativa) |
audit:read | Consultar auditoria e diagnóstico |
self:register | Criar intenção de cadastro (Plataforma Mundo) |
self:read|update|email|mfa|sessions | Autoatendimento do próprio usuário (token curto, 15 min) |
Endpoints principais
| Método e rota | Função |
|---|---|
GET|POST /admin/users | Listar (filtros status, email) / criar convite (devolve registration_url) |
POST /admin/users/{user}/suspend|activate | Suspender / reativar |
POST /admin/users/{user}/password-reset-link | Gerar redefinição de senha |
POST /admin/users/{user}/sessions/revoke-all | Revogação global |
POST /admin/users/{user}/mfa/reset | Reset de MFA |
GET|POST|PATCH /admin/applications | Aplicaçõ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-requests | Criar a solicitação (draft); 409 se já houver uma aberta |
POST /admin/integration-requests/{id}/transition | Avançar o workflow (status, reason) |
GET /admin/clients, POST /admin/applications/{app}/clients | Listar / emitir client |
POST /admin/clients/{client}/rotate-secret|suspend|activate | Rotacionar secret / suspender / ativar |
PUT /admin/clients/{client}/redirect-uris | Substituir URIs |
GET /admin/audit, /audit/{id}, /audit/diagnostics | Consultar auditoria |
GET|PATCH /me, /me/sessions, /me/mfa/totp | Autoatendimento |
GET /status | Status 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+jsoncomcorrelation_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 (
limit1–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)
- Criar a aplicação —
POST /admin/applications(name,slug,category,registration_policy,requires_user_assignment,trusted_consent). - Criar a solicitação de integração —
POST /admin/applications/{application}/integration-requests(status inicialdraft;409se já existe uma aberta). - Percorrer o workflow —
submitted → security_review → sandbox → homologated → activecomPOST .../transition(uma chamada por etapa, cada uma comIdempotency-Keynova). - Emitir o client do ambiente do servidor (
productionno SSO de produção) com as URIs exatas. Copiarclient.idesecretna hora. - Configurar a aplicação: issuer,
client_id,client_secret,redirect_uriepost_logout_redirect_uricomo variáveis de ambiente (nunca no Git). - 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/nonceerrados eredirect_uriparecida ou com curinga são rejeitados. - Assinatura,
iss,audeexpinvá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
| Plataforma | Regra |
|---|---|
| Web com backend | Client confidencial; secret só no backend; tokens no servidor; cookie de sessão Secure/HttpOnly. |
| SPA | Preferir BFF; sem BFF, client público com PKCE e token de acesso só em memória. Nunca refresh token em localStorage. |
| Mobile / Desktop | Navegador 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
auditem 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/diagnosticsinforma retenção, volume, severidade recente e estado do outbox.
Saúde
| Endpoint | Uso |
|---|---|
GET /up | Liveness (processo de pé). |
GET /up/ready | Readiness: testa banco e cache e verifica atraso do outbox. 200 ready, 503 quando degradado ou sem dependência. |
GET /api/v1/status | Status técnico público (nome, estado, horário). |
18. Modelo de segurança
| Controle | Como funciona |
|---|---|
| Senhas | Argon2id; comparação de tempo constante; sem enumeração de contas. |
| Segundo fator | Step-up por e-mail em contexto novo/arriscado; TOTP voluntário; recuperação por códigos de uso único. |
| Segredos em repouso | TOTP e CPF/CNPJ cifrados; tokens, códigos e secrets de client guardados como hash. |
| Rate limiting | Por 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çalhos | CSP (default-src 'self', script-src 'self', frame-ancestors 'none'), HSTS, X-Content-Type-Options, Referrer-Policy: no-referrer, Permissions-Policy, COOP. |
| CSRF e cookies | CSRF em todos os formulários; cookies Secure, HttpOnly, SameSite=Lax. |
| Proxy | Confiança em proxy somente pelos CIDRs explícitos de TRUSTED_PROXIES; sem isso o IP real do cliente é perdido. |
| OIDC | PKCE S256 e nonce obrigatórios, redirects exatos, RS256 com kid, refresh rotacionado com detecção de reuso, sem grants inseguros. |
| Ambientes | Client e token de API presos ao ambiente do servidor. |
| Privacidade | Claims mínimos; consentimento explícito para aplicações externas; dados pessoais fora de logs. |
19. Operação e deploy
Processos (mesma imagem)
| Serviço | Comando | Observação |
|---|---|---|
| Web | gerado pelo Nixpacks (PHP-FPM + Nginx) | Health /up, readiness /up/ready |
| Worker | php artisan queue:work --sleep=3 --tries=3 --timeout=90 --max-time=3600 | 1 réplica; sem domínio |
| Scheduler | php artisan schedule:work | 1 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
| Tarefa | Frequência |
|---|---|
| Publicar outbox de auditoria | a cada minuto |
| Expurgar auditoria além da retenção | diária, 02:30 |
| Limpar intenções de identidade expiradas | diária |
| Podar tokens Sanctum expirados, jobs falhos e chaves de idempotência | diária |
Variáveis de ambiente principais
| Grupo | Variáveis |
|---|---|
| Aplicação | APP_ENV, APP_URL, APP_KEY, APP_DEBUG=false |
| OIDC | OIDC_ENVIRONMENT, OIDC_ISSUER, OIDC_KEY_ID, PASSPORT_PRIVATE_KEY, PASSPORT_PUBLIC_KEY, TTLs, OIDC_RETIRING_PUBLIC_KEYS |
| API | API_CONSUMER_ENVIRONMENT, API_ADMIN_TOKEN_TTL_MINUTES, API_SELF_TOKEN_TTL_MINUTES |
| Segurança | DOCUMENT_BLIND_INDEX_KEY (diferente de APP_KEY), limiares de risco, TRUSTED_PROXIES, TRUSTED_CONTEXT_* |
| Banco e fila | DB_* (MySQL), SESSION_DRIVER=database, QUEUE_CONNECTION=database, CACHE_STORE=database |
MAIL_* (SMTP), MAIL_FROM_ADDRESS, MAIL_EHLO_DOMAIN | |
| Auditoria | AUDIT_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
| Sintoma | Causa provável | Ação |
|---|---|---|
403 The application is not active and homologated | Aplicação ainda não está active, ou client suspenso | Avançar o workflow até active; verificar o client |
403 The client credential belongs to another environment | Client 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 ... different | Redirect final bloqueado por CSP form-action (corrigido) ou clique duplo | Atualizar o SSO; marcar o client como confiável para pular a tela |
Cai em /verify-email sem ter sessão | Rota de autorização sem auth (corrigido) | Atualizar o SSO |
| Código de acesso não chega | Worker parado ou SMTP incorreto | Subir o worker; conferir MAIL_*; ver fila de jobs |
422 Transition from X to Y is not allowed | Etapa pulada ou já executada | Seguir a ordem do workflow |
403 Invalid API consumer | Ambiente do token diferente de API_CONSUMER_ENVIRONMENT | Reemitir o token com o ambiente correto |
409 na API | Idempotency-Key repetida com corpo diferente | Gerar chave nova |
| IP do usuário aparece sempre o mesmo | TRUSTED_PROXIES vazio | Informar o CIDR da rede do Traefik |
/up/ready devolve 503 | Banco/cache indisponível ou outbox atrasado | Ver banco e scheduler; consultar /admin/audit/diagnostics |
| Timeout ao conectar no MySQL | Firewall do servidor do banco | Liberar a porta só para o IP do servidor do SSO |
21. Limitações conhecidas
amr=otpainda não é emitido. O SSO registrapwdeemail, mas o valorotpdepende de um ajuste pendente. Aplicações que exigem segundo fator poramrdevem usar o login local até a correção.- Logout com
id_token_hintexpirado é 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.
