Template de organização
O template de organização no Logto define um conjunto consistente de papéis (roles) e permissões disponíveis para cada organização (tenant) em seu produto SaaS. Ao centralizar essas definições, você pode reforçar a segurança, permitir onboarding escalável e garantir uma excelente experiência do usuário em todas as organizações.
Se você não está construindo um aplicativo multi-tenant ou não precisa de papéis/permissões específicos por organização, pode pular esta seção. Os papéis e permissões globais do Logto são suficientes para aplicativos single-tenant ou que não utilizam organizações.
O que é o template de organização?
Um template de organização é um modelo que especifica quais papéis e permissões estão disponíveis em cada organização. Toda organização criada em seu tenant Logto herda automaticamente o template, garantindo um modelo de autorização consistente em todos os tenants.
- Por que usar um template?
- Impõe políticas de controle de acesso uniformes para cada organização.
- Simplifica o onboarding de novos tenants e membros da equipe.
- Facilita atualizações e auditorias do controle de acesso baseado em papel (RBAC) à medida que seu produto cresce.
Conceitos principais
- Papéis da organização: Coleções de permissões concedidas a usuários ou clientes M2M (máquina para máquina) dentro de uma organização. Os papéis definem "quem pode fazer o quê" dentro de cada organização.
- Permissões da organização: Ações não relacionadas à API, de granularidade fina (por exemplo, recursos de UI, lógica de negócio) que podem ser atribuídas a papéis.
- Recursos de API (API resources): Endpoints/serviços de API protegidos por permissões. Papéis da organização podem ser vinculados a recursos de API para acesso à API com escopo de organização.
- Mapeamento papel-permissão: Cada papel da organização no template pode ser mapeado para uma ou mais permissões.
- Propagação do template: Alterações no template atualizam os papéis e permissões disponíveis para todas as organizações.
Papéis e permissões da organização (incluindo permissões de recursos de API) são distintos dos papéis globais e suas permissões. No entanto, recursos de API e suas permissões são definidos centralmente e podem ser referenciados tanto em contextos globais quanto de organização.
Comparação com papéis e permissões globais
Comparação de tipos de papel
| Tipo de papel | Pode ter permissões de recurso de API? | Pode ter permissões da organização (não-API)? |
|---|---|---|
| Global | Sim | Não |
| Organização | Sim | Sim |
Comparação de tipos de permissões
| Tipo de permissão | Definido em | Atribuível a papéis globais? | Atribuível a papéis de organização? |
|---|---|---|---|
| Recurso de API | Entidade de recurso de API | Sim | Sim |
| Organização | Template de organização | Não | Sim |
Anatomia de um template de organização
Um template de organização é composto por:
- Papéis: Ex.:
Admin,Membro,Visualizador,Financeiro - Permissões da organização: Ex.:
invite:member,manage:billing,view:analytics - Matriz papel-permissão: Um mapeamento de quais permissões (incluindo permissões da organização e permissões de recursos de API) são concedidas por cada papel.
Visão geral visual
Este diagrama ilustra como papéis da organização, permissões e recursos de API se conectam em um template de organização do Logto.
Cada organização criada no Logto terá esse mesmo conjunto de papéis e permissões, e usuários/clientes podem ser atribuídos a papéis por organização conforme necessário.
Use o template de organização em seu produto
O template de organização do Logto foi projetado para aplicações SaaS modernas e multi-tenant onde:
- Cada organização deve ter as mesmas opções de papel e permissão para onboarding, colaboração e gestão.
- Você quer evitar definir papéis/permissões manualmente para cada nova organização.
- Um RBAC consistente é fundamental para conformidade, segurança e confiança do cliente.
- Você precisa evoluir o controle de acesso conforme seu produto muda, sem quebrar organizações existentes.
Exemplos de uso
- Produtos SaaS que oferecem workspaces, equipes ou empresas (cada um sendo um tenant).
- Plataformas com papéis granulares de admin/membro/visualizador por organização.
- Produtos com permissões tanto de API quanto não-API.
Boas práticas & versionamento
- Mantenha papéis e permissões orientados ao negócio: Use nomes claros que correspondam a ações reais (não apenas endpoints técnicos).
- Evite proliferação de papéis/permissões: Comece simples; adicione novos papéis/permissões apenas quando seu produto realmente precisar.
- Comunique mudanças: Avise usuários/admins se as opções de papel ou permissão em suas organizações estiverem prestes a mudar.
- Evolua o template: À medida que seu produto cresce, você pode atualizar o template a qualquer momento. Todas as organizações terão acesso automaticamente aos novos papéis/permissões.
- Versionamento (opcional): Para mudanças maiores, considere versionar seu template e comunicar planos de migração aos seus clientes.
Gerenciando seu template de organização
Você pode gerenciar o template de organização pelo Console → Template de organização ou via Logto Management API.
- Criar papéis: Adicione papéis de usuário e papéis M2M ao seu template. Cada papel fica disponível para todas as organizações em seu tenant Logto.
- Criar permissões: Defina permissões tanto para recursos de API quanto para ações não-API (dentro do app).
- Editar a matriz papel-permissão: Atribua permissões a papéis usando o Console do Logto ou Management API.
- Atualizar ou excluir papéis/permissões: Alterações no template são aplicadas automaticamente a todas as organizações. (Usuários/clientes mantêm suas atribuições de papel; apenas o conjunto de permissões muda.)
Para guias passo a passo sobre como gerenciar papéis e permissões da organização, veja Controle de acesso baseado em papel (RBAC).
Perguntas frequentes
Preciso usar permissões da organização?
Não, permissões da organização são opcionais. Você pode usar o template de organização apenas para definir papéis e permissões de recursos de API, se preferir.
O que acontece se eu alterar o template de organização?
Alterações em papéis ou permissões são refletidas imediatamente em todas as organizações. Usuários e clientes mantêm suas atribuições de papel; apenas o que esses papéis permitem pode mudar.
Posso personalizar papéis ou permissões por organização?
Não diretamente. Templates de organização impõem um modelo consistente em todos os tenants. (Você ainda pode atribuir papéis diferentes para usuários/clientes diferentes em cada organização.)
Como faço rollback ou migro mudanças?
Atualize manualmente o template para restaurar papéis/permissões anteriores. Para migrações complexas, considere estratégias de versionamento.
O que acontece se eu excluir um papel ou permissão?
Usuários/clientes com esse papel perdem acesso às permissões vinculadas a ele. Excluir uma permissão a remove de todos os papéis que a possuíam.
Existem limitações?
A personalização é feita no nível do template, não por organização. Entre em contato se precisar de exceções avançadas por tenant.
Leitura adicional
Proteger permissões da organização (não-API)
Proteger recursos de API no nível da organização
Personalizando reivindicações de token