Construir um aplicativo SaaS multi-inquilino: Um guia completo desde o design até a implementação

Como aplicativos como Notion, Slack ou Figma são construídos? Esses aplicativos SaaS multi-inquilino parecem simples de usar, mas construir um você mesmo? Essa é outra história.

Quando eu pensei pela primeira vez em construir essa fera complexa, minha mente explodiu:

• Os usuários precisam de várias opções de login (e-mail, Google, GitHub)
• Cada usuário pode criar e pertencer a várias organizações
• Diferentes níveis de permissão dentro de cada organização
• Organizações empresariais exigindo auto-ingresso para domínios de e-mail específicos
• Requisitos de MFA para operações sensíveis
• ...

"Chefe, vamos falar sobre design de produto em duas semanas. Estou atolado no momento."

Mas quando eu realmente comecei a trabalhar nisso, descobri que não é tão assustador quanto parece.

Eu apenas construí um sistema com todos esses recursos em MENOS DE 2 HORAS!

Vou mostrar exatamente como projetar e implementar tal sistema do zero - e você ficará surpreso com quão simples realmente é em 2025 com as ferramentas modernas e a abordagem arquitetônica correta.

O código fonte completo está disponível no final deste artigo. Vamos nos aprofundar!

Vamos começar com um produto SaaS de documentação AI chamado DocuMind.

DocuMind é um produto SaaS de documentação AI projetado com um modelo multi-inquilino para suportar usuários individuais, pequenas empresas e empresas grandes.

A plataforma oferece poderosas capacidades de AI para gerenciamento de documentos, incluindo geração automática de resumos, extração de pontos chave e recomendações inteligentes de conteúdo dentro das organizações.

Quais recursos são necessários para autenticação e autorização SaaS?#

Primeiro, vamos revisar os requisitos necessários. Quais recursos você precisa?

Arquitetura multi-inquilino#

Para habilitar uma arquitetura multi-inquilino, você precisará de uma camada de entidade chamada organização. Imagine ter um único pool de usuários que podem acessar múltiplos espaços de trabalho. Cada organização representa um espaço de trabalho, e os usuários mantêm uma única identidade enquanto acessam diferentes espaços de trabalho (organizações) com base em suas funções atribuídas.

É um recurso amplamente utilizado em provedores de autenticação. Uma organização em um sistema de gerenciamento de identidades corresponde ao espaço de trabalho, projeto ou inquilino do seu aplicativo SaaS.

Membresia#

Um membro é um conceito temporário usado para indicar o status de membresia de uma identidade dentro de uma organização.

Por exemplo, Sarah se inscreve no seu aplicativo usando seu e-mail, [email protected]. Ela pode pertencer a diferentes espaços de trabalho. Se Sarah faz parte do Espaço de Trabalho A mas não do Espaço de Trabalho B, ela é considerada membro do Espaço de Trabalho A mas não do Espaço de Trabalho B.

Design de função e permissão#

Em uma arquitetura multi-inquilino, os usuários precisam de funções com permissões específicas para acessar seus recursos do inquilino. Permissões são controles de acesso detalhados que definem ações específicas, como ler: pedido ou escrever: pedido. Elas determinam quais ações podem ser realizadas em recursos específicos.

As funções são um conjunto de permissões atribuídas a membros em um ambiente multi-inquilino.

Você precisará definir essas funções e permissões, depois atribuir funções aos usuários, e às vezes pode incluir processos automatizados. Por exemplo:

1. Usuários que ingressam em uma organização recebem automaticamente o papel de membro.
2. O primeiro usuário a criar um espaço de trabalho é automaticamente atribuído ao papel de admin.

Fluxo de inscrição e login#

Garanta um processo de registro e autenticação amigável e seguro, incluindo opções básicas de login e inscrição:

