IAM
ProduçãoIdentidade, organizações e permissões para todo o catálogo de building blocks
Você não integra login em cada serviço que contrata. Contrata o IAM uma vez e todos os 32 building blocks passam a saber quem é o usuário, de que empresa ele é e o que ele pode fazer.
- Fintechs e bancos digitais que operam múltiplas empresas clientes na mesma plataforma
- Plataformas B2B que vendem para empresas e precisam separar dados por cliente
- Times de produto que integram vários serviços e não querem replicar autorização em cada um
- Assinatura de um provedor de identidade externo (Auth0, Cognito) para o cenário B2B multi-tenant
- Tabela de usuários, papéis e permissões reimplementada dentro de cada serviço
- Camada caseira de "de qual empresa é este registro" espalhada pelo código
- Um provedor de identidade para o usuário final do seu app (login social, SAML — isso é o building block SSO)
- Um gerenciador de senhas ou cofre de segredos
- Um sistema de KYC ou verificação de identidade documental
38 endpoints em 8 recursos.
/iam/api/v1/users/iam/api/v1/mfa/iam/api/v1/organizations/iam/api/v1/iam/api/v1/associations/iam/oauth/iam/healthResumo executivo
O IAM responde três perguntas para todos os outros building blocks: quem é este usuário, de qual empresa ele é e o que ele tem permissão de fazer. Ele emite o token que carrega essas três respostas, e todo o resto da plataforma confia nesse token em vez de manter cadastro próprio.
Na prática isso significa que quando uma financeira contrata o Commerce e o Payments, ela não cadastra usuário duas vezes nem descobre, três meses depois, que o time de atendimento consegue estornar pagamento porque alguém esqueceu de checar permissão em um endpoint. A permissão PAYMENTS_REFUND_CREATE é a mesma string em todo lugar, e quem não a tem no token recebe 403 antes de a requisição chegar na regra de negócio.
Está em produção desde fevereiro de 2026 e é dependência obrigatória de todos os outros 31 building blocks — nenhum sobe sem ele.
| Atributo | Valor |
|---|---|
| Identificador | iam |
| Categoria | Identidade |
| Escopo | Global (não exige organizationId para operar) |
| Porta (standalone) | 3001 |
| Path alias | @iam |
| Prefixo HTTP | /iam |
| Status | Produção desde 2026-02 |
| Depende de | PostgreSQL, Redis |
O problema
negócioO cenário. Uma plataforma B2B vende para empresas, não para pessoas. Cada empresa cliente tem seus próprios usuários, seus próprios dados, e não pode enxergar um byte da empresa vizinha. Conforme a plataforma cresce, ela deixa de ser um serviço e vira dez — e cada um precisa saber quem está chamando.
É aqui que a arquitetura se degrada em silêncio. Cada serviço novo chega com a própria noção de quem-pode-o-quê, e a plataforma passa a ter tantas implementações de autorização quantos serviços tiver.
flowchart TD U["Usuário da empresa cliente"] --> A["Serviço A"] U --> B["Serviço B"] U --> C["Serviço C"] A --> AA["Tabela de usuários própria<br/>Checagem de permissão própria"] B --> BB["Outra tabela<br/>Outra checagem"] C --> CC["Sem checagem<br/>alguém esqueceu"] AA --> R["Risco: regra divergente por serviço"] BB --> R CC --> R
O que trava hoje.
- Cada serviço reimplementa autorização. O time do serviço A checa permissão de um jeito, o do serviço B de outro, e o terceiro esquece de checar. O bug não aparece em teste, aparece em auditoria.
- O provedor de identidade externo não conhece o seu domínio. Auth0 sabe que o usuário fez login; não sabe se ele pode cancelar uma assinatura. A regra volta para o seu código, replicada em cada serviço.
- Multi-tenancy vira convenção, não garantia. "Todo mundo lembra de filtrar por
organization_id" é uma frase que funciona até o dia em que alguém não lembra. Vazamento entre clientes é o incidente que não tem pedido de desculpas suficiente. - Integração máquina a máquina é gambiarra. Sem M2M de verdade, o parceiro acaba com um usuário de serviço com senha em variável de ambiente e permissão de administrador.
- O custo por usuário não fecha no B2B. Preço por usuário ativo mensal foi desenhado para aplicativo de consumidor. Numa plataforma B2B com dezenas de milhares de usuários corporativos de baixa frequência, a conta cresce sem relação com o valor entregue.
O custo de não resolver. Autorização espalhada é a origem mais comum de falha de controle de acesso — a categoria "Broken Access Control" lidera o OWASP Top 10 desde 2021 (OWASP Top 10:2021). E o custo não é só o incidente: é cada novo serviço nascendo com mais duas semanas de trabalho só para reimplementar quem-pode-o-quê.
Proposta de valor
negócio| Antes | Depois |
|---|---|
| Cada serviço tem sua tabela de usuários e sua lógica de permissão | Um token, um vocabulário de permissões, 32 serviços obedecendo |
| "Lembrar de filtrar por organização" é disciplina de equipe | Building block tenant-scoped recusa requisição sem organização no token |
| Integração de parceiro usa usuário de serviço com senha fixa | client_credentials com escopo, credencial rotacionável, expiração curta |
| Adicionar um serviço novo custa duas semanas de autorização | O serviço novo declara suas permissões e já nasce protegido |
O desenho que sustenta essa tabela é simples: um único ponto emite a credencial, e todo o resto apenas verifica.
flowchart LR U["Usuário"] -->|"login"| IAM["IAM"] P["Parceiro"] -->|"client_credentials"| IAM IAM -->|"JWT: sub, organizationId, permissions"| BBs["32 building blocks"] BBs -->|"requirePermission + requireOrganization"| OK["Resposta ou 403"]
Autorização escrita uma vez
As permissões são um enum compartilhado por todos os building blocks. O middleware requirePermission é o mesmo código em todo lugar — não há trinta implementações para auditar, há uma.
O tenant vem do token, nunca do corpo da requisição
O organizationId é claim assinado. Um cliente não consegue pedir dados de outro trocando um campo no JSON, porque o campo não é lido do JSON.
Máquina a máquina de verdade
O parceiro recebe client_id (que é o identificador da própria organização) e client_secret rotacionável, troca por token de vida curta e opera com escopo reduzido ao que precisa.
Custo desacoplado do número de usuários
O IAM vem com a plataforma. Uma empresa cliente com 40 usuários corporativos não custa 40 vezes uma com um usuário.
Casos de uso reais
negócioCaso 1 — Uma financeira separa correspondentes bancários sem duplicar infraestrutura Cenário ilustrativo
Financeira de crédito consignado que opera através de 120 correspondentes bancários. Cada correspondente tem de 3 a 40 operadores, e nenhum pode ver proposta de outro.
A primeira versão da plataforma tinha uma instância por correspondente. Cento e vinte bancos de dados, cento e vinte deploys, e uma migração de schema que levava um fim de semana inteiro. O custo de infraestrutura crescia linearmente com as vendas, o que é exatamente o contrário do que se espera de software.
Cada correspondente vira uma Organization do tipo parceiro. Os operadores viram User associados a essa organização por uma Association que carrega o papel. Todo building block tenant-scoped — Customers, Products, Decision Platform — lê o organizationId do token e nunca do corpo. A separação deixa de ser topológica e passa a ser criptográfica.
flowchart LR
subgraph antes["Antes — separação topológica"]
C1["Correspondente 1"] --> I1["Instância + banco 1"]
C2["Correspondente 2"] --> I2["Instância + banco 2"]
C120["Correspondente 120"] --> I120["Instância + banco 120"]
end
subgraph depois["Depois — separação por token"]
O1["Organization 1"] --> T["Token com organizationId"]
O2["Organization 2"] --> T
O120["Organization 120"] --> T
T --> U["Uma instância<br/>um deploy<br/>uma migração"]
end
antes -.->|"migração"| depoisUma instância, um deploy, uma migração. Adicionar um correspondente vira uma chamada POST /iam/api/v1/organizations em vez de um provisionamento de ambiente.
Caso 2 — Um parceiro integra por API sem nunca receber senha de usuário Cenário ilustrativo
Marketplace que envia pedidos para o ERP de um cliente através da API da plataforma, sem interface humana no meio.
A integração anterior usava um usuário de serviço chamado integracao@empresa.com com senha em variável de ambiente do marketplace. A senha nunca expirava, tinha permissão de administrador porque ninguém quis descobrir o conjunto mínimo, e não havia como revogar sem quebrar a integração em produção às três da tarde.
O parceiro recebe o client_id (o próprio organizationId) e um client_secret gerado por POST /iam/api/v1/organizations/:id/client-secret. A integração troca as credenciais em POST /iam/oauth/token com grant_type=client_credentials e recebe um token de uma hora, com permissões filtradas pelo scope solicitado. Rotacionar o segredo é uma chamada de API.
sequenceDiagram participant Op as Operador da plataforma participant IAM participant Mk as Marketplace participant BB as Building block tenant-scoped Op->>IAM: POST /organizations/:id/client-secret IAM-->>Op: clientId + clientSecret (exibido uma vez) Op->>Mk: entrega credencial Mk->>IAM: POST /oauth/token (client_credentials + scope) IAM-->>Mk: access_token (1h, escopo reduzido) Mk->>BB: Authorization Bearer BB-->>Mk: dados apenas da organização do token
Credencial com escopo mínimo, expiração curta e rotação sem downtime. E toda emissão de token fica registrada no log de segurança, então "quando essa integração foi usada pela última vez" vira uma consulta em vez de uma suposição.
Caso 3 — Uma auditoria de acesso deixa de ser um projeto de três semanas Cenário ilustrativo
Operação regulada precisa responder ao auditor quem tinha acesso a dados de cliente no último trimestre.
Com autorização espalhada por dez serviços, responder isso significava dez levantamentos diferentes, cada um com um dono, um formato e um grau de confiança distinto. O relatório chegava desatualizado.
O acesso é a interseção de três tabelas: Association liga usuário, organização e papel; Role define o papel; OrganizationPermission define o que a organização contratou. A resposta é uma consulta — a consulta de auditoria cruza Association com OrganizationPermission e resolve as permissões do papel pelo mapa ROLE_PERMISSIONS do código (src/iam/constants/permissions.ts), já que Role guarda apenas o nome. O Audit Trail complementa registrando o que foi de fato acessado.
erDiagram
User ||--o{ Association : "participa"
Organization ||--o{ Association : "recebe"
Role ||--o{ Association : "define papel"
Organization ||--o{ OrganizationPermission : "contratou"A pergunta "quem podia ver o quê" tem uma fonte de verdade, e a resposta é reproduzível.
Caso 4 — Multi-tenancy como fundação, não como remendo Referência de mercado
O padrão de banco de dados compartilhado com discriminador de tenant é a arquitetura recomendada pela AWS e pela Microsoft para SaaS B2B, justamente pelo custo por tenant (AWS SaaS Tenant Isolation Strategies).
No mercado, o mesmo material é explícito no risco: com banco compartilhado, o isolamento passa a depender inteiramente da camada de aplicação. Uma cláusula WHERE esquecida é um vazamento entre clientes.
É assim que a Catalisa endereça o risco: o organizationId chega por claim assinado e nunca pelo corpo. O middleware requireOrganization bloqueia antes da regra de negócio. E building blocks que guardam dado sensível — o Data Store é o exemplo — somam Row-Level Security no Postgres como segunda barreira, para que a falha de aplicação não seja suficiente para vazar.
flowchart LR R["Requisição com Bearer JWT"] --> M1["authMiddleware<br/>assinatura HS256 válida?"] M1 -->|não| E401["401"] M1 -->|sim| M2["requireOrganization<br/>claim organizationId presente?"] M2 -->|não| E403["403"] M2 -->|sim| M3["requirePermission<br/>permissão no token?"] M3 -->|não| E403 M3 -->|sim| N["Regra de negócio"] N --> RLS["Row-Level Security no Postgres<br/>segunda barreira, nos BBs sensíveis"] RLS --> D["Dados apenas do tenant"]
O padrão econômico de multi-tenancy sem aceitar o risco que normalmente vem junto.
Mercado e diferenciais
negócioPanorama. O mercado de identidade se dividiu em três campos. Os provedores hospedados (Auth0, Clerk, Cognito) resolvem autenticação muito bem e cobram por usuário ativo. As soluções auto-hospedadas (Keycloak, FusionAuth) entregam protocolo completo e transferem a operação para você. E, na prática, quase toda plataforma B2B acaba escrevendo uma terceira camada em cima — a autorização de domínio, que nenhum dos dois grupos resolve, porque nenhum deles sabe o que é uma fatura na sua regra de negócio.
O IAM da Catalisa nasce nesse terceiro campo. Ele não tenta ser o melhor autenticador do mercado; ele é o autorizador que já conhece os 32 building blocks.
| Critério | Catalisa IAM | Auth0 | Amazon Cognito | Keycloak |
|---|---|---|---|---|
| Modelo de preço | Incluso na plataforma | Por usuário ativo mensal | Por usuário ativo mensal | Licença zero, você opera |
| Organização como cidadã de 1ª classe | Sim, no token | Só nos planos superiores | Não | Via realm, um por tenant |
| Autorização de domínio | Vocabulário único nos 32 BBs | Fora do escopo | Fora do escopo | Genérica, você mapeia |
| M2M com escopo | client_credentials nativo | Sim, cobrado à parte | Sim | Sim |
| Login social e SAML | Não (é o BB SSO) | Sim, extenso | Parcial | Sim, extenso |
| MFA | Não implementado (ver §15) | Sim | Sim | Sim |
| Tela de login hospedada | Não | Sim | Sim | Sim |
| Operação por sua conta | Já vem operado | Não | Não | Sim, integral |
Nossos diferenciais
- A permissão é do domínio, não genérica.
BILLING_INVOICES_VOIDsignifica alguma coisa concreta porque o Billing a declara e o middleware a exige. Um IdP externo só conseguiria chegar aqui se você reimplementasse o catálogo inteiro dentro dele — e mantivesse os dois em sincronia para sempre. - O tenant não é opcional em nenhum ponto do caminho. O
organizationIdé claim assinado, e os building blocks tenant-scoped rejeitam token sem ele. Não é convenção de time, é o código recusando. - A credencial M2M já nasce com o tenant amarrado. O
client_idé o identificador da organização. Não existe estado em que uma credencial de integração esteja apontando para o tenant errado, porque ela é o tenant. - Custo desacoplado de usuário ativo. No B2B, o número de usuários corporativos tem pouca relação com o valor entregue. Cobrar por ele penaliza exatamente o cliente que mais cresce.
Quando escolher o concorrente. O IAM ganha quando o problema é autorização de domínio em plataforma B2B multi-tenant — não quando o problema é autenticação de consumidor final. Nos três cenários abaixo, a escolha certa é outra.
flowchart TD
Q1{"Seu produto é B2C,<br/>com login social e<br/>tela de login pronta?"}
Q1 -->|sim| A["Auth0 ou Clerk"]
Q1 -->|não| Q2{"Exige SAML corporativo<br/>ou LDAP?"}
Q2 -->|sim| K["Keycloak"]
Q2 -->|não| Q3{"Já vive na AWS, com<br/>volume alto de usuários?"}
Q3 -->|sim| C["Amazon Cognito"]
Q3 -->|não| I["Catalisa IAM"]| Se o seu caso é | Escolha | Por quê |
|---|---|---|
| B2C com login Google/Apple, tela de login pronta, MFA por SMS e recuperação de senha com boa conversão | Auth0 ou Clerk | Entregam isso hoje; o IAM não. Nossa camada de identidade federada é um building block separado, o SSO, e o MFA ainda não está implementado |
| SAML corporativo ou LDAP | Keycloak | É a escolha madura em cobertura de protocolo |
| Já vive dentro da AWS, volume alto de usuários e tolerância à experiência de desenvolvimento | Amazon Cognito | Será mais barato que qualquer alternativa |
Modelo de cobrança e ROI
negócioUnidade de cobrança. O IAM não é cobrado à parte. Ele é infraestrutura obrigatória de todos os outros building blocks, e cobrar por ele seria cobrar duas vezes pela mesma coisa.
O que dispara custo. Número de organizações ativas e volume de emissão de token — ambos com impacto marginal, já que a emissão é uma assinatura HS256 e a verificação não toca o banco.
Comparação de custo — cenário: plataforma B2B com 80 empresas clientes e 4.000 usuários corporativos, dos quais cerca de 2.500 acessam em um mês típico.
| Catalisa IAM | Auth0 (B2B Essentials) | Amazon Cognito | |
|---|---|---|---|
| Base de cálculo | Incluso na plataforma | Por usuário ativo mensal | Por usuário ativo mensal, após a faixa gratuita |
| Ordem de grandeza mensal | R$ 0 adicional | Alguns milhares de reais | Dezenas de reais |
| Autorização de domínio | Inclusa | Você implementa | Você implementa |
| Custo de engenharia estimado | — | 2 a 4 semanas por serviço novo | 2 a 4 semanas por serviço novo |
Ordens de grandeza para orientar conversa, não proposta comercial. Preços de Auth0 e Cognito variam por região, plano e negociação — consulte as tabelas públicas dos fornecedores na data da sua análise. O custo de engenharia é estimativa interna.
ROI
O retorno não está na linha de licença — o Cognito é mais barato que qualquer coisa. Está na engenharia que não é gasta.
flowchart LR
A["Building block novo entra no catálogo"] --> B{"Existe IAM?"}
B -->|não| C["2 a 4 semanas reimplementando<br/>quem-pode-o-quê + risco de errar"]
B -->|sim| D["Declara as permissões<br/>e já nasce protegido"]
C --> E["Coleção de serviços<br/>que não conversam"]
D --> F["Catálogo integrado"]Cada building block novo que entra no catálogo já nasce autorizado; sem o IAM, cada um custaria de duas a quatro semanas de trabalho só para reimplementar quem-pode-o-quê, com a chance de errar que isso carrega. Com 32 building blocks, essa é a diferença entre um catálogo e uma coleção de serviços que não conversam.
Arquitetura
As camadas e o caminho da requisição
flowchart TD
HTTP["HTTP"] --> HONO
subgraph HONO["Hono app — basePath('/iam')"]
R1["/api/v1/users<br/>usersRouter · userAssociationsRouter"]
R2["/api/v1/organizations<br/>organizationsRouter · membersRouter"]
R3["/api/v1/roles<br/>rolesRouter"]
R4["/api/v1/permissions<br/>permissionsRouter"]
R5["/api/v1/associations<br/>associationsRouter"]
R6["/oauth<br/>oauthRouter — token · revoke"]
R7["/health<br/>sonda com banco, cripto e JWT"]
end
HONO -->|"Zod parse → ResultAsync<T, AppError>"| SVC
subgraph SVC["services/"]
S1["AuthService — login, emissão de par de tokens"]
S2["UserService — ciclo de vida do usuário"]
S3["OrganizationService — organizações e client_secret"]
S4["AssociationService — usuário ↔ organização ↔ papel"]
S5["RoleService — catálogo de papéis e permissões"]
S6["OrganizationPermissionService — o que a org contratou"]
S7["RefreshTokenService — rotação e revogação"]
end
SVC --> REPO["repositories/ (Prisma)"]
REPO --> PG[("PostgreSQL — schema iam")]O token sai daqui e é verificado em todo lugar
O token emitido pelo IAM é consumido por todos os outros building blocks, e a verificação é o mesmo código nos 32:
flowchart LR
C["Cliente"] -->|"Bearer JWT"| MW
subgraph MW["Middlewares — idênticos nos 32 BBs"]
direction TB
A["authMiddleware<br/>verifica assinatura HS256"] --> B["requirePermission(P)<br/>P ∈ token.permissions?"]
B --> D["requireOrganization<br/>token.organizationId presente?"]
end
MW --> H["Handler da regra de negócio"]Decisões não óbvias.
- HS256 com segredo compartilhado, e não RS256. Todos os building blocks são nossos e rodam na nossa infraestrutura, então a chave pública não traria benefício e a rotação de par de chaves traria custo operacional. O trade-off aceito é que qualquer serviço com o segredo pode emitir token, não só verificar — o que é aceitável enquanto todos os consumidores forem internos. No dia em que um terceiro precisar verificar token sem poder emitir, isso vira RS256.
JWT_SECRETcom mínimo de 44 caracteres, validado no construtor. É o comprimento de uma chave de 256 bits em base64. O serviço não sobe com segredo fraco; falhar no boot é melhor que rodar inseguro.- Preflight de JWT no startup. O
JwtService.preflight()assina e verifica um token descartável antes de o serviço aceitar tráfego. Um segredo malformado quebra no boot, não na primeira requisição de um cliente. - Permissões dentro do token, não consultadas por requisição. A verificação não toca o banco, o que mantém a latência do middleware perto de zero. O trade-off é que revogar permissão só surte efeito na renovação do token — por isso o access token dura uma hora por padrão.
isRootcomo claim explícito. Operador de plataforma precisa de acesso cross-organização. Isso é um claim booleano e nomeado, em vez de um caso especial escondido em cada rota, justamente para que seja auditável.- Rate limit nas rotas de autenticação.
POST /users/loginePOST /oauth/tokenpassam porauthRateLimitMiddleware, e falhas geram evento emlogSecurityEvent. Força bruta é ruidosa e limitada por padrão.
Monolito vs. standalone
Em monolito, os outros building blocks resolvem o IAM pelo container TypeDI, com chamada direta. Em standalone — o modo usado em produção — o IAM roda na porta 3001 e os demais o alcançam por HTTP via ModuleClient.
| Monolito | Standalone (produção) | |
|---|---|---|
| Como os BBs alcançam o IAM | Container TypeDI, chamada direta em processo | HTTP via ModuleClient, porta 3001 |
| Emissão de token | No mesmo processo | Requisição de rede ao IAM |
| Verificação de token | Local, sem rede | Local, sem rede |
A verificação não precisa de rede em nenhum dos dois modos: qualquer serviço com o JWT_SECRET valida a assinatura localmente.
Conceitos e modelo de dados
Glossário
| Termo | Significa |
|---|---|
| Organization | Uma empresa dentro da plataforma. É a unidade de isolamento: todo dado tenant-scoped pertence a exatamente uma. |
| User | Uma pessoa. Existe globalmente, com e-mail único, e pode pertencer a várias organizações. |
| Association | O vínculo entre usuário, organização e papel. É o que responde "esta pessoa, nesta empresa, é o quê". |
| Role | Papel nomeado (ADMIN, VIEWER, ...). Agrupa permissões. |
| Permission | String do vocabulário compartilhado, no formato MODULO_RECURSO_ACAO — por exemplo IAM_USERS_CREATE. |
| OrganizationPermission | O que a organização contratou. Limite superior: um usuário nunca recebe permissão que a organização dele não tem. |
| Client secret | Segredo da organização para autenticação M2M. Guardado como hash, exibido só na criação. |
| isRoot | Marca de operador de plataforma. Libera acesso cross-organização. |
| Segundo fator (MFA) | Código TOTP de app autenticador, com 10 códigos de recuperação. Depois da senha certa, o login devolve um desafio em vez do token; o código troca o desafio pelo token. |
amr | Claim do token (RFC 8176) que diz como a pessoa entrou: ["pwd"] só senha; ["pwd","otp","mfa"] senha + TOTP; ["pwd","mfa"] senha + código de recuperação. Quem exige segundo fator confere mfa. |
mfaRequired | Política da organização: todo login com ela exige segundo fator. Padrão false. Quem já cadastrou o fator é desafiado sempre, ligado ou não. |
Modelo de dados — schema iam no PostgreSQL.
| Modelo Prisma | Tabela | Propósito | Campos-chave |
|---|---|---|---|
User | iam.users | Pessoa autenticável | email (único), passwordHash, status, isRoot, mfaEnabled, deletedAt |
Organization | iam.organizations | Empresa cliente, parceiro ou dono | slug (único), type, status, clientSecretHash, mfaRequired, metadata |
Association | iam.associations | Vínculo usuário ↔ organização ↔ papel | Chave primária composta (userId, organizationId, roleId) |
Role | iam.roles | Catálogo de papéis | name (único) |
OrganizationPermission | iam.organization_permissions | Permissões contratadas pela organização | Único (organizationId, permission) |
RefreshToken | iam.refresh_tokens | Refresh tokens emitidos | token (único), expiresAt |
UserMfaFactor | iam.user_mfa_factors | Segundo fator TOTP do usuário (um por usuário) | userId (único), secretEncrypted, confirmedAt, lastUsedStep, failedAttempts, lockedUntil |
UserMfaRecoveryCode | iam.user_mfa_recovery_codes | Códigos de recuperação — só o hash | codeHash (único), usedAt |
Enumerações
| Enum | Valores |
|---|---|
UserStatus | ativo · inativo · pendente · bloqueado |
OrganizationType | cliente · parceiro · dono |
OrganizationStatus | ativo · inativo · suspenso |
Relacionamentos
erDiagram
User ||--o{ Association : "pertence a"
Organization ||--o{ Association : "tem membros"
Role ||--o{ Association : "papel do vínculo"
Organization ||--o{ OrganizationPermission : "contratou"
User ||--o{ RefreshToken : "possui"
User ||--o| UserMfaFactor : "segundo fator"
User ||--o{ UserMfaRecoveryCode : "recuperação"Login com segundo fator
sequenceDiagram
participant C as Cliente (ex.: console do banco)
participant I as IAM
C->>I: POST /users/login {email, password, organizationId}
alt usuário com fator confirmado
I-->>C: 200 {mfaRequired: true, enrollmentRequired: false, challengeToken, expiresIn: 300}
C->>I: POST /users/login/mfa {challengeToken, code | recoveryCode}
I-->>C: 200 {accessToken (amr: pwd+otp+mfa), refreshToken}
else organização com mfaRequired e usuário sem fator
I-->>C: 200 {mfaRequired: true, enrollmentRequired: true, challengeToken, expiresIn: 900}
C->>I: POST /users/login/mfa/enroll {challengeToken}
I-->>C: 201 {secret, otpauthUri} ← o cliente desenha o QR
C->>I: POST /users/login/mfa/enroll/confirm {challengeToken, code}
I-->>C: 200 {accessToken (amr: pwd+otp+mfa), refreshToken, recoveryCodes[10]}
else padrão
I-->>C: 200 {accessToken (amr: pwd), refreshToken}
endCiclo de vida do usuário
stateDiagram-v2 [*] --> pendente: criação (POST /users) pendente --> ativo: ativação (PATCH status) ativo --> bloqueado: suspensão (PATCH status) ativo --> inativo: desativação (PATCH status) ativo --> [*]: exclusão lógica (deletedAt) inativo --> [*]: exclusão lógica (deletedAt) bloqueado --> [*]: exclusão lógica (deletedAt)
Atenção. O usuário nasce pendente e só o status ativo autentica — o AuthService recusa qualquer outro. A exclusão é lógica: deletedAt é preenchido e a linha é preservada para auditoria.
Ciclo de vida da organização
stateDiagram-v2 [*] --> ativo: criação (POST /organizations, padrão ativo) ativo --> suspenso: suspensão (PATCH status) suspenso --> ativo: reativação (PATCH status) ativo --> inativo: desativação (PATCH status) inativo --> ativo: reativação (PATCH status) ativo --> [*]: exclusão lógica (deletedAt) inativo --> [*]: exclusão lógica (deletedAt) suspenso --> [*]: exclusão lógica (deletedAt)
Como uma permissão chega ao token
flowchart TD
A["Permissões da organização<br/>(OrganizationPermission)"] --> X{"interseção"}
B["Permissões do papel<br/>(Role → ROLE_PERMISSIONS)"] --> X
X --> T["token.permissions[]<br/>o que o usuário de fato pode fazer"]Atenção. A organização é o teto. Papel de ADMIN numa organização que não contratou o Billing não concede nenhuma permissão de Billing.
Referência da API
Prefixo: /iam. Em standalone, a base é https://iam.stg.catalisa.app.
Usuários — /iam/api/v1/users
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /iam/api/v1/users | Cria usuário | IAM_USERS_CREATE |
POST | /iam/api/v1/users/login | Autentica e emite par de tokens | Pública (com rate limit) |
GET | /iam/api/v1/users | Lista usuários, paginado | IAM_USERS_READ |
GET | /iam/api/v1/users/:userId | Busca usuário | IAM_USERS_READ |
PATCH | /iam/api/v1/users/:userId | Atualiza usuário | IAM_USERS_UPDATE |
DELETE | /iam/api/v1/users/:userId | Exclusão lógica | IAM_USERS_DELETE |
GET | /iam/api/v1/users/:userId/associations | Organizações e papéis do usuário | IAM_ASSOCIATIONS_READ |
POST | /iam/api/v1/users/login/mfa | Segundo passo do login: {challengeToken, code} ou {challengeToken, recoveryCode} | Pública, com desafio (rate limit) |
POST | /iam/api/v1/users/login/mfa/enroll | Cadastro devido no login: devolve secret e otpauthUri | Pública, com desafio enroll |
POST | /iam/api/v1/users/login/mfa/enroll/confirm | Primeiro código: cadastra, entra e devolve os 10 códigos de recuperação (uma vez) | Pública, com desafio enroll |
POST | /iam/api/v1/users/:userId/mfa/reset | Admin remove o fator de outro usuário, com {reason} obrigatório; revoga os refresh tokens dele. 202 com pedido quando a organização exige quatro olhos | IAM_USERS_UPDATE + mesma organização |
Segundo fator do próprio usuário — /iam/api/v1/mfa
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
GET | /iam/api/v1/mfa | Estado: enrolled, pending, lockedUntil, recoveryCodesRemaining | Token de usuário (não chave de API) |
POST | /iam/api/v1/mfa/totp/enroll | Cadastro voluntário: secret e otpauthUri | Token de usuário |
POST | /iam/api/v1/mfa/totp/confirm | Primeiro código {code}; devolve os códigos de recuperação | Token de usuário |
Não existe rota para o dono desligar o próprio fator: uma sessão roubada a usaria primeiro. Desligar é o reset por outro admin, com motivo.
Organizações — /iam/api/v1/organizations
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /iam/api/v1/organizations | Cria organização | IAM_ORGANIZATIONS_CREATE |
GET | /iam/api/v1/organizations | Lista organizações | IAM_ORGANIZATIONS_READ |
GET | /iam/api/v1/organizations/:organizationId | Busca organização | IAM_ORGANIZATIONS_READ |
PATCH | /iam/api/v1/organizations/:organizationId | Atualiza organização (inclui mfaRequired) | IAM_ORGANIZATIONS_UPDATE |
DELETE | /iam/api/v1/organizations/:organizationId | Exclusão lógica | IAM_ORGANIZATIONS_DELETE |
POST | /iam/api/v1/organizations/:organizationId/client-secret | Gera ou rotaciona o segredo M2M | IAM_ORGANIZATIONS_UPDATE |
GET/PUT | /iam/api/v1/organizations/:organizationId/access-policy | Quatro olhos para mudança de acesso sensível (ver "Quatro olhos") | IAM_ORGANIZATIONS_READ / _UPDATE |
GET | /iam/api/v1/organizations/:organizationId/members | Lista membros: o vínculo (roleId, roleName) e a pessoa — email, status, mfaEnabled e lastLoginAt (última entrada concluída; null = nunca entrou). Nenhum segredo | IAM_ASSOCIATIONS_READ |
Papéis e permissões
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
GET | /iam/api/v1/roles | Lista papéis | IAM_ROLES_READ |
GET | /iam/api/v1/roles/:roleName/permissions | Permissões de um papel | IAM_ROLES_READ |
GET | /iam/api/v1/permissions | Permissões da organização atual | IAM_ROLES_READ |
GET | /iam/api/v1/permissions/all | Vocabulário completo da plataforma | IAM_ROLES_READ |
Associações — /iam/api/v1/associations
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /iam/api/v1/associations | Vincula usuário a organização com papel | IAM_ASSOCIATIONS_CREATE |
DELETE | /iam/api/v1/associations | Remove o vínculo | IAM_ASSOCIATIONS_DELETE |
Os eventos iam.association.created e iam.association.deleted saem com o autor em metadata.userId (e actorType, IP e agente) e a pessoa cujo acesso mudou em payload.userId. Antes o autor gravado era a própria pessoa alvo, e a trilha dizia que cada um tinha se dado o próprio papel.
POST aceita replacesRoleId (opcional) para trocar papel numa chamada só: dá o novo antes de tirar o antigo. Responde 201 com o vínculo, ou 202 com um pedido (access-requests) quando a organização exige segunda aprovação e o papel é sensível.
Quem pode mudar acesso de quem
A guarda (src/iam/authorization/access-guard.ts) vale para conceder, trocar e tirar papel:
- Só concede (ou tira) um papel quem tem TODAS as permissões dele. Comparado com o mesmo mapa que monta o token (
getRolePermissions). Quem temIAM_MANAGERnão dáADMINnemBILLING_MANAGER— nem a si, nem a outra pessoa. Recusa:403 MISSING_ROLE_PERMISSIONS, comdetails.missing. - Ninguém altera os próprios papéis — nem
ADMIN, nem root.403 SELF_ROLE_CHANGE. - Máquina não concede papel de pessoa. Chave de API e token M2M recebem
403 MACHINE_CANNOT_GRANT_ROLE, salvo a organizaçãodono(operador da plataforma), que é como o painel provisiona o dono de um tenant novo. É a mesma exceção estreita deassertUserInOrg. - Toda recusa vai para a trilha, uma vez, com organização e autor (ver abaixo).
- Trocar a credencial de alguém (senha, e-mail, segundo fator) segue a régua da regra 1 sobre os papéis SENSÍVEIS do alvo (
checkCredentialChange): quem não poderia conceder o papel do alvo não toma a conta dele.IAM_MANAGERnão troca a senha nem reseta o fator de umADMIN; segue podendo com umVIEWER. Alvo que é de mais de uma organização, ou root, só o operador (root ou chavedono). A própria conta, por token de pessoa, passa. Recusa:403 TARGET_OUTRANKS_ACTOR, eventoiam.user.refused/iam.mfa.refused. Com a regra de quatro olhos ligada, trocarpasswordouemailde OUTRA pessoa com papel sensível é recusado (403 CREDENTIAL_CHANGE_FOUR_EYES), fora root e a chavedono: era tomar a conta do segundo aprovador e aprovar o próprio pedido. O reset do fator já vira pedido (MFA_RESET). - Só o operador nomeia
dono.POST/PATCH /organizationscomtype: 'dono'exige root ou token da própria organizaçãodono— senão o admin de um tenant promovia a sua e a chave dela herdava o alcance do operador (regra 3,assertUserInOrg). Eventoiam.organization.refused.
Não existe rota para criar papel customizado nem para editar as permissões de um papel: os papéis são o mapa ROLE_PERMISSIONS do código. Uma catraca (tests/unit/iam/routes/access-refusal-audit.test.ts) falha se uma rota de escrita aparecer em /roles; quando ela nascer, terá de chamar missingRolePermissions com as permissões do autor.
Quatro olhos — /iam/api/v1/access-requests
Com a política da organização ligada, a mudança sensível vira um PEDIDO que outra pessoa da mesma organização aprova, com prazo (24 h) e trilha:
| Mudança | Quando vira pedido | Quem aprova precisa de |
|---|---|---|
Conceder/trocar papel (POST /associations) | o papel dá permissão administrativa ou financeira (isSensitiveRole: hoje ADMIN, BILLING_MANAGER, CUSTOMER_MANAGER, IAM_MANAGER, PANEL_ADMIN, PANEL_MASTER, WPP_ADMIN) | IAM_ASSOCIATIONS_CREATE e todas as permissões do papel |
Resetar o segundo fator (POST /users/:userId/mfa/reset) | sempre | IAM_USERS_UPDATE |
Criar credencial de máquina (POST /api-keys/api/v1/api-keys) | o escopo escreve (POST/PUT/PATCH/DELETE, *, ou vazio = irrestrita) | API_KEYS_CREATE e o grant-guard sobre o escopo |
Desligar a própria política (PUT .../access-policy) | estava ligada | IAM_ORGANIZATIONS_UPDATE |
Quem decide é uma pessoa (não chave), da mesma organização (ou root), que não pediu e não é a afetada — comparando também o e-mail canônico (caixa e +sufixo ignorados): a segunda conta da mesma caixa postal não aprova o pedido da primeira. No reset de fator, quem aprova também passa pela regra 5. Aprovar papel, reset e política executa na hora; aprovar chave só libera o resgate: a chave nasce em POST /api-keys/api/v1/api-keys/from-request/:requestId, pelo autor, uma vez, dentro de 24 h — e só ele vê o segredo. Com a política ligada, PATCH /api-keys/:id não amplia chave para escrita, e POST /api-keys/:id/rotate não rotaciona a chave de escrita de OUTRA pessoa (devolveria o segredo dela sem segunda aprovação) — os dois 403 WRITE_SCOPE_NEEDS_APPROVAL. A própria chave segue rotacionável.
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
GET | /iam/api/v1/access-requests?filter[status]=PENDING | Pedidos da organização do token (root: filter[organizationId]). status é o efetivo: pendente vencido aparece EXPIRED | IAM_ASSOCIATIONS_READ |
GET | /iam/api/v1/access-requests/:requestId | Um pedido | IAM_ASSOCIATIONS_READ |
POST | /iam/api/v1/access-requests/:requestId/approve | Aprova ({ note? }) | pessoa; a do tipo (tabela acima) |
POST | /iam/api/v1/access-requests/:requestId/reject | Recusa ({ note? }) | pessoa; a do tipo |
POST | /iam/api/v1/access-requests/:requestId/cancel | Desiste (só quem pediu) | autor do pedido |
GET | /iam/api/v1/organizations/:organizationId/access-policy | { approvalRequired, source: 'house_default' | 'organization', houseDefault, recommendation, eligibleApprovers, minApprovers, canEnable, canDisableImmediately } | IAM_ORGANIZATIONS_READ (mesma organização, root ou chave dono) |
PUT | /iam/api/v1/organizations/:organizationId/access-policy | { approvalRequired: true | false | null } — ver "Ligar e desligar" abaixo; null volta ao padrão da casa | IAM_ORGANIZATIONS_UPDATE (pessoa da mesma organização ou root — a chave dono só LÊ: mudar pela chave apagava quem pediu, e quem pediu pelo painel aprovava no IAM) |
POST | /api-keys/api/v1/api-keys/from-request/:requestId | Resgata a chave aprovada (201 com key, uma vez) | autor + API_KEYS_CREATE |
Ligar e desligar — aprovadores elegíveis
Aprovador elegível = pessoa distinta da organização que pode decidir o pedido de desligar (IAM_ORGANIZATIONS_UPDATE, pelo mesmo getRolePermissions do token), com usuário ativo, não apagado, que já entrou ao menos uma vez (lastLoginAt) e não root. Duas contas no mesmo e-mail canônico contam uma vez. O convidado que nunca entrou não conta — senão o próprio admin criava uma segunda conta parada para passar da contagem. O GET devolve só a contagem (eligibleApprovers), nunca quem.
| Mudança | Aprovadores | Resultado |
|---|---|---|
| Ligar | 2 ou mais | liga na hora |
| Ligar | menos de 2 | 409 APPROVERS_INSUFFICIENT (details.eligibleApprovers) — a org ficaria presa: não desliga, não promove, não emite chave de escrita |
| Desligar | 2 ou mais | vira pedido POLICY_RELAX (202) |
| Desligar | menos de 2 | na hora, com reason: 'single_approver' e eligibleApprovers no iam.access-policy.changed. Só pessoa que tem a permissão AGORA no banco (token velho de quem perdeu o papel recebe 403 MISSING_PERMISSIONS), root ou chave dono; chave de cliente: 403 MACHINE_CANNOT_RELAX_POLICY |
Ao desligar (na hora ou por pedido aprovado), todo pedido PENDING da organização é CANCELADO, com iam.access-request.cancelled (cancelReason: 'policy_disabled', autor = quem desligou) e decisionNote: 'policy_disabled'. Cancelar e não liberar: liberar executaria, sem ninguém olhar de novo, uma mudança pedida em outro contexto (o autor pode ter perdido o poder; a chave de escrita sairia sem segunda pessoa). Quem ainda quiser refaz direto, pela guarda de hoje. Pedido de chave já APPROVED (esperando resgate) fica — já teve a segunda pessoa.
O atalho "tira o outro aprovador e desliga sozinho" está fechado: com a regra ligada, nenhuma mudança direta leva a organização de 2+ aprovadores a menos de 2 — tirar papel (DELETE /associations), trocar papel (replacesRoleId), PATCH /users/:id com status não ativo ou email (e-mail igual ao de outro aprovador o faria contar como a mesma pessoa) e DELETE /users/:id. Recusa: 409 APPROVER_QUORUM_PROTECTED (details.eligibleAfter), na trilha. Só root passa (a chave dono não: o painel a usa em nome do admin do tenant). Saída legítima: promover outro aprovador antes, ou desligar a regra (vira pedido). Checar e gravar correm sob a trava do quórum da organização (pg_advisory_xact_lock, tentada e sem segurar conexão enquanto espera): duas remoções simultâneas não veem a mesma contagem, e o ligar/desligar também conta sob ela. Ocupada por mais de 10 s: 409 APPROVER_QUORUM_BUSY.
Quem decide é conferido no banco: aprovar e recusar usam as permissões do token que ainda valem pelos papéis atuais (interseção). O admin removido enquanto o pedido esperava recebe 403 APPROVER_NOT_ELIGIBLE com o token antigo.
Padrão declarado: a organização que nunca escolheu fica DESLIGADA, e a API diz source: 'house_default' — nunca só "desligado". Recomendação: ligar (PUT ... { approvalRequired: true }) em toda organização que opera o CBP.
Estados: PENDING → EXECUTED (papel, reset, política) ou PENDING → APPROVED → EXECUTED (chave); fora disso REJECTED, CANCELLED, EXPIRED, FAILED (a execução aprovada falhou; failureReason). Cada transição é uma reivindicação condicionada ao estado anterior: duas aprovações simultâneas têm um vencedor, o outro recebe 409.
Trilha das mudanças de acesso
| Evento | Quando |
|---|---|
iam.association.refused | qualquer recusa em POST/DELETE /associations — permissão, organização alheia, corpo inválido, guarda |
iam.mfa.refused | qualquer recusa no reset de segundo fator |
iam.access-request.refused | qualquer recusa ao aprovar, recusar ou cancelar pedido |
iam.access-policy.refused | qualquer recusa ao mudar a política |
api-keys.key.refused | qualquer recusa ao emitir, ampliar ou resgatar chave |
iam.access-request.{created,approved,executed,rejected,cancelled,expired,failed} | o ciclo do pedido |
iam.access-policy.changed | a política mudou (before/after, com source) |
As recusas saem do middleware auditAccessRefusals, entre authMiddleware e requirePermission, e por isso pegam toda camada. metadata.organizationId é a organização do autor (o alvo vai em payload.targetOrganizationId); metadata.userId + actorType só quando há autor; o alvo vai em payload.targetUserId, nunca em payload.userId (o mapeador da trilha o leria como autor). 401 não é publicado (não há autor) e 5xx é falha, não recusa.
Armadilhas e troubleshooting
- "O painel parou de dar papel ao dono do tenant novo." O painel usa
x-api-keyda organização da plataforma. Se a organização da chave não for do tipodono, a chave agora recebe403 MACHINE_CANNOT_GRANT_ROLE. Confiraiam.organizations.typeda organização da chave. 202onde se esperava201. A organização tem a política ligada e o papel é sensível (ou a chave escreve). O corpo traz o pedido emdataemeta.approvalRequired: true; a tela deve mostrar "aguardando aprovação", não erro.- Trocar papel com quatro olhos: mande
replacesRoleIdnoPOST. FazerPOST+DELETEseparados tira o papel antigo enquanto o novo ainda espera aprovação. - "Liguei a regra e voltou 409
APPROVERS_INSUFFICIENT." Há menos de duas pessoas que conseguem aprovar o desligamento. DêADMINouIAM_MANAGERa outra pessoa que já entrou ao menos uma vez (o convidado conta depois do primeiro login). - "A organização tem um admin só e a regra está ligada (ficou presa)." Desligue: com menos de dois aprovadores o
PUT { approvalRequired: false }vale na hora e cancela os pendentes. - "Não consigo tirar o papel de outro admin: 409
APPROVER_QUORUM_PROTECTED." Ele é o penúltimo aprovador com a regra ligada. Promova outra pessoa antes, ou peça para desligar a regra; se o outro admin saiu da empresa, o operador (root) remove. - "O pedido sumiu da fila." Venceu. A listagem (
GET /access-requests) varre antes de ler: pendente — ou chave aprovada e não resgatada — com prazo passado é GRAVADOEXPIRED, com eventoiam.access-request.expiredsem autor (quem expira é o relógio), em lotes de 100. Não há agendador: pedido vencido que ninguém lista ficaPENDINGno banco, mas nenhuma decisão ou resgate passa (todos conferem o prazo na reivindicação). 409ao cancelar um pedido de papel aprovado: só o pedido de CHAVE aprovado se cancela (espera o resgate); os outros executam na própria aprovação.- "O gerente de acesso não consegue mais trocar a senha de alguém." Regra 5: o alvo tem papel sensível que ele não poderia conceder, ou é de outra organização também. Quem troca é um
ADMINda organização, root, ou o painel pela chavedono. - Aprovação travada em
APPROVEDnum pedido que não é de chave: o processo caiu entre aprovar e executar. Não reexecuta sozinho; trate pela trilha (approvedsemexecuted/failed). - Apagar organização em teste falha com
access_requests_organization_id_fkey: a FK éRESTRICTde propósito (o pedido é trilha). LimpeaccessRequestantes deorganization. - Rodar a integração dentro de
node:22(sem socket do Docker): subapostgres:16-alpineeredis:7-alpineao lado e passeINTEGRATION_DATABASE_URL(o setup não sobe container quando ela existe).REDIS_URLvem detests/setup.ts(localhost:6379), e ovitest.integration.config.tsnão carrega esse arquivo: use uma config que acrescentesetupFiles: ['./tests/setup.ts'], e definaS3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY(o container exige). Com banco compartilhado entre suítes, resíduo de uma segura FK da outra. - Já falham na
main, sem relação com isto:tests/integration/api-keys(5 testes de rotação) etests/unit/shared/config/env.test.ts(WPP_SESSION_WORKER_ENABLED).
OAuth 2.0 — /iam/oauth
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /iam/oauth/token | client_credentials ou refresh_token | Pública (com rate limit) |
POST | /iam/oauth/revoke | Revoga um refresh token | Pública |
Saúde
| Método | Rota | Descrição |
|---|---|---|
GET | /iam/health | Sonda banco, criptografia e round-trip de JWT. 503 se algum falhar. |
Endpoints principais em detalhe
Os dois endpoints abaixo são os que um integrador usa primeiro. O caminho é o mesmo nos dois: credencial entra, token sai.
sequenceDiagram participant Cli as Cliente participant RL as authRateLimitMiddleware participant Auth as AuthService participant DB as PostgreSQL participant Log as logSecurityEvent Cli->>RL: POST /users/login ou /oauth/token RL-->>Cli: 429 se o limite estourou RL->>Auth: credenciais Auth->>DB: busca usuário ou organização DB-->>Auth: registro + hash Auth->>Auth: verifica hash e resolve permissões Auth->>Log: LOGIN_SUCCESS / LOGIN_FAILURE / OAUTH_TOKEN_FAILURE Auth-->>Cli: 200 com token, ou 401
POST /iam/api/v1/users/login
Autentica por e-mail e senha. Rota pública, protegida por rate limit; sucesso e falha vão para o log de segurança.
Request
{
"email": "admin@catalisa.app",
"password": "senha-do-usuario",
"organizationId": "2194956a-2d0a-4203-89a3-933319d80fa1"
}{
"email": "admin@catalisa.app",
"password": "senha-do-usuario",
"organizationId": "2194956a-2d0a-4203-89a3-933319d80fa1"
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
email | string (e-mail) | Sim | E-mail do usuário |
password | string (máx. 128) | Sim | Senha em texto puro, sobre TLS |
organizationId | string | Não | Aceita UUID ou slug. Omitido, o serviço resolve a organização do usuário. Necessário quando o usuário pertence a mais de uma. |
Resposta 200
{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "b1000000-0000-0000-0000-000000000001",
"email": "admin@catalisa.app",
"status": "ativo"
}
}{
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "b1000000-0000-0000-0000-000000000001",
"email": "admin@catalisa.app",
"status": "ativo"
}
}Resposta 200 quando há segundo fator devido — sem token e sem dados do usuário:
{
"mfaRequired": true,
"enrollmentRequired": false,
"challengeToken": "q0V8…(opaco, 43 caracteres)",
"expiresIn": 300
}{
"mfaRequired": true,
"enrollmentRequired": false,
"challengeToken": "q0V8…(opaco, 43 caracteres)",
"expiresIn": 300
}O cliente troca o challengeToken pelo par de tokens em POST /iam/api/v1/users/login/mfa (ou, com enrollmentRequired: true, em …/login/mfa/enroll e …/login/mfa/enroll/confirm). Um cliente que lia accessToken direto precisa tratar este caso.
Claims do access token
| Claim | Descrição |
|---|---|
sub | ID do usuário |
email | |
type | access ou refresh |
organizationId | Organização do contexto — o tenant efetivo da requisição |
permissions | Lista de permissões já resolvida |
isRoot | true só para operador de plataforma |
amr | Como a pessoa entrou: ["pwd"], ["pwd","otp","mfa"] ou ["pwd","mfa"] (código de recuperação). Preservado na renovação |
exp | Expiração — JWT_EXPIRES_IN, padrão 3600s |
Erros
| Status | Quando |
|---|---|
400 | Corpo não passa no schema Zod |
401 | Credenciais inválidas, usuário não ativo, ou sem acesso à organização informada |
429 | Rate limit de autenticação estourado |
POST /iam/oauth/token
Endpoint OAuth 2.0. Suporta client_credentials (M2M) e refresh_token.
Request — client_credentials
{
"grant_type": "client_credentials",
"client_id": "2194956a-2d0a-4203-89a3-933319d80fa1",
"client_secret": "cs_live_...",
"scope": "CUSTOMERS_READ CUSTOMERS_CREATE"
}{
"grant_type": "client_credentials",
"client_id": "2194956a-2d0a-4203-89a3-933319d80fa1",
"client_secret": "cs_live_...",
"scope": "CUSTOMERS_READ CUSTOMERS_CREATE"
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
grant_type | client_credentials | refresh_token | Sim | Fluxo |
client_id | string | Em client_credentials | É o organizationId |
client_secret | string | Em client_credentials | Segredo gerado na rota de client-secret |
scope | string | Não | Permissões separadas por espaço. Omitido, o token recebe todas as permissões da organização. |
refresh_token | string | Em refresh_token | O refresh token a trocar |
O scope só reduz: pedir uma permissão que a organização não contratou não a concede. O filtro está em filterScopedPermissions.
Resposta 200
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "CUSTOMERS_READ CUSTOMERS_CREATE"
}{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "CUSTOMERS_READ CUSTOMERS_CREATE"
}Atenção. No fluxo refresh_token a resposta traz também um refresh_token novo: o token apresentado é consumido na hora (uso único) e substituído por outro. Guarde o novo valor — reapresentar o antigo devolve 400 invalid_grant e registra REFRESH_TOKEN_REPLAY_ATTEMPT no log de segurança. O expires_in vem de OAUTH_ACCESS_TOKEN_TTL, e não de JWT_EXPIRES_IN.
Erros — formato OAuth 2.0, não o envelope padrão da plataforma.
| Status | error | Quando |
|---|---|---|
400 | unsupported_grant_type | grant_type fora dos suportados |
401 | invalid_client | client_id/client_secret ausente ou inválido |
400 | invalid_grant | Refresh token ausente, inválido, expirado, revogado ou já consumido |
500 | server_error | Falha ao emitir o novo refresh token na rotação |
429 | — | Rate limit estourado |
O serviço não distingue organização inexistente de segredo errado — ambos retornam
invalid_client. É proposital: distinguir permitiria enumerar organizações.
POST /iam/api/v1/organizations/:organizationId/client-secret
Gera ou rotaciona o segredo M2M. O valor é retornado uma única vez; o banco guarda apenas o hash.
Resposta 200
{
"clientId": "2194956a-2d0a-4203-89a3-933319d80fa1",
"clientSecret": "cs_live_8f3a...",
"warning": "Guarde este segredo agora. Ele não será exibido novamente."
}{
"clientId": "2194956a-2d0a-4203-89a3-933319d80fa1",
"clientSecret": "cs_live_8f3a...",
"warning": "Guarde este segredo agora. Ele não será exibido novamente."
}Rotacionar invalida o segredo anterior de imediato — coordene com o parceiro antes de chamar.
Início rápido
Do zero a uma chamada autenticada em um building block tenant-scoped, em quatro passos.
sequenceDiagram autonumber participant Você participant IAM participant Cust as Customers Você->>IAM: POST /users/login (e-mail, senha, organizationId) IAM-->>Você: accessToken + refreshToken Você->>Você: decodifica o payload e confere organizationId Você->>Cust: GET /persons com Bearer Cust-->>Você: só os clientes da sua organização Você->>Cust: GET /persons com token inválido Cust-->>Você: 401
1. Autenticar
TOKEN=$(curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/users/login \
-H "Content-Type: application/json" \
-d '{
"email": "admin@catalisa.app",
"password": "password123",
"organizationId": "2194956a-2d0a-4203-89a3-933319d80fa1"
}' | jq -r .accessToken)
echo "${TOKEN:0:32}..."TOKEN=$(curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/users/login \
-H "Content-Type: application/json" \
-d '{
"email": "admin@catalisa.app",
"password": "password123",
"organizationId": "2194956a-2d0a-4203-89a3-933319d80fa1"
}' | jq -r .accessToken)
echo "${TOKEN:0:32}..."Resposta esperada — o começo de um JWT, prova de que a variável foi preenchida:
eyJhbGciOiJIUzI1NiIsInR5cCI6Ik...eyJhbGciOiJIUzI1NiIsInR5cCI6Ik...2. Inspecionar o que o token carrega
echo "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jqecho "$TOKEN" | cut -d. -f2 | base64 -d 2>/dev/null | jq{
"sub": "b1000000-0000-0000-0000-000000000001",
"email": "admin@catalisa.app",
"type": "access",
"organizationId": "2194956a-2d0a-4203-89a3-933319d80fa1",
"permissions": ["IAM_USERS_READ", "CUSTOMERS_READ", "..."],
"exp": 1755400000
}{
"sub": "b1000000-0000-0000-0000-000000000001",
"email": "admin@catalisa.app",
"type": "access",
"organizationId": "2194956a-2d0a-4203-89a3-933319d80fa1",
"permissions": ["IAM_USERS_READ", "CUSTOMERS_READ", "..."],
"exp": 1755400000
}O organizationId aqui é o tenant efetivo. Todo building block tenant-scoped vai ler daqui — nunca do corpo da sua requisição.
3. Usar o token em outro building block
curl -s https://customers.stg.catalisa.app/customers/api/v1/persons \
-H "Authorization: Bearer $TOKEN" | jq '.data | length'curl -s https://customers.stg.catalisa.app/customers/api/v1/persons \
-H "Authorization: Bearer $TOKEN" | jq '.data | length'Resposta esperada — a contagem de clientes visíveis para a sua organização:
1212Nenhum organizationId na chamada, e ainda assim só vêm os clientes da sua organização.
4. Confirmar que o isolamento é real
curl -s -o /dev/null -w "%{http_code}\n" \
https://customers.stg.catalisa.app/customers/api/v1/persons \
-H "Authorization: Bearer token-invalido"curl -s -o /dev/null -w "%{http_code}\n" \
https://customers.stg.catalisa.app/customers/api/v1/persons \
-H "Authorization: Bearer token-invalido"Retorna 401. Não há caminho em que a ausência de token válido resulte em dado.
Credenciais de staging. Nunca use credencial de produção em documentação ou script de exemplo — ver AMBIENTES.md.
Receitas
Criar uma organização e o primeiro administrador dela
Objetivo. Provisionar um cliente novo do zero: organização, usuário administrador e o vínculo entre os dois. Exige um token com permissões de IAM.
flowchart LR A["1. POST /organizations"] --> B["2. POST /users"] B --> C["3. GET /roles<br/>descobrir o id de ADMIN"] C --> D["4. POST /associations<br/>usuário + organização + papel"] D --> E["5. PATCH /users/:id<br/>status ativo"] E --> F["Administrador consegue autenticar"]
1. Criar a organização
ORG=$(curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/organizations \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"Financeira Exemplo","slug":"financeira-exemplo","type":"cliente"}')
ORG_ID=$(echo "$ORG" | jq -r '.data.id')
echo "$ORG_ID"ORG=$(curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/organizations \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"Financeira Exemplo","slug":"financeira-exemplo","type":"cliente"}')
ORG_ID=$(echo "$ORG" | jq -r '.data.id')
echo "$ORG_ID"Resposta esperada — o UUID da organização recém-criada:
3f6c1a02-7f4b-4c2e-9a11-0d6f9b3f1c773f6c1a02-7f4b-4c2e-9a11-0d6f9b3f1c772. Criar o usuário
USER=$(curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/users \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"email":"admin@financeira-exemplo.com.br","password":"UmaSenhaForte!2026"}')
USER_ID=$(echo "$USER" | jq -r '.data.id')
echo "$USER" | jq '.data | {id, email, status}'USER=$(curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/users \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"email":"admin@financeira-exemplo.com.br","password":"UmaSenhaForte!2026"}')
USER_ID=$(echo "$USER" | jq -r '.data.id')
echo "$USER" | jq '.data | {id, email, status}'Resposta esperada — repare no status, que nasce pendente:
{
"id": "8a2f0e11-4d3b-4f18-8f0a-3b6b2c9e4d55",
"email": "admin@financeira-exemplo.com.br",
"status": "pendente"
}{
"id": "8a2f0e11-4d3b-4f18-8f0a-3b6b2c9e4d55",
"email": "admin@financeira-exemplo.com.br",
"status": "pendente"
}3. Descobrir o papel
ROLE_ID=$(curl -s https://iam.stg.catalisa.app/iam/api/v1/roles \
-H "Authorization: Bearer $TOKEN" | jq -r '.data[] | select(.name=="ADMIN") | .id')
echo "$ROLE_ID"ROLE_ID=$(curl -s https://iam.stg.catalisa.app/iam/api/v1/roles \
-H "Authorization: Bearer $TOKEN" | jq -r '.data[] | select(.name=="ADMIN") | .id')
echo "$ROLE_ID"Resposta esperada — Role.id é inteiro, não UUID:
114. Associar usuário + organização + papel
curl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/associations \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d "{\"userId\":\"$USER_ID\",\"organizationId\":\"$ORG_ID\",\"roleId\":$ROLE_ID}" | jqcurl -s -X POST https://iam.stg.catalisa.app/iam/api/v1/associations \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d "{\"userId\":\"$USER_ID\",\"organizationId\":\"$ORG_ID\",\"roleId\":$ROLE_ID}" | jqResposta esperada — o vínculo criado, com a chave composta dos três identificadores.
5. Ativar o usuário
curl -s -X PATCH "https://iam.stg.catalisa.app/iam/api/v1/users/$USER_ID" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"status":"ativo"}' | jq '.data.status'curl -s -X PATCH "https://iam.stg.catalisa.app/iam/api/v1/users/$USER_ID" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"status":"ativo"}' | jq '.data.status'Resposta esperada:
"ativo""ativo"Armadilhas.
- O usuário nasce
pendentee não autentica até virarativo— faça oPATCHde status ou o login falha com401e ninguém entende por quê. - Sem a associação do passo 4, o login retorna
401mesmo com senha correta: usuário sem organização não tem contexto. - A organização precisa ter as permissões contratadas em
OrganizationPermission. PapelADMINnuma organização sem permissões de Billing não concede nenhuma permissão de Billing — a organização é o teto. - O
slugé único globalmente. Colisão retorna409.
Entregar credencial M2M a um parceiro
Objetivo. Dar a um parceiro acesso programático com escopo mínimo, sem senha de usuário no meio.
sequenceDiagram participant Você participant IAM participant Parc as Parceiro Você->>IAM: POST /organizations/:id/client-secret IAM-->>Você: clientId + clientSecret (uma única exibição) Você->>Parc: entrega por canal seguro (SOPS) Parc->>IAM: POST /oauth/token com scope reduzido IAM-->>Parc: access_token de 1 hora
1. Gerar o segredo
curl -s -X POST \
"https://iam.stg.catalisa.app/iam/api/v1/organizations/$ORG_ID/client-secret" \
-H "Authorization: Bearer $TOKEN" | jqcurl -s -X POST \
"https://iam.stg.catalisa.app/iam/api/v1/organizations/$ORG_ID/client-secret" \
-H "Authorization: Bearer $TOKEN" | jqResposta esperada — o clientSecret só aparece aqui, nunca mais:
{
"clientId": "3f6c1a02-7f4b-4c2e-9a11-0d6f9b3f1c77",
"clientSecret": "cs_live_8f3a...",
"warning": "Guarde este segredo agora. Ele não será exibido novamente."
}{
"clientId": "3f6c1a02-7f4b-4c2e-9a11-0d6f9b3f1c77",
"clientSecret": "cs_live_8f3a...",
"warning": "Guarde este segredo agora. Ele não será exibido novamente."
}2. O parceiro troca a credencial por um token
O parceiro usa assim:
curl -s -X POST https://iam.stg.catalisa.app/iam/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "'"$ORG_ID"'",
"client_secret": "cs_live_...",
"scope": "CUSTOMERS_READ"
}' | jq -r .access_tokencurl -s -X POST https://iam.stg.catalisa.app/iam/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "'"$ORG_ID"'",
"client_secret": "cs_live_...",
"scope": "CUSTOMERS_READ"
}' | jq -r .access_tokenArmadilhas.
- O segredo aparece uma vez. Perdeu, rotaciona — não tem recuperação.
- Rotacionar derruba a integração do parceiro na hora. Combine a janela antes.
- Sempre passe
scope. Sem ele o token recebe todas as permissões da organização, o que é o oposto de privilégio mínimo. - Guarde o segredo com SOPS, nunca em
.envversionado — ver SECRETS-SOPS-REFERENCE.md.
Renovar o access token sem novo login
Objetivo. Manter a sessão viva por até sete dias sem pedir senha de novo.
sequenceDiagram participant App participant IAM App->>IAM: POST /oauth/token (grant_type refresh_token) IAM->>IAM: valida e rotaciona o refresh token IAM-->>App: novo access_token (1h) Note over App: renove antes de expirar,<br/>não depois de receber 401
curl -s -X POST https://iam.stg.catalisa.app/iam/oauth/token \
-H "Content-Type: application/json" \
-d '{"grant_type":"refresh_token","refresh_token":"'"$REFRESH"'"}' | jqcurl -s -X POST https://iam.stg.catalisa.app/iam/oauth/token \
-H "Content-Type: application/json" \
-d '{"grant_type":"refresh_token","refresh_token":"'"$REFRESH"'"}' | jqResposta esperada — repare que vem um refresh token novo: o antigo foi consumido e não serve mais.
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"scope": null
}{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"scope": null
}Armadilhas.
- O refresh token vive
JWT_REFRESH_EXPIRES_IN(padrão 7 dias). - Renove antes de o access token expirar, não depois de a chamada falhar — tratar
401como gatilho de renovação gera tempestade de renovação quando o serviço tem concorrência. - O refresh token é de uso único e rotaciona a cada troca. Guarde o novo valor devolvido na resposta; reapresentar o antigo devolve
400 invalid_grante gera um eventoREFRESH_TOKEN_REPLAY_ATTEMPTno log de segurança.
Descobrir por que uma requisição voltou 403
Objetivo. Isolar, em quatro perguntas, qual das camadas negou a requisição. Siga na ordem — cada pergunta elimina uma causa.
flowchart TD
Q1{"A permissão existe<br/>no vocabulário?"}
Q1 -->|não| F1["Erro de grafia<br/>confira em /permissions/all"]
Q1 -->|sim| Q2{"A organização contratou?"}
Q2 -->|não| F2["Falta OrganizationPermission<br/>a organização é o teto"]
Q2 -->|sim| Q3{"O papel concede?"}
Q3 -->|não| F3["Troque o papel da Association"]
Q3 -->|sim| Q4{"O token foi emitido<br/>depois da mudança?"}
Q4 -->|não| F4["Causa mais comum:<br/>reemita o token"]
Q4 -->|sim| F5["Investigue o requirePermission da rota"]1. O que o token realmente carrega
echo "$TOKEN" | cut -d. -f2 | base64 -d | jq '.permissions, .organizationId'echo "$TOKEN" | cut -d. -f2 | base64 -d | jq '.permissions, .organizationId'Resposta esperada — a lista de permissões e o tenant efetivo do token:
["IAM_USERS_READ", "CUSTOMERS_READ"]
"2194956a-2d0a-4203-89a3-933319d80fa1"["IAM_USERS_READ", "CUSTOMERS_READ"]
"2194956a-2d0a-4203-89a3-933319d80fa1"2. O que a organização contratou
curl -s https://iam.stg.catalisa.app/iam/api/v1/permissions \
-H "Authorization: Bearer $TOKEN" | jqcurl -s https://iam.stg.catalisa.app/iam/api/v1/permissions \
-H "Authorization: Bearer $TOKEN" | jqSe a permissão não aparecer aqui, nenhum papel vai concedê-la — a organização é o teto.
3. O vocabulário completo, para conferir a grafia exata
curl -s https://iam.stg.catalisa.app/iam/api/v1/permissions/all \
-H "Authorization: Bearer $TOKEN" | jqcurl -s https://iam.stg.catalisa.app/iam/api/v1/permissions/all \
-H "Authorization: Bearer $TOKEN" | jqArmadilhas. A quarta pergunta do diagrama é a causa mais comum: permissões são resolvidas na emissão do token, então mudança de papel ou de contrato só vale no próximo token — até uma hora depois, com o padrão de JWT_EXPIRES_IN.
Integração com outros building blocks
| Building block | Como se relaciona | Obrigatório |
|---|---|---|
| Todos os 31 demais | Verificam o token emitido aqui via authMiddleware | Sim |
| API Keys | Alternativa ao JWT para acesso programático de longa duração | Não |
| SSO | Identidade federada (login social, provedores externos) apoiada no IAM | Não |
| Audit Trail | Registra o que cada identidade fez; o IAM define quem ela é | Não |
| Webhooks Engine | Escopa entrega de eventos por organização | Não |
flowchart TD U["Usuário"] -->|"login"| IAM P["Parceiro"] -->|"client_credentials"| IAM IAM["IAM<br/>emite access + refresh token"] -->|"Bearer JWT"| C["Customers"] IAM -->|"Bearer JWT"| PY["Payments"] IAM -->|"Bearer JWT"| CM["Commerce"] IAM -->|"Bearer JWT"| B["Billing"] IAM -->|"Bearer JWT"| O["...os outros 27"] C --> N["Todos leem organizationId do token,<br/>nunca do corpo"] PY --> N CM --> N B --> N O --> N
Este diagrama é o argumento comercial da Catalisa em uma imagem: a autorização é resolvida uma vez, na borda, e vale para o catálogo inteiro. Um provedor de identidade externo pararia na primeira seta.
Configuração e operação
Variáveis de ambiente
| Variável | Descrição | Obrigatória | Padrão |
|---|---|---|---|
JWT_SECRET | Segredo HS256. Mínimo 44 caracteres — o serviço não sobe abaixo disso. Gere com openssl rand -base64 32. | Sim | — |
JWT_EXPIRES_IN | Vida do access token, em segundos | Não | 3600 |
JWT_REFRESH_EXPIRES_IN | Vida do refresh token, em segundos | Não | 604800 |
OAUTH_ACCESS_TOKEN_TTL | expires_in devolvido por /oauth/token, em segundos | Não | 3600 |
DATABASE_URL | PostgreSQL | Sim | — |
REDIS_URL | Redis, usado no rate limit | Sim | — |
DEPLOYMENT_MODE | monolith ou standalone | Não | monolith |
IAM_MFA_MASTER_KEY | Chave do segredo TOTP em repouso (64 hex). Sem ela o IAM sobe e a senha funciona; as rotas de segundo fator respondem 503 MFA_NOT_CONFIGURED. Perdê-la obriga reset de todo fator. Gere com openssl rand -hex 32. | Para MFA | — |
IAM_MFA_ISSUER | Nome que o app autenticador mostra ao lado da conta | Não | Catalisa |
Dependências de infraestrutura
| Dependência | Para quê |
|---|---|
| PostgreSQL | Schema iam — usuários, organizações, associações, refresh tokens |
| Redis | Contadores de rate limit das rotas de autenticação; desafios de segundo fator (só o hash, com TTL) |
Limites
| Limite | Valor |
|---|---|
| Comprimento da senha no login | 128 caracteres |
Comprimento mínimo do JWT_SECRET | 44 caracteres |
| Rate limit de autenticação | Definido em authRateLimitMiddleware |
| Vida do access token | 1 hora (padrão) |
| Vida do refresh token | 7 dias (padrão) |
| Desafio de segundo fator | 5 min (verificação) · 15 min (cadastro) · 5 respostas erradas por desafio |
| Bloqueio do segundo fator | 5 códigos errados seguidos → 15 min, contados no banco, entre desafios |
| Janela do TOTP | ±1 passo de 30 s; cada passo vale uma vez |
Catálogo de erros
| Status | Código | Significa | O que fazer |
|---|---|---|---|
400 | VALIDATION | Corpo reprovado no Zod | Confira campos e tipos contra §9 |
401 | UNAUTHORIZED | Token ausente, inválido ou expirado | Renove pelo refresh token |
401 | invalid_client | Credencial M2M inválida (ou organização inexistente) | Confira client_id e rotacione o segredo |
403 | FORBIDDEN | Token válido, permissão faltando | Siga a receita "por que voltou 403" em §11 |
403 | — | Building block tenant-scoped sem organizationId no token | Autentique informando a organização |
404 | NOT_FOUND | Recurso inexistente ou excluído logicamente | Confira o ID |
409 | CONFLICT | E-mail ou slug já em uso | Escolha outro |
429 | — | Rate limit de autenticação | Aplique recuo exponencial |
401 | MFA_INVALID_CODE | Código errado, já usado, ou código de recuperação inválido (details.attemptsLeft) | Peça o próximo código do app |
401 | MFA_CHALLENGE_INVALID | Desafio expirado, já usado, esgotado ou do tipo errado | Volte para a senha |
429 | MFA_LOCKED | 5 códigos errados (details.retryAfterSeconds) | Espere, ou peça reset a um admin |
409 | MFA_ALREADY_ENROLLED / MFA_NOT_ENROLLED | Cadastro repetido / nada a verificar | Reset por admin / cadastre |
403 | MFA_SELF_RESET | Admin tentando resetar o próprio fator | Outro admin |
503 | MFA_NOT_CONFIGURED | Falta IAM_MFA_MASTER_KEY | Configure a chave |
503 | — | /health reprovou banco, cripto ou JWT | Verifique Postgres e JWT_SECRET |
Observabilidade.
GET /iam/healthvalida conectividade com o banco, o subsistema de senha e um round-trip completo de assinar/verificar JWT. Responde503se qualquer um falhar — é a sonda certa para orquestrador.logSecurityEventregistraLOGIN_SUCCESS,LOGIN_FAILUREeOAUTH_TOKEN_FAILUREcom IP, user-agent e motivo. É a base para detectar força bruta e credencial M2M vazada.- O segundo fator publica na trilha (
iam-events→ Audit Trail, recursouser_mfa):iam.mfa.enrollmentStarted,iam.mfa.enrolled,iam.mfa.success,iam.mfa.failure(comreason:INVALID_CODE,CODE_REUSED,INVALID_RECOVERY_CODE,LOCKED,NOT_ENROLLED,ALREADY_ENROLLED,SELF_RESET,NOT_CONFIGURED),iam.mfa.locked,iam.mfa.recoveryCodeUsedeiam.mfa.reset(comreasoneresetBy). Nenhum evento nem linha de log carrega segredo, código ou código de recuperação. - O
JwtService.preflight()roda no startup e derruba o boot com segredo malformado.
Segurança e compliance
Isolamento entre tenants
O organizationId é claim assinado no JWT. Building blocks tenant-scoped aplicam requireOrganization, que devolve 403 quando o claim está ausente. Building blocks com dado sensível somam Row-Level Security no Postgres como segunda camada, para que uma falha de aplicação não baste para vazar.
flowchart LR T["JWT assinado<br/>organizationId"] --> M["requireOrganization"] Body["Corpo da requisição"] -.->|"nunca é lido<br/>como fonte de tenant"| X["✕"] M --> A["Regra de negócio"] A --> RLS["Row-Level Security<br/>nos BBs com dado sensível"]
Atenção. Nenhuma rota lê organizationId do corpo da requisição — essa é a invariante que sustenta o isolamento, e qualquer código novo que a viole é bug de segurança, não escolha de estilo.
Credenciais em repouso
| O que | Como é guardado | Regras |
|---|---|---|
| Senhas | Hash pelo PasswordService compartilhado | Nunca retornadas, nunca logadas. O login limita a senha a 128 caracteres para evitar abuso de custo de hashing |
| Segredos M2M | Hash em clientSecretHash | Exibidos uma única vez, rotacionáveis por API. A verificação não distingue organização inexistente de segredo errado — deliberadamente, para não permitir enumeração |
| Segredo TOTP | Cifrado (aes-256-gcm, credential-crypto) com IAM_MFA_MASTER_KEY | Exibido uma vez no cadastro (QR e texto). Coberto pelo rotate-master-keys.ts |
| Códigos de recuperação | SHA-256 de 80 bits aleatórios | Exibidos uma vez. Cada um vale uma vez — o uso é reivindicado com UPDATE condicional |
| Desafio de segundo fator | SHA-256 no Redis, com TTL | Opaco, não é JWT: nenhum bloco o aceita como token |
Tokens
HS256, expiração curta no access token, refresh revogável. JWT_SECRET abaixo de 256 bits impede o boot. Padrões fracos comuns geram alerta em produção.
Renovação re-resolve o escopo. O refresh token carrega a organização do login; a cada grant_type=refresh_token o IAM relê o usuário e os papéis atuais nessa organização. Usuário desativado, excluído ou sem papel na organização desde o login recebe invalid_grant e a recusa vai à trilha (security.token.refused, reason USER_INACTIVE ou ORGANIZATION_ACCESS_REVOKED). amr é copiado do refresh como está — a renovação nunca promove a forma de entrada. Refresh emitido antes desta regra (sem organização) renova sem escopo, como antes: o cliente que exige organização pede novo login uma vez.
Superfície de ataque de autenticação
Login e emissão de token passam por rate limit e vão para o log de segurança com IP e user-agent.
Segundo fator
- Reúso impossível. Cada código TOTP vale uma vez: o passo usado é gravado com
UPDATE … WHERE last_used_step < passo, e só uma requisição vence — dois logins simultâneos com o mesmo código recebem um token e uma recusa (teste de corrida emtests/integration/iam/mfa.integration.test.ts). Código mais antigo que o último usado também é recusado. - Bloqueio. 5 erros seguidos travam o fator por 15 minutos, no banco, entre desafios; cada desafio aceita 5 respostas. O bloqueio vale até para o código certo.
- Reset só por outro admin, com motivo, evento
iam.mfa.resete revogação de todos os refresh tokens do usuário.PATCH mfaEnableddeixou de existir: a flag só espelha o fator confirmado. - A renovação não rebaixa nem promove. O
amrviaja no refresh token e passa para o access token renovado.
Exclusão lógica
Usuários e organizações usam deletedAt. O histórico sobrevive à remoção, que é o que auditoria e obrigação de retenção exigem.
LGPD
O IAM guarda e-mail e hash de senha — e-mail é dado pessoal. Exclusão é lógica por padrão; atender a pedido de eliminação exige processo explícito de expurgo, que hoje não é automatizado (ver §15).
Limitações conhecidas
| Limitação | Impacto | Situação |
|---|---|---|
| Segundo fator é só TOTP | Sem WebAuthn/passkey, SMS ou e-mail. Códigos de recuperação não se regeneram sem reset | Roadmap |
Os blocos não exigem amr | O segundo fator é exigido por quem o pede: o console do banco confere mfa no token; uma chamada direta ao baas com token só de senha ainda passa. Para obrigar TODA entrada, ligue mfaRequired na organização | Por design nesta fatia |
| Clientes sem tela de segundo fator | Usuário com fator confirmado recebe desafio em todo login; um cliente que não trata mfaRequired (ex.: o painel) não consegue entrar com esse usuário | Use contas separadas ou implemente o segundo passo no cliente |
| Sem login social ou SAML | Autenticação é e-mail e senha ou M2M | Por design — é o building block SSO |
| Sem tela de login hospedada | O cliente constrói a própria interface | Por design |
| Permissões resolvidas na emissão | Mudança de papel só vale no próximo token (até 1h) | Por design — o trade-off que mantém a verificação sem tocar o banco |
| Sem recuperação de senha por e-mail | Reset é PATCH administrativo | Roadmap |
| Sem expurgo automatizado para LGPD | Exclusão é lógica; eliminação definitiva é manual | Roadmap |
| HS256 com segredo compartilhado | Qualquer serviço com o segredo pode emitir token, não só verificar | Por design enquanto todos os consumidores forem internos |
| Sem cadastro self-service | Organização e usuário são criados por quem já tem permissão de IAM | Especificado, não implementado — ver a página de cadastro em docs.catalisa.app |
Perguntas frequentes
Preciso do IAM se já uso Auth0 na minha empresa?
Sim, mas os papéis são diferentes. O Auth0 continua autenticando seus usuários; o IAM é quem os building blocks consultam para saber a organização e as permissões. A integração natural é o SSO federar o Auth0 e o IAM emitir o token que o resto da plataforma entende.
Um usuário pode pertencer a mais de uma empresa?
Pode. Association é uma tabela com chave composta de usuário, organização e papel — a mesma pessoa pode ser ADMIN numa e VIEWER em outra. No login, informe organizationId para escolher o contexto; sem isso o serviço não tem como adivinhar qual você quer.
O que acontece se o token vazar?
Ele vale até expirar — uma hora por padrão. Não há revogação de access token individual, por design: revogar exigiria consultar o banco a cada requisição. Se o vazamento for confirmado, o caminho é revogar o refresh token e, no limite, rotacionar o JWT_SECRET, o que invalida todos os tokens de uma vez.
Dá para usar em produção com autenticação só por senha?
Depende do seu risco. Há segundo fator TOTP nativo (§8, §14): ligue mfaRequired na organização para exigi-lo em todo login, e confira amr contendo mfa no cliente que precisa dele.
Qual a diferença entre o IAM e o API Keys?
O IAM autentica identidades — pessoas e organizações — com token de vida curta. O API Keys emite credencial de longa duração para acesso programático, com rastreio de uso próprio. Integração que roda continuamente e precisa de escopo dinâmico usa M2M do IAM; integração simples com credencial estática usa API Keys.
Por que o organizationId do login aceita slug?
Conveniência de integração. Slug é legível e estável (financeira-exemplo), o que evita carregar UUID em script de setup e documentação. A resolução acontece no AuthService, e o token sempre carrega o UUID.
Como funciona o acesso do operador de plataforma?
Pelo claim isRoot. Contas root acessam entre organizações nas rotas que, para todos os outros, exigem que o recurso pertença à organização do token. É um privilégio elevado, deve ficar restrito a poucas contas, e todo uso deve ser acompanhado pelo Audit Trail.
Adicionar um building block novo exige mudar o IAM?
Não. O building block novo declara as permissões dele no vocabulário compartilhado e usa o requirePermission de sempre. O IAM não precisa saber o que o Commerce faz — só precisa carregar as strings no token.
Padrão: PADRAO-DOCUMENTACAO.md · Índice: INDEX.md