Identity Management

Visão geral

O Identity Management é o centro de identidade, autorização e tenancy do ecossistema. Ele não é uma tela de login: é a fundação de segurança que permite que vários sistemas compartilhem a mesma base de usuários, contratos, permissões e sessões, sem reimplementar autenticação em cada produto.

Concretamente, ele modela a relação entre:

• usuários (identidade base, senha com hash BCrypt);
• empresas;
• aplicações que consomem o IAM (audience, redirect URIs e as credenciais OAuth de cada uma);
• contratos (empresa mais aplicação, com vigência, o tenant real);
• papéis de acesso vinculados ao contrato, a partir de modelos padrão por sistema;
• recursos protegidos (catálogo central de capacidades e permissões);
• vínculos entre usuários e papéis;
• sessões autenticadas, revogáveis individualmente ou em massa;
• access token, ID token e refresh token rotativo, guardados como hash;
• tenants (banco e segredo de integração por contrato).

Dois papéis na arquitetura

O sistema ocupa duas posições ao mesmo tempo, e é isso que o torna o ponto mais sensível do monorepo.

Como consumidor do framework base (Archon), ele herda pipeline HTTP, multi-tenant, persistência, auditoria automática e autorização por convenção. Como dependência de todos os outros sistemas, ele emite os tokens, valida as sessões, resolve qual tenant atende cada requisição e expõe o catálogo de permissões que as demais APIs consomem. Em outras palavras: se ele para, o ecossistema inteiro para.

Login

O usuário se identifica com suas credenciais, mas a autenticação não termina numa resposta de "autenticado ou não": todo acesso passa pelo fluxo OIDC completo, com seleção de contrato quando há mais de um antes da emissão do código de autorização.

Esse detalhe é central. O acesso não depende só do usuário existir. A identidade só vira sessão quando casa com um contrato vigente, e é o contrato que define qual sistema, qual empresa e quais regras de acesso valem ali.

Central de Sistemas

Quando o usuário tem mais de um contrato, a autenticação não termina no login: o sistema devolve uma etapa de seleção de contexto. A Central de Sistemas é a materialização disso na interface, a porta de entrada onde o usuário escolhe em qual sistema, sob qual contrato, quer entrar.

A escolha não é cosmética. Ela determina qual aplicação recebe o token, com qual audiência e quais permissões. O mesmo usuário pode ser administrador em um contexto e ter acesso restrito em outro, com a mesma credencial.

Autenticação por baixo dos panos

Por trás dessas telas existe a parte que realmente faz o sistema valer como projeto de engenharia.

Um único fluxo, OIDC com PKCE obrigatório. Não existe um atalho de login direto por API que pule o provedor de identidade. O fluxo é authorization code com PKCE (S256) sempre exigido, discovery em /.well-known/openid-configuration e jwks.json, e os endpoints padrão de authorize, token, userinfo, revocation e logout. A identificação e a seleção de contrato acontecem na tela hospedada de login, antes do código de autorização ser emitido; o código é de uso único, invalidado atomicamente na troca por token.

Chave de assinatura global, publicada em JWKS. O JWT não é assinado por chave de contrato: existe uma chave de assinatura RSA ativa (com kid, janela de validade e pronta para rotação), publicada no JWKS do Identity Management. As APIs consumidoras não guardam segredo local, validam contra essa chave pública, o issuer e a audience esperada.

Refresh token rotativo com detecção de reuso. Ao renovar o acesso, o token anterior é revogado e um novo par é emitido para a mesma sessão. Se um refresh token já usado for apresentado de novo (sinal de token roubado ou replay), a sessão inteira é revogada, não só aquele token. Access token, ID token e refresh token são guardados no banco como hash SHA-256, nunca em texto puro.

Sessões de verdade. Cada login cria uma LoginSession com IP, user-agent e expiração, validada por um middleware em toda requisição autenticada. Sessões podem ser listadas e revogadas uma a uma ou em massa.