1. Login por e-mail e senha: Método de login tradicional com e-mail e senha.
2. Login sem senha: Use códigos de verificação por e-mail para acesso fácil e seguro.
3. Gerenciamento de contas: Um centro de contas onde os usuários podem atualizar seu e-mail, senha e outros detalhes.
4. Login social: Opções como Google e GitHub para login rápido.
5. Autenticação multi-fator (MFA): Aperfeiçoe a segurança permitindo login através de aplicativos autenticadores como Duo.

Criação de inquilino e convite#

Em um aplicativo SaaS multi-inquilino, uma diferença chave no fluxo do usuário é a necessidade de suportar a criação de inquilinos e convites de membros. Esse processo requer um planejamento cuidadoso e execução, pois desempenha um papel chave na ativação e crescimento do produto.

Aqui estão alguns fluxos típicos de uso que você precisa considerar:

Aqui estão alguns cenários comuns encontrados em quase todos os aplicativos SaaS. Use-os como referência para inspirar sua equipe de produto e design, e sinta-se livre para criar seus próprios fluxos conforme necessário.

Arquitetura técnica e design de sistemas#

Uma vez que entendemos todos os requisitos do produto, vamos passar para a implementação.

Definir estratégia de autenticação#

Autenticação parece assustadora. Os usuários precisam de:

• Inscrição/login por e-mail e senha
• Login com um clique com Google/Github
• Redefinição de senha quando esquecem
• Login em equipe para clientes empresariais
• ...

Implementar apenas esses recursos básicos pode levar semanas de desenvolvimento.

Mas agora, não precisamos construir NADA disso nós mesmos!

Provedores modernos de autenticação (eu escolherei Logto desta vez) embalaram todos esses recursos para nós. O fluxo de autenticação é direto:

De semanas de desenvolvimento para 15 minutos de configuração, Logto lida com todos os fluxos complexos para nós! Vamos cobrir as etapas de integração na seção de implementação mais tarde. Agora podemos nos concentrar em construir os recursos principais do DocuMind!

Estabelecer arquitetura multi-inquilino#

O sistema de organização permite que os usuários criem e ingressem em várias organizações. Vamos entender os relacionamentos principais:

Neste sistema, cada usuário pode pertencer a várias organizações, e cada organização pode ter vários membros.

Habilitar controle de acesso em aplicativo multi-inquilino#

O Controle de Acesso Baseado em Papéis (RBAC) é importante para assegurar a segurança e escalabilidade em aplicativos SaaS multi-inquilino.

Em um aplicativo multi-inquilino, o design de permissões e funções é geralmente consistente, pois decorre do design do produto. Por exemplo, em vários espaços de trabalho, geralmente existe um papel de administrador e um papel de membro. Logto como provedor de autenticação tem o seguinte design de controle de acesso baseado em papéis a nível de organização:

1. Definições de permissões unificadas: Permissões são definidas em nível de sistema e aplicadas consistentemente em todas as organizações, garantindo uma gestão de permissões sustentável e consistente
2. Modelos de organização: Combinações predefinidas de papéis e permissões através de modelos de organização, simplificando a inicialização de organização

O relacionamento de permissão tem esta aparência:

Como cada usuário precisa de seu próprio papel(s) dentro de cada organização, o relacionamento entre papéis e organizações deve refletir os papéis atribuídos a cada usuário:

Projetamos o sistema de organização e o sistema de controle de acesso, e agora podemos começar a construir nosso produto!

Pilha tecnológica#

Escolhi uma pilha portátil e amigável para iniciantes:

1. Frontend: React (facilmente transferível para Vue/Angular/Svelte)
2. Backend: Express (API simples e intuitiva)

Por que separar frontend e backend? Porque tem uma arquitetura clara, fácil de aprender e simples de modificar. E para provedores de autenticação, uso Logto como exemplo.

E para os seguintes guias, os padrões aqui funcionam com: Qualquer frontend, qualquer backend e qualquer sistema de autenticação.

Adicionar fluxo básico de autenticação ao seu aplicativo#

Esta é a etapa mais fácil. Só precisamos integrar Logto em nosso projeto. Depois podemos configurar métodos de login/registro de usuários no Console Logto com base em nossas necessidades.

Instalar Logto no seu aplicativo#

