Construir uma aplicação SaaS multi-inquilino: Um guia completo do design à implementação

Como são construídas aplicações como o Notion, Slack ou Figma? Estas aplicações SaaS multi-inquilino parecem simples de usar, mas construir uma por si mesmo? Isso é uma história diferente.

Quando pensei pela primeira vez em construir uma besta tão complexa, a minha mente explodiu:

• Os utilizadores precisam de múltiplas opções de início de sessão (email, Google, GitHub)
• Cada utilizador pode criar e pertencer a múltiplas organizações
• Diferentes níveis de permissão dentro de cada organização
• Organizações empresariais a requererem adesão automática para domínios de email específicos
• Requisitos de MFA para operações sensíveis
• ...

"Chefe, vamos falar sobre o design do produto daqui a duas semanas. Estou atolado agora."

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

Eu apenas construí um sistema com todas estas funcionalidades em MENOS DE 2 HORAS!

Vou mostrar-lhe exatamente como desenhar e implementar tal sistema do zero - e ficará maravilhado 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 mergulhar!

Começaremos com um produto SaaS de documentação de IA chamado DocuMind.

DocuMind é um produto SaaS de documentação de IA projetado com um modelo multi-inquilino para suportar utilizadores individuais, pequenas empresas e empresas.

A plataforma fornece poderosas capacidades de IA para gestão documental, incluindo geração automática de resumos, extração de pontos chave e recomendações de conteúdo inteligente dentro das organizações.

Que funcionalidades são necessárias para autenticação e autorização SaaS?#

Primeiro, vamos rever os requisitos necessários. Que funcionalidades precisa?

Arquitetura multi-inquilino#

Para ativar uma arquitetura multi-inquilino, precisará de uma camada de entidade chamada organização. Imagine ter uma única piscina de utilizadores que pode aceder a múltiplos espaços de trabalho. Cada organização representa um espaço de trabalho, e os utilizadores mantêm uma identidade única enquanto acedem a diferentes espaços de trabalho (organizações) com base nos seus papéis atribuídos.

É uma funcionalidade amplamente utilizada em fornecedores de autenticação. Uma organização num sistema de gestão de identidades corresponde ao espaço de trabalho, projeto ou inquilino da sua aplicação SaaS.

Membresia#

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

Por exemplo, a Sarah inscreve-se na sua aplicação usando o email dela, [email protected]. Ela pode pertencer a diferentes espaços de trabalho. Se a Sarah fizer parte do Espaço de Trabalho A mas não do Espaço de Trabalho B, ela é considerada um membro do Espaço de Trabalho A mas não do Espaço de Trabalho B.

Design de papéis e permissões#

Numa arquitetura multi-inquilino, os utilizadores precisam de papéis com permissões específicas para aceder aos recursos do seu inquilino. As permissões são controlos de acesso detalhados que definem ações específicas, como read: order ou write: order. Elas determinam que ações podem ser realizadas em recursos particulares.

Os papéis são um conjunto de permissões atribuídas a membros num ambiente multi-inquilino.

Terá que definir estes papéis e permissões, e depois atribuir papéis aos utilizadores; e às vezes, isso pode incluir processos automatizados. Por exemplo:

1. Os utilizadores que se juntam a uma organização obtêm automaticamente o papel membro.
2. O primeiro utilizador a criar um espaço de trabalho é automaticamente atribuído ao papel admin.

Fluxo de registo e login#

Assegure um processo simples e seguro de registo e autenticação, incluindo opções básicas de início de sessão e registo:

1. Assinatura com email e senha: Método tradicional de login com email e senha.
2. Assinatura sem senha: Use códigos de verificação de email para acesso fácil e seguro.
3. Gestão de contas: Um centro de contas onde os utilizadores podem atualizar o seu email, senha e outros detalhes.
4. Assinatura social: Opções como Google e GitHub para um acesso rápido.
5. Autenticação Multi-Fator (MFA): Aumente a segurança permitindo login através de apps autenticadoras como Duo.

Criação e convite de inquilinos#

Numa aplicação SaaS multi-inquilino, uma diferença chave no fluxo de utilizador é a necessidade de suportar criação de inquilinos e convites de membros. Este processo requer um planeamento cuidadoso e execução, pois desempenha um papel importante na ativação e crescimento do produto.

Aqui estão alguns fluxos típicos que precisa considerar:

Aqui estão alguns cenários comuns encontrados em quase todas as aplicações SaaS. Use-os como referência para inspirar a sua equipa de produto e design, e sinta-se à vontade para criar os seus próprios fluxos conforme necessário.

Arquitetura técnica e design do sistema#

Uma vez que compreendemos todos os requisitos do produto, vamos passar à implementação.

Definir estratégia de autenticação#