Autorização unificada. Um único atributo (RequireAccess) aceita tanto um Bearer JWT de usuário quanto um segredo de integração entre serviços (comparado em tempo constante). Cada tenant tem seu próprio segredo, nunca compartilhado, e a resolução do tenant acontece automaticamente a partir da claim validada ou da chave de API.

Proteção de conta. Login, cadastro e formulário de contato têm limite de requisições por janela de tempo (login mais permissivo, cadastro e contato mais restritos), e contas com sequência de tentativas falhas de login ficam bloqueadas temporariamente.

Dashboard

O dashboard dá a visão operacional da instância: tendência de logins, saúde dos contratos, sessões por horário, sistemas mais utilizados e um painel de segurança consolidado. É o lado administrativo do sistema, a leitura de saúde e uso do ambiente, complementando toda a parte técnica de tokens e sessões.

Gestão de usuários

A área de usuários centraliza o cadastro e a manutenção das identidades: nome, username, email, status e dados básicos de perfil. É a base que depois é conectada a contratos, papéis e permissões. O usuário existe de forma independente; o que define o que ele pode fazer é o vínculo com papéis dentro de um contrato.

Gestão de aplicações

Cada sistema que consome o IAM é registrado como uma aplicação, com sua audiência e suas redirect URIs permitidas. Vinculado a essa aplicação vive o cliente OAuth propriamente dito: tipo de cliente, segredo com hash, se exige PKCE e consentimento, se pode operar offline, tempos de vida de access e refresh token, e se a rotação de refresh token está ativa. É esse cadastro que permite ao Identity Management saber para quem está emitindo token e isolar um produto do outro dentro da mesma central.

Gestão de empresas

As empresas representam as organizações atendidas pela plataforma. Sozinha, a empresa não define o isolamento: ela é um dos lados do contrato. É a combinação empresa mais aplicação que produz o tenant, e é por isso que a tela de empresas é estrutural, e não apenas um cadastro auxiliar.

Gestão de contratos

O contrato é a entidade central do sistema. Cada contrato representa a combinação de uma empresa com uma aplicação, com data de início, data de término e status ativo. As credenciais OAuth (client id, segredo, PKCE, tempos de vida de token) pertencem à aplicação, não ao contrato, justamente porque uma única aplicação atende vários contratos com a mesma configuração de cliente.

Na prática, é o contrato que responde, em cada requisição: qual empresa está acessando, qual sistema está sendo consumido e quais regras de acesso valem. Ele é a peça que materializa o tenant, o ponto onde identidade, multi-tenancy e emissão de token se encontram.

Catálogo de permissões

As permissões não são escritas à mão. Cada API do ecossistema publica, no startup, seus recursos protegidos e o catálogo de capacidades (módulos, verbos e rótulos em português) no Identity Management por um endpoint de sincronização, que cria os novos, atualiza os existentes, reativa os que reaparecem e desativa os que somem.

Esses recursos são ligados a papéis, e os papéis a usuários dentro de um contrato. O resultado vira claim no JWT: capacidade por módulo (ver, editar, excluir), permissão por recurso onde ainda se aplica, e um marcador de papel root quando cabe. As claims de capacidade e permissão foram desenhadas de forma compacta de propósito, porque o cabeçalho de autorização passa por proxies com limite de tamanho, e uma lista longa de permissões nominais estourava esse limite. A autorização do ecossistema inteiro se resolve a partir desse contrato de claims.

Multi-tenant por contrato

O sistema foi desenhado para crescer sem replicar autenticação. Várias empresas convivem no mesmo ambiente, vários sistemas compartilham a mesma central, e o mesmo usuário pode ter acessos diferentes em contextos diferentes, sempre com o contrato como unidade de isolamento.