Primeiro, faça login em Logto Cloud. Você pode se inscrever para uma conta gratuita se não tiver uma. Crie um Tenant de Desenvolvimento para testar.

No Console de Tenant, clique no botão "Aplicativo" à esquerda. Depois selecione React para começar a construir nosso aplicativo.

Siga o guia na página. Você pode completar a integração do Logto em cerca de 5 minutos!

Aqui está meu código de integração:

Aqui está um truque útil: Nossa página de login tem botões de Entrar e Registrar. O botão Registrar leva diretamente à página de registro do Logto. Isso funciona através do recurso primeira tela do Logto. Ele determina qual etapa do fluxo de autenticação os usuários veem primeiro.

Você pode definir como padrão para a página de registro quando seu produto espera muitos novos usuários.

Após clicar em login, você irá para a página de login do Logto. Após login bem-sucedido (ou registro), parabéns! Seu aplicativo tem seu primeiro usuário (você)!

E chame a função signOut do hook useLogto para deslogar o usuário quando desejar.

Personalizar métodos de login e inscrição#

No Console Logto, clique em "Experiência de Login" no menu à esquerda. Depois clique na aba "Inscrição e login". Nesta página, siga as instruções para configurar os métodos de login/registro do Logto.

E o fluxo de login ficará assim:

Habilitar autenticação multi-fator#

Com Logto, habilitar MFA é simples. Basta clicar no botão "Autenticação multi-fator" no Console Logto. Depois ative na página de autenticação multi-fator.

E o fluxo de MFA ficará assim:

Tudo é tão simples! Configuramos um sistema de autenticação complexo de usuário em apenas alguns minutos!

Adicionando experiência de organização multi-inquilino#

Agora temos nosso primeiro usuário! No entanto, este usuário não pertence a nenhuma organização ainda, e não criamos nenhuma organização.

Logto oferece suporte embutido para multi-inquilino. Você pode criar qualquer número de organizações no Logto. Cada organização pode ter vários membros.

Cada usuário pode obter suas informações de organização do Logto. Isso habilita o suporte a multi-inquilino.

Obter informações de organização de um usuário#

Para obter informações de organização de um usuário no Logto, siga estas duas etapas:

Declare o acesso à informação de organização no Config Logto. Isto é feito configurando os escopos e recursos apropriados.

Use o método fetchUserInfo do Logto para obter informações do usuário, incluindo dados da organização.

Após completar essas etapas, você precisa sair e entrar novamente. Isso é necessário porque modificamos o escopo e o recurso solicitados.

No momento, você ainda não criou nenhuma organização. O usuário também não ingressou em nenhuma organização. O painel mostrará "Você ainda não tem nenhuma organização."

Em seguida, criaremos uma organização para nuestros usuários e os adicionaremos a ela.

Graças ao Logto, não precisamos construir relações complexas de organização. Só precisamos criar uma organização no Logto e adicionar usuários a ela. Logto lida com toda a complexidade para nós. Existem duas maneiras de criar Organizações:

1. Criação manual de organizações através do Console Logto
2. Use a API de gerenciamento Logto para criar organizações, especialmente ao projetar um fluxo SaaS que permite aos usuários criar suas próprias organizações (espaços de trabalho).

Criar organização no console Logto#

Clique no botão "Organizações" no menu à esquerda do Console Logto. Crie uma organização.

Agora você tem sua primeira organização.

Em seguida, vamos adicionar o usuário a esta organização.

Vá para a página de detalhes da organização. Mude para a guia Membros. Clique no botão "+ Adicionar membro". Selecione seu usuário de login na lista à esquerda. Clique no botão "Adicionar membros" no canto inferior direito. Agora você adicionou com sucesso o usuário a esta organização.

Atualize a página do seu APP. Você verá que o usuário agora pertence a uma organização!

Implementar experiência de criação de organização self-service#

Criar uma organização no console não é suficiente. Seu aplicativo SaaS precisa de um fluxo que permita aos usuários finais criarem e gerenciarem facilmente seus próprios espaços de trabalho. Para implementar essa funcionalidade, use a API de Gerenciamento Logto.