A autenticação parece assustadora. Os utilizadores precisam de:

• Assinatura/login com Email & senha
• Login numa clique com Google/Github
• Redefinição de senha quando esquecem
• Login abrangente da equipa para clientes empresariais
• ...

Implementar apenas estas funcionalidades básicas pode levar semanas de desenvolvimento.

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

Os fornecedores de autenticação moderna (escolherei Logto desta vez) têm todas estas funcionalidades para nós. O fluxo de autenticação é simples:

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

Estabelecer a arquitetura multi-inquilino#

O sistema organizacional permite que utilizadores criem e se juntem a várias organizações. Vamos entender os relacionamentos principais:

Neste sistema, cada utilizador pode pertencer a múltiplas organizações, e cada organização pode ter múltiplos membros.

Ativar o controle de acesso na aplicação multi-inquilino#

O Controlo de Acesso Baseado em Papéis (RBAC) é importante para garantir a segurança e escalabilidade em aplicações SaaS multi-inquilino.

Numa aplicação multi-inquilino, o design das permissões e papéis é geralmente consistente, pois deriva do design do produto. Por exemplo, em múltiplos espaços de trabalho, há tipicamente um papel de admin e um papel de membro. Logto, como fornecedor de autenticação, tem o seguinte design de controlo de acesso baseado em papéis a nível organizacional:

1. Definições unificadas de permissões: As permissões são definidas ao nível do sistema e aplicam-se consistentemente a todas as organizações, garantindo uma gestão de permissões sustentável e consistente
2. Modelos de organização: Combinações de papéis e permissões pré-definidas através de modelos de organização, simplificando a inicialização da organização

O relacionamento de permissões parece assim:

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

Projetámos o sistema organizacional e o sistema de controlo de acesso, e agora podemos começar a construir o nosso produto!

Pilha tecnológica#

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

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

Por que separar frontend e backend? Porque tem uma arquitetura clara, é fácil de aprender e simples de trocar pilhas. E para os fornecedores de autenticação, usei Logto como exemplo.

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

Adicionar fluxo de autenticação básico à sua aplicação#

Este é o passo mais fácil. Só precisamos de integrar Logto no nosso projeto. Então podemos configurar métodos de login/registo de utilizador no Console do Logto com base nas nossas necessidades.

Instalar Logto na sua aplicação#

Primeiro, faça login no Logto Cloud. Pode se inscrever para uma conta gratuita se não tiver uma. Crie um Inquilino de Desenvolvimento para testar.

No Console do Inquilino, clique no botão "Application" à esquerda. Em seguida, selecione React para começar a construir a sua aplicação.

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

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

Aqui está um truque útil: Nossa página de login tem botões de Iniciar Sessão e Registrar. O botão Registrar leva diretamente à página de registo do Logto. Isto funciona através da funcionalidade primeira tela do Logto. Determina qual passo do fluxo de autenticação os utilizadores veem primeiro.

Pode definir como padrão a página de registo quando o seu produto espera muitos novos utilizadores.

Após clicar para login, será redirecionado para a página de login do Logto. Após login (ou registo) com sucesso, parabéns! A sua aplicação tem o primeiro utilizador (você)!

E chame a função signOut do gancho useLogto para efetuar logout do utilizador quando desejar.

Personalizar métodos de login e registo#

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

E o fluxo de login será assim:

Ativar autenticação multi-fator#

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

E o fluxo MFA será assim:

Tudo é tão simples! Configurámos um sistema de autenticação de utilizador complexo em apenas alguns minutos!

Adicionar experiência organizacional multi-inquilino#

Agora temos o nosso primeiro utilizador! No entanto, esse utilizador não pertence a nenhuma organização ainda, e não criámos quaisquer organizações.

Logto fornece suporte incorporado para multi-inquilino. Pode criar qualquer número de organizações no Logto. Cada organização pode ter múltiplos membros.

Cada utilizador pode obter a sua informação de organização a partir do Logto. Isto habilita o suporte multi-inquilino.

Obter informação da organização do utilizador#

Para obter informação da organização do utilizador a partir do Logto, siga estes dois passos:

Declare acesso à informação da organização no Config do Logto. Isto é feito definindo os scopes e resources apropriados.

Use o método fetchUserInfo do Logto para obter informação do utilizador, incluindo dados da organização.

Após completar esses passos, precisa sair e entrar novamente. Isso é necessário porque modificámos o escopo e recurso solicitados.

Agora mesmo, você não criaram organizações. O utilizador também não se juntou a nenhuma organização. O painel mostrará "Você ainda não tem nenhuma organização".

A seguir, vamos criar uma organização para os nossos utilizadores e adicioná-los a ela.

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

1. Criar organizações manualmente através do Console do Logto
2. Usar a API de Gestão do Logto para criar organizações, especialmente ao projetar um fluxo SaaS que permite que os utilizadores criem suas próprias organizações (espaços de trabalho).

Criar organização no console do Logto#

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

Agora você tem sua primeira organização.

A seguir, vamos adicionar o utilizador a esta organização.

Vá para a página de detalhes da organização. Mude para a aba de Membros. Clique no botão "+ Add member". Selecione seu utilizador de login a partir da lista à esquerda. Clique no botão "Add members" na parte inferior direita. Agora adicionou com sucesso o utilizador a esta organização.

Atualize sua página de APP. Verá que o utilizador agora pertence a uma organização!

Implementar experiência de criação de organizações de autosserviço#

Criar uma organização no console não é suficiente. Sua aplicação SaaS precisa de um fluxo que permita que os utilizadores finais criem e gerenciem facilmente os seus próprios espaços de trabalho. Para implementar essa funcionalidade, use a API de Gestão do Logto.

Para orientação, verifique a documentação Interagir com a API de Gestão para configurar a comunicação de API com o Logto.

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

Vamos tomar 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 do backend:
   • O acesso do frontend à nossa API do Backend exige autenticação
   • Os endpoints da API são protegidos validando o Token de Acesso do Logto do utilizador
   • Garante que apenas utilizadores autenticados podem acessar os nossos serviços
2. Acessando a API de Gestão do Logto:
   • O Backend precisa chamar de forma segura a API de Gestão do Logto
   • Siga o guia Interagir com API de Gestão para configuração
   • Use autenticação Máquina-a-Máquina para obter credenciais de acesso

Proteger a sua API de backend#

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

Nossa API de serviço backend só permite utilizadores autenticados. Precisamos usar o Logto para proteger nossa API. Também precisamos saber a informação do utilizador atual (como o ID do utilizador).

No conceito do Logto (e OAuth 2.0), nosso serviço backend atua como servidor de recursos. Os utilizadores acessam o servidor de recursos do DocuMind com um token de Acesso a partir do frontend. O servidor de recursos verifica este token. Se for válido, ele retorna os recursos solicitados.

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

Vá para o Console do Logto.

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

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

Verá um tutorial para usar o recurso da API. Pode seguir esse tutorial ou os nossos passos abaixo.

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

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

• LOGTO_JWKS_URL
• LOGTO_ISSUER

Obtenha essas variáveis do endpoint de Configuração OpenID do seu inquilino Logto. Visite https://<your-tenant-id>.logto.app/oidc/.well-known/openid-configuration. Encontrará a informação necessária no JSON retornado:

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

Isso protege nosso endpoint POST /organizations. Apenas utilizadores com tokens de acesso Logto válidos podem acessar.

Agora podemos obter o token a partir do Logto no nosso frontend. Os utilizadores podem criar organizações através do nosso serviço backend com este token. O middleware também nos fornece o ID do utilizador. Isso ajuda ao adicionar utilizadores às organizações.

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

Como antes, os utilizadores precisam fazer login novamente após atualizarmos a configuração do Logto.

No Dashboard, obtenha o Token de Acesso do Logto ao criar uma organização. Use este token para acessar a API do nosso serviço backend.

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

Chamando a API de Gestão do Logto#

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

Assim como pedidos de frontend ao serviço backend, pedidos de serviço backend ao Logto precisam de tokens de Acesso.

No Logto, usamos autenticação Máquina-a-Máquina para tokens de acesso. Veja Interagir com API de Gestão.

Vá para a página de aplicações no Console do Logto. Crie um aplicativo Máquina-a-Máquina. Atribua o papel "Acesso à API de Gestão do Logto". Copie o endpoint do Token, App ID, e App Secret. Usaremos estes para tokens de acesso.

Agora podemos obter tokens de acesso da API de Gestão do Logto através deste aplicativo M2M.

Use este token de acesso para chamar a API de Gestão do Logto.

Usaremos estas APIs de Gestão:

• POST /api/organizations: Criar organização (ver: Referência à API de criação de organização)
• POST /api/organizations/{id}/users: Adicionar utilizadores à organização (ver: Referência à API de adicionar utilizadores)

Implementámos agora a criação de organização através da API de Gestão do Logto. Também podemos adicionar utilizadores a organizações.

Vamos testar este recurso no Dashboard.

e clique em “Create Organization”

Criação bem-sucedida!

O próximo passo seria convidar utilizadores para uma organização. Não vamos implementar esta funcionalidade no nosso tutorial ainda. Já sabe como usar a API de Gestão. Pode referir esta Criação e convite de inquilinos como referência de design de produto e implementar facilmente esta funcionalidade seguindo este post no blog: How we implement user collaboration within a multi-tenant app.

Implementar controle de acesso para sua app multi-inquilino#

Agora vamos passar para o controle de acesso organizacional.

Queremos alcançar:

• Os utilizadores só podem aceder a recursos pertencentes às suas próprias organizações: Isso pode ser feito através do token de organização do Logto
• Os utilizadores 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 essas funcionalidades.

Usando o token de organização do Logto#

Semelhante ao token de acesso do Logto que mencionámos anteriormente, o Logto emite um token de acesso correspondente a um recurso específico, e os utilizadores usam este token para aceder a recursos protegidos no serviço backend. Correlativamente, o Logto emite um token de organização correspondente a uma organização específica, e os utilizadores usam este token para aceder a recursos protegidos da organização no serviço backend.

Na aplicação frontend, podemos usar o método getOrganizationToken do Logto para obter um token para aceder uma organização específica.

Aqui, organizationId é o id da organização à qual o utilizador pertence.

Antes de usar getOrganization ou qualquer recurso de organização, precisamos garantir que o escopo urn:logto:scope:organizations e o recurso urn:logto:resource:organization estão incluídos na configuração do Logto. Uma vez que já declaramos isso anteriormente, não vamos repetir.

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

Há dois pontos importantes a notar nesta implementação:

1. Se o organizationId passado para getOrganizationToken não for um id de organização que pertence ao utilizador atual, este método não poderá obter um token, garantindo assim que os utilizadores apenas podem acessar as suas próprias organizações.
2. Ao solicitar recursos da 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 de organização em vez do controle de permissão de utilizador (você entenderá melhor isso quando implementarmos a API GET /documents mais tarde).

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

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

Então usamos o middleware requireOrganizationAccess para proteger a API GET /documents.

Desta forma, implementámos o uso de tokens de organização para acessar recursos organizacionais. No serviço backend, pode recuperar recursos correspondentes da base de dados com base no ID da organização.

Alguns softwares requerem isolamento de dados entre organizações. Para mais discussões e implementações, você pode se referir ao post do blog: Implementação 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 organizacional#

Implementámos o uso de tokens de organização para aceder recursos organizacionais. A seguir, vamos implementar o controlo de permissão de utilizador dentro das organizações usando RBAC.

Vamos assumir que o DocuMind tem dois papéis: Admin e Colaborador.

Os admins podem criar e acessar documentos, enquanto os Colaboradores só podem acessar documentos.

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

O Admin tem ambas as permissões read:documents e create:documents, enquanto o Colaborador tem apenas a permissão read:documents.

• Admin
  • read:documents
  • create:documents
• Colaborador
  • read:documents

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

Um modelo de organização é um modelo da estrutura de controlo de acesso para cada organização: ele 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 ao Console Logto > Modelos de Organização > Permissões da Organização e crie duas permissões: read:documents e create:documents.

Em seguida, vamos à aba de papéis de organização para criar dois papéis de utilizador: Admin e Colaborador, e atribuír permissões correspondentes a esses papéis.

Desta forma, criámos um modelo de permissão RBAC para cada organização.

A seguir, vamos à página de detalhes da Nossa Organização para atribuir papéis apropriados aos nossos membros.

Agora, os nossos utilizadores de organização têm papéis! Pode alcançar esses passos através da API de Gestão do Logto:

Agora podemos implementar o controle de permissão de utilizador verificando as permissões deles.

No nosso código, precisamos fazer com que o token de organização do utilizador carregue informações de permissão e, em seguida, verificar essas permissões no backend.

Na configuração do Logto do código frontend, precisamos declarar as permissões que os utilizadores precisam solicitar dentro da organização. Vamos adicionar as permissões read:documents e create:documents ao scopes.

Como de costume, faça login novamente com o seu utilizador para que estas configurações entrem em vigor.

Então no middleware requireOrganizationAccess do backend, adicionamos verificação para permissões do utilizador.

Depois, crie uma API POST /documents e use o middleware requireOrganizationAccess com a configuração requiredScopes para proteger esta API e a API GET /documents anterior.

Desta forma, implementámos o controlo de permissão de utilizador verificando suas permissões.

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

Controlar elementos da página com base nas permissões de utilizador verificando os escopos nas reivindicações.

Adicionar mais recursos para a app multi-inquilino#

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

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

Resumo#

Lembra-se de como era avassalador no início? Utilizadores, organizações, permissões, funcionalidades empresariais... parecia uma montanha interminável para escalar.

Mas olhe o que realizámos:

• Um sistema completo de autenticação com múltiplas opções de login e suporte a MFA
• Um sistema organizacional flexível que suporta múltiplas adesões
• Controle de acesso baseado em função dentro das organizações

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

O código fonte completo deste tutorial está disponível em: Multi-tenant SaaS Sample.

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

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