Identity Management

Núcleo de identidade e acesso de toda a plataforma: um único sistema que autentica usuários, resolve o contexto multi-tenant, emite tokens por contrato e centraliza as permissões consumidas por todos os outros produtos do ecossistema.

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 e redirect URIs);
• contratos (empresa x aplicação, o tenant real);
• papéis de acesso vinculados ao contrato;
• recursos protegidos (catálogo central de 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;
• 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 entra com suas credenciais e o sistema não responde apenas "autenticado ou não". Ele resolve, em sequência: quem é o usuário, quais contratos ativos ele possui e em qual contexto pode operar.

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 token será emitido, com qual audiência, assinado com qual chave e carregando 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.

Dois fluxos de autenticação. Há um fluxo de login direto por API (identificação, seleção de contrato e emissão de tokens) e um fluxo OIDC completo, com authorization code e PKCE, discovery em /.well-known/openid-configuration e jwks.json, e endpoints padrão de authorize, token, userinfo, revocation e logout. Aplicações podem integrar pelo caminho simples ou pelo padrão de mercado.

Token assinado por contrato. O JWT final não é assinado com uma chave global: cada contrato tem sua própria JwtSecretKey, e a audiência vem da aplicação daquele contrato. Comprometer um contrato não compromete os outros.

Validação dinâmica. As APIs consumidoras não guardam a chave localmente. Elas validam o token consultando o Identity Management pelo client_id para descobrir a chave e a configuração esperadas. A confiança é resolvida em tempo de requisição, não codificada.

Refresh token rotativo. Ao renovar o acesso, o token anterior é revogado e marcado como usado, e um novo par de tokens é emitido para a mesma sessão. Isso fecha a janela de replay de refresh tokens.

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 dele.

Dashboard

O dashboard dá a visão operacional da instância: usuários ativos, contratos ativos, empresas e sistemas cadastrados, sistemas mais utilizados e sessões ativas. É 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. É esse cadastro que permite ao Identity Management saber para quem está emitindo token, validar de onde a autenticação pode partir 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 e carrega tudo o que torna aquele acesso concreto: ClientId, ClientSecret e JwtSecretKey (gerados automaticamente na criação), os tempos de vida do access token e do refresh token, e a vigência do acesso.

Na prática, é o contrato que responde, em cada requisição: qual empresa está acessando, qual sistema está sendo consumido, qual token deve ser gerado, com qual chave, 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 seus recursos protegidos no Identity Management por um endpoint de sincronização, que recebe os recursos em lote, cria os novos, atualiza os existentes, reativa os que reaparecem e desativa os que somem. Cada recurso descreve um ponto protegido (controller, action, método HTTP e rota).

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: o token carrega as permissões no formato controller.action, mais um marcador de papel root quando aplicável. 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 do client_id ou da chave de API. É 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.

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, preço, moeda, período de cobrança (mensal ou anual), dias de trial 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 estado de bloqueio com motivo (hoje, inadimplência).

Pagamentos e gateway. A cobrança recorrente é delegada a um provedor externo (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. Cada pagamento é registrado com valor, método (Pix, boleto ou cartão), vencimento, data de pagamento e um status que espelha o provedor: pendente, confirmado, recebido, vencido, estornado ou em chargeback.

Webhooks e dunning. O provedor avisa o sistema por webhook a cada evento (pagamento confirmado, vencido e afins), e o Identity Management atualiza pagamento e assinatura de forma idempotente, guardando o evento recebido. Um job de cobrança (dunning) roda em segundo plano para tratar as assinaturas em atraso, escalando até o bloqueio.

O gate de acesso. O elo entre cobrança e identidade é o ponto mais importante. Quando uma assinatura está bloqueada por inadimplência, o próprio fluxo de emissão de token barra o acesso: a empresa deixa de obter novos tokens e, na prática, perde acesso aos produtos até regularizar. O desenho é fail-open, uma empresa sem assinatura não é barrada (o que mantém os sistemas internos livres), e só o bloqueio explícito por pagamento corta o acesso.

Diferenciais do projeto

• OIDC completo (authorization code com PKCE) convivendo com um fluxo de login direto por API;
• JWT assinado por contrato, com validação dinâmica de chave por client_id, em vez de chave global;
• refresh token rotativo com revogação do token anterior, fechando replay;
• multi-tenant materializado pelo contrato, com banco e segredo isolados por tenant;
• catálogo de permissões sincronizado pelas próprias APIs, virando claims controller.action no token;
• autorização unificada para usuários (Bearer) e serviços (segredo de integração) em um único atributo;
• frontend administrativo em React (stack compartilhada do ecossistema), com login, OIDC e backoffice completo;
• camada de cobrança SaaS (planos, assinaturas e pagamentos via gateway, com webhooks e dunning) com bloqueio de acesso por inadimplência no próprio fluxo de token.

Resumo executivo

O Identity Management é o centro de identidade, autorização e tenancy do ecossistema Archon. Ele autentica (por login direto ou OIDC), resolve contrato e tenant, emite tokens por contrato, mantém sessões e refresh tokens rotativos, centraliza as permissões de todos os sistemas e, na camada SaaS, gerencia planos, assinaturas e cobrança, barrando o acesso de quem está inadimplente.

É um projeto estratégico no portfólio justamente porque o desafio dele não é a tela de login: é conectar segurança, multi-tenancy e autorização entre sistemas independentes, de forma que o erro em qualquer uma dessas dimensões teria efeito em todo o ecossistema.