Cada tenant tem seu próprio banco e seu próprio segredo de integração, e a resolução de qual tenant atende a requisição acontece a partir da claim de tenant já validada no token, ou da chave de API para chamadas de serviço. É o que sustenta um cenário multi-produto real: uma base de identidade única alimentando toda a plataforma, sem que um tenant enxergue o outro.

Onboarding e provisionamento de tenant

Criar um cliente novo não é uma sequência de cadastros manuais: é uma única transação que dá à luz o tenant inteiro. A partir dos dados da empresa e da lista de sistemas contratados, o Identity Management cria a empresa, um contrato por sistema e um banco de dados isolado por sistema, com uma chave de API gerada e um convite administrativo de uso único, válido por sete dias.

Os detalhes desse provisionamento são o que o tornam sério:

• Privilégio mínimo por sistema. Cada banco nasce com uma role de dono própria para aquele sistema, criada com uma credencial administrativa separada da aplicação. Nenhum sistema enxerga o banco do outro.
• Compensação em caso de falha. Se qualquer parte do provisionamento falhar depois que os bancos já foram criados, o processo desfaz e apaga os bancos criados, em vez de deixar um tenant pela metade.
• Bootstrap depois do commit. Só depois que a transação principal é confirmada, cada sistema contratado é inicializado: integrações padrão são semeadas, segredos compartilhados são gerados e as migrations daquele tenant rodam. A assinatura, quando o onboarding vem com um plano, é criada de forma best-effort nesse mesmo momento, sem desfazer o provisionamento se a cobrança falhar.
• Convite de uso único. O retorno inclui um link de setup para o administrador da empresa, que finaliza por um de dois caminhos: criar a conta do zero ou vincular uma conta que já existe na central.

Além do onboarding administrativo, existe um cadastro self-service em duas etapas: o interessado se cadastra (com atribuição de UTM de origem), confirma por e-mail e só então os bancos e contratos são efetivamente criados, o que evita provisionar tenant para quem nunca confirma o cadastro.

Planos, assinaturas e pagamentos

Além de identidade, o Identity Management é a autoridade de cobrança do ecossistema SaaS. É aqui que vivem os planos, as assinaturas das empresas e a integração com o provedor de pagamento, o que transforma o sistema de um login num backend de SaaS de verdade.

Planos. Cada plano tem nome, descrição, preço, moeda, período de cobrança (mensal ou anual), dias de trial, preço de lançamento e um flag de ativo. São os pacotes que uma empresa contrata.

Assinaturas. Cada empresa tem uma assinatura ligada a um plano, com ciclo de vida próprio: em trial, ativa, em atraso, suspensa e cancelada. A assinatura guarda as janelas do período corrente, as datas de trial e cancelamento, e as referências de cliente e assinatura no provedor externo. Carrega também um motivo de bloqueio (hoje, inadimplência).

Pagamentos e gateway. A cobrança recorrente é delegada ao Asaas por trás de uma interface de gateway (criar cliente, criar assinatura, cancelar), com uma implementação no-op para ambientes sem cobrança real. Os métodos suportados hoje são Pix e cartão de crédito. Cada pagamento é registrado com valor, método, vencimento, data de pagamento e um status que espelha o provedor.

Webhooks e dunning. O provedor avisa o sistema por webhook a cada evento (pagamento confirmado, vencido e afins), processado de forma idempotente por um identificador externo do evento, evitando duplicar efeitos em reentregas. Um job de cobrança (dunning) roda em segundo plano para escalar as assinaturas em atraso além da janela de tolerância até o bloqueio.

O gate de acesso. O elo entre cobrança e identidade é o ponto mais importante. Uma empresa sem assinatura ativa é bloqueada por padrão: o fluxo de emissão de token nega o acesso (access_denied), com uma única exceção, um conjunto configurável de audiências restritas ainda recebe um token limitado, o suficiente para telas como cobrança e regularização. O desenho só abre mão do bloqueio (fail-open) se a própria checagem de assinatura falhar por erro técnico, nunca por ausência de assinatura.