Para orientações, confira a documentação Interact with Management API para configurar a comunicação da API com o Logto.

Entender o fluxo de interação de autenticação de organização#

Vamos pegar o fluxo de criação de organização como exemplo. Veja como funciona o processo de criação de organização:

Este fluxo tem dois requisitos chave de autenticação:

1. Protegendo a API de serviço backend:
   • O acesso do Frontend à nossa API de Serviço Backend requer autenticação
   • Os endpoints da API são protegidos validando o Token de Acesso do Logto do usuário
   • Garante que apenas usuários autenticados possam acessar nossos serviços
2. Acessar a API de Gerenciamento do Logto:
   • O Serviço Backend precisa chamar com segurança a API de Gerenciamento do Logto
   • Siga o guia Interact with Management API para configuração
   • Use autenticação de Máquina para Máquina para obter credenciais de acesso

Proteger sua API de backend#

Primeiro, vamos criar um endpoint de API em nosso serviço backend para criar organizações.

Nossa API de Serviço Backend permite apenas usuários autenticados. Precisamos usar Logto para proteger nossa API. Também precisamos saber a informação do usuário atual (como id do usuário).

No conceito Logto (e OAuth 2.0), nosso serviço backend atua como um servidor de recursos. Os usuários acessam o servidor de recursos DocuMind com um Token de Acesso do frontend. O servidor de recursos verifica esse token. Se válido, retorna os recursos solicitados.

Vamos criar um Recurso API para representar nosso serviço backend.

Vá para o Console Logto.

1. Clique no botão "Recursos API" à direita.
2. Clique em "Criar Recurso API". Selecione Express no pop-up.
3. Preencha "API DocuMind" como nome da API. Use "https://api.documind.com" como identificador da API.
4. Clique em criar.

Não se preocupe com este URL de identificador de API. É apenas um identificador único para sua API no Logto. Não está relacionado ao URL real do seu serviço backend.

Você verá um tutorial para usar o recurso API. Você pode seguir esse tutorial ou nossos passos abaixo.

Vamos criar um middleware requireAuth para proteger nosso endpoint POST /organizations.

Para usar este middleware, precisamos destas variáveis de ambiente:

• LOGTO_JWKS_URL
• LOGTO_ISSUER

Obtenha estas variáveis do endpoint de Configuração OpenID do seu Tenant Logto. Visite https://<seu-id-de-tenant>.logto.app/oidc/.well-known/openid-configuration. Você encontrará as informações necessárias no JSON retornado:

Agora use o middleware requireAuth no nosso endpoint POST /organizations.

Isto protege nosso endpoint POST /organizations. Somente usuários com tokens de acesso válidos Logto podem acessá-lo.

Agora podemos obter o token do Logto no nosso frontend. Os usuários podem criar organizações através do nosso serviço backend com este token. O middleware também nos dá o ID do usuário. Isso ajuda ao adicionar usuários a organizações.

No código do frontend, declare este recurso API na configuração Logto. Adicione seu identificador à matriz de recursos.

Como antes, os usuários precisam fazer login novamente após atualizarmos a configuração Logto.

No Dashboard, obtenha o Token de Acesso Logto ao criar uma organização. Use este token para acessar nossa API de serviço Backend.

Agora podemos acessar corretamente a API do serviço backend DocuMind.

Chamando a API de Gerenciamento Logto#

Vamos implementar a criação de organização usando a API de Gerenciamento Logto.

Assim como solicitações de frontend para serviço backend, solicitações de serviço backend para Logto precisam de Tokens de Acesso.

No Logto, usamos autenticação Máquina para Máquina para tokens de acesso. Veja Interact with Management API.

Vá para a página de aplicativos no Console Logto. Crie um aplicativo Máquina para Máquina. Atribua o papel "Acesso à API de Gerenciamento Logto". Copie o endpoint de token, ID do aplicativo e segredo do aplicativo. Usaremos esses dados para tokens de acesso.

Agora podemos obter tokens de acesso à API de Gerenciamento Logto através deste aplicativo M2M.

Use este token de acesso para chamar a API de Gerenciamento Logto.

Vamos usar estas APIs de Gestão:

• POST /api/organizations: Criar organização (ver: Referência da API de Criação de Organização)
• POST /api/organizations/{id}/users: Adicionar usuários à organização (ver: Referência da API de Adição de Usuários)

Agora implementamos a criação de organização através da API de Gerenciamento Logto. Também podemos adicionar usuários às organizações.

Vamos testar esse recurso no Dashboard.

e clique em “Criar Organização”

Criação bem-sucedida!

O próximo passo seria convidar usuários para uma organização. Não implementaremos esse recurso em nosso tutorial ainda. Você já sabe como usar a API de Gerenciamento. Você pode referir-se a este Criação de inquilino e convite como referência de design de produto e implementar facilmente este recurso seguindo este post no blog: Como implementamos a colaboração de usuários em um aplicativo multi-inquilino.

Implementar controle de acesso ao seu aplicativo multi-inquilino#

Agora vamos passar para o controle de acesso à organização.

Queremos alcançar:

• Os usuários só podem acessar recursos pertencentes às suas próprias organizações: Isso pode ser feito através do token de organização do Logto
• Os usuários têm papéis específicos dentro das organizações (contendo diferentes permissões) para executar ações autorizadas: Isso pode ser implementado através do recurso de modelo de organização do Logto

Vamos ver como implementar esses recursos.

Usando token de organização Logto#

Assim como o token de acesso do Logto mencionado anteriormente, Logto emite um token de acesso correspondente a um recurso específico, e os usuários usam este token para acessar recursos protegidos no serviço backend. Correspondentemente, Logto emite um token de organização correspondente a uma organização específica, e os usuários usam este token para acessar recursos de organização protegidos no serviço backend.

No aplicativo frontend, podemos usar o método getOrganizationToken do Logto para obter um token para acessar uma organização específica.

Aqui, organizationId é o id da organização à qual o usuário pertence.

Antes de usar getOrganization ou recursos de organização, precisamos garantir que o escopo urn:logto:scope:organizations e o recurso urn:logto:resource:organization estejam incluídos na configuração Logto. Como já declaramos isso anteriormente, não repetiremos.

Na nossa página de organização, usamos o token de organização para buscar documentos dentro da organização.

Existem dois pontos importantes a se notar nesta implementação:

1. Se o organizationId passado para getOrganizationToken não for um id de organização que pertence ao usuário atual, este método não será capaz de obter um token, garantindo assim que os usuários só possam acessar suas próprias organizações.
2. Ao solicitar recursos de organização, usamos o token de organização em vez do token de acesso porque para recursos pertencentes a uma organização, queremos usar o controle de permissão da organização em vez do controle de permissão do usuário (você entenderá melhor isso quando implementarmos a API GET /documents mais tarde).

Em seguida, criamos uma API GET /documents no nosso serviço backend. Assim como usamos o recurso de API para proteger a API POST /organizations, usamos indicadores de recurso específicos da organização para proteger a API GET /documents.

Primeiro, vamos criar um middleware requireOrganizationAccess para proteger os recursos da Organização.

Em seguida, usamos o middleware requireOrganizationAccess para proteger a API GET /documents.

Desta forma, implementamos o uso de tokens de organização para acessar recursos de organização. No serviço backend, você pode recuperar recursos correspondentes do banco de dados com base no id da organização.

Alguns softwares exigem isolamento de dados entre as organizações. Para mais discussões e implementações, você pode se referir ao post no blog: Implementação de multi-inquilino com PostgreSQL: Aprenda através de um exemplo simples do mundo real.

Implementar design de controle de acesso baseado em papéis a nível de organização#

Implementamos o uso de tokens de organização para acessar recursos de organização. Em seguida, vamos implementar o controle de permissão do usuário dentro das organizações usando RBAC.

Vamos supor que o DocuMind tenha dois papéis: Administrador e Colaborador.

Os administradores podem criar e acessar documentos, enquanto os colaboradores podem apenas acessar documentos.

Portanto, nossa Organização precisa ter esses dois papéis: Administrador e Colaborador.

Administrador possui permissões ler:documentos e criar:documentos, enquanto Colaborador possui apenas a permissão ler:documentos.

• Administrador
  • ler:documentos
  • criar:documentos
• Colaborador
  • ler:documentos

É aqui que entra o recurso de modelo de organização do Logto.

Um modelo de organização é um esboço do modelo de controle de acesso para cada organização: define os papéis e permissões que se aplicam a todas as organizações.

Por que modelo de organização?

Porque a escalabilidade é um dos requisitos mais importantes para produtos SaaS. Em outras palavras, o que funciona para um cliente deve funcionar para todos os clientes.

Vamos para Console Logto > Modelos de Organização > Permissões de Organização e crie duas permissões: ler:documentos e criar:documentos.

Depois vá para a guia de papéis de organização para criar dois papéis de usuários: Administrador e Colaborador, e atribua permissões correspondentes a esses papéis.

Desta forma, criamos um modelo de permissão RBAC para cada organização.

Em seguida, vamos para nossa página de detalhes da Organização para atribuir papéis apropriados aos nossos membros.

Agora os usuários de nossa organização têm papéis! Você pode realizar essas etapas via API de Gerenciamento Logto:

Agora podemos implementar o controle de permissão do usuário verificando suas permissões.

No nosso código, precisamos fazer o token de organização do usuário carregar informações de permissão, e então verificar essas permissões no backend.

Na configuração Logto do código frontend, precisamos declarar as permissões que os usuários precisam solicitar dentro da organização. Vamos adicionar permissões ler:documentos e criar:documentos aos escopos.

Como de costume, faça login novamente com seu usuário para que essas configurações entrem em vigor.

Depois no middleware requireOrganizationAccess do backend, adicionamos verificação para permissões do usuário.

Em seguida, crie uma API POST /documents, e use o middleware requireOrganizationAccess com configuração de escopos necessários para proteger esta API e a API GET /documents anterior.

Desta forma, implementamos o controle de permissão do usuário verificando as permissões do usuário.

No frontend, você pode obter informações de permissão do usuário decodificando o token de organização ou chamando o método getOrganizationTokenClaims do Logto.

Controle elementos da página com base nas permissões do usuário verificando os escopos nas declarações.

Adicionar mais recursos ao aplicativo multi-inquilino#

Até agora, implementamos os recursos básicos de usuário e organização em um sistema SaaS multi-inquilino! No entanto, ainda existem alguns recursos que não cobrimos, como personalizar a marca da página de login para cada Organização, adicionar automaticamente usuários com e-mails de domínio específico a certas organizações e integrar a funcionalidade de SSO a nível empresarial.

Estes são todos recursos prontos para uso, e você pode encontrar mais informações sobre esses recursos na documentação do Logto.

Resumo#

Lembra como parecia avassalador no começo? Usuários, organizações, permissões, recursos empresariais... parecia uma montanha interminável para escalar.

Mas veja o que realizamos:

• Um sistema de autenticação completo com várias opções de login e suporte a MFA
• Um sistema de organização flexível que suporta várias associações
• Controle de acesso baseado em papéis dentro de organizações

E a melhor parte? Não tivemos que reinventar a roda. Ao aproveitar ferramentas modernas como Logto, transformamos o que poderia ter sido meses de desenvolvimento em questão de horas.

O código fonte completo para este tutorial está disponível em: Exemplo de SaaS Multi-Inquilino.

Este é o poder do desenvolvimento moderno em 2025 - podemos nos concentrar em construir recursos únicos do produto em vez de lutar com a infraestrutura. Agora é sua vez de construir algo incrível!

Explore todos os recursos do Logto, do Logto Cloud ao Logto OSS, no site Logto ou inscreva-se no Logto cloud hoje.