Controle de acesso baseado em papel (RBAC)

Controle de acesso baseado em papel (RBAC) (Role-based access control (RBAC)) é um modelo de autorização comprovado que mapeia ações de negócios do mundo real para papéis e permissões. Este guia cobre como o RBAC funciona no Logto, padrões de design práticos e melhores práticas para construir aplicações SaaS seguras e escaláveis.

O que é RBAC?

O RBAC permite que você gerencie quem pode fazer o quê em sua aplicação agrupando permissões em papéis. Usuários e clientes recebem um ou mais papéis, que concedem as permissões necessárias para acessar funcionalidades, APIs ou dados.

Conceitos principais

• Papel (Role): Um conjunto nomeado de permissões (ex: admin, viewer, billing-manager).
• Permissão (Permission): Uma ação ou direito (ex: manage:members, view:analytics).
• Escopo (Scope): Um sinônimo para permissão, comumente usado em contextos OAuth 2.0.
• Recurso de API (API resource): Uma API, endpoint ou serviço ao qual as permissões se aplicam.
• Usuário/Cliente (User/Client): A entidade à qual os papéis são atribuídos (usuários finais ou aplicativos máquina para máquina (M2M)).

nota:

No Logto (e no OAuth 2.1), "permissões" e "escopos" referem-se ao mesmo conceito e são usados de forma intercambiável nesta documentação.

Recursos de API

Um recurso de API (API resource) é qualquer endpoint ou serviço protegido em sua aplicação—como uma API REST, endpoint GraphQL ou outro serviço backend que requer autorização.

O Logto modela recursos de API seguindo o RFC 8707: Resource Indicators for OAuth 2.0.
Cada recurso de API é identificado de forma única por um indicador de recurso (resource indicator) (um URI), que é usado para delimitar tokens de acesso e impor restrições de público.

Nome da propriedade	Descrição	Obrigatório
Nome da API	Um nome amigável para identificar o recurso de API no Console e nos logs.	Sim
Identificador da API	O URI único do indicador de recurso que representa o recurso de API.	Sim
Tempo de expiração do token	O tempo de vida dos tokens de acesso emitidos para esta API (em segundos). O padrão é 3600 (1 hora).	Não
API padrão	Apenas um recurso de API pode ser definido como padrão por tenant Logto. Quando definido, o parâmetro resource pode ser omitido das solicitações de autenticação.	Não

nota:

Quando um recurso de API padrão é designado, o Logto o usará como público para os tokens quando o parâmetro resource for omitido nas solicitações de autenticação.

Comportamento do recurso de API padrão

No Logto, toda permissão global definida pelo usuário (escopo) deve estar vinculada a um recurso de API. Caso contrário, a permissão é tratada como um escopo OpenID Connect (OIDC).

Isso geralmente não afeta a maioria das integrações, mas ao trabalhar com aplicativos de terceiros que não suportam o RFC 8707, a solicitação inicial de autorização pode não incluir um parâmetro resource. Nesses casos, o Logto emite tokens de acesso opacos (opaque access tokens) em vez de JWTs, o que pode complicar o controle de acesso.

Para resolver isso, você pode definir um recurso de API padrão para seu tenant:

• Quando o parâmetro resource estiver ausente na Solicitação de autenticação (Authentication request):
  • O Logto usa o recurso de API padrão como público para os tokens de acesso.
• Se o escopo openid estiver incluído:
  • O Logto emite um token de acesso opaco para o endpoint Userinfo quando não há resource presente na solicitação de token.
• Se o escopo openid não estiver incluído:
  • O Logto emite um token de acesso JWT para o recurso de API padrão como público.

Definir um recurso de API padrão garante uma integração mais suave com aplicativos que não suportam o RFC 8707, mantendo controles de acesso seguros e baseados em padrões.

RBAC no Logto

O Logto fornece RBAC flexível tanto em nível global quanto organizacional para suportar SaaS multi-tenant:

• Papéis globais (Global roles): Atribuídos em todo o tenant Logto. Ideal para permissões em todo o produto, administradores ou superusuários.
• Papéis de organização (Organization roles): Atribuídos dentro de uma organização. Perfeito para acesso específico da organização, como administradores de workspace, membros de projeto ou grupos personalizados.
• Recursos de API (API resources): APIs e funcionalidades registradas que requerem autorização.
• Permissões (escopos) (Permissions (scopes)): Definidas por recurso de API ou no template da organização.
  • Permissões de recurso de API podem ser atribuídas a papéis globais ou de organização.
  • Permissões de organização só podem ser atribuídas a papéis de organização.

Dependendo das necessidades do seu produto, você pode usar esses modelos RBAC separadamente ou em combinação.

Abaixo estão três exemplos ilustrativos com diagramas:

Modelo 1: Recursos de API globais

Cenário

Um produto SaaS com APIs compartilhadas entre todos os usuários, independentemente da organização. Use papéis globais para controlar o acesso a recursos de API em todo o produto.

Diagrama

Pontos-chave

• Usuários e aplicativos M2M recebem papéis globais (ex: Gerente de loja, Agente de serviço).
• Papéis concedem permissões (escopos), como read:store, order:book.
• Permissões são vinculadas diretamente a recursos de API (ex: https://read.shop/stores).

Quando usar

Quando o acesso não é específico da organização ou usuários/clientes operam em todas as organizações.

nota:

O Logto não suporta permissões que não sejam de API em nível global, pois este é reservado para escopos OpenID Connect (OIDC).

dica:

Para um guia passo a passo de implementação, veja Proteger recursos de API globais.

Modelo 2: Permissões de organização (não-API)

Cenário

Controlando funcionalidades ou fluxos internos do aplicativo que não são aplicados na camada de API (como restringir recursos de UI, dashboards ou ferramentas internas) usando papéis e permissões de organização.

Diagrama

Pontos-chave

• Cada organização (A e B) tem suas próprias atribuições, mas todas compartilham um conjunto comum de papéis definidos no template da organização.
• Usuários e aplicativos M2M podem ter papéis diferentes em cada organização.
• Papéis de organização (ex: Admin, Membro) concedem permissões de organização como invite:member, manage:billing.
• Permissões são aplicadas na UI do app ou na lógica de negócio, não pelo gateway de API.

Quando usar

Quando você deseja gerenciar quem pode ver ou usar funcionalidades dentro de uma organização quando a aplicação na camada de API não é necessária.

dica:

Para um guia passo a passo de implementação, veja Proteger permissões de organização (não-API).

Modelo 3: Recursos de API em nível de organização

Cenário

Uma plataforma SaaS multi-tenant onde cada organização tem seus próprios membros, dados e papéis. Use papéis de organização para conceder acesso à API dentro de cada organização.

Diagrama

Pontos-chave

• Cada organização (A e B) tem suas próprias atribuições, mas todas compartilham um conjunto comum de papéis definidos no template da organização.
• Usuários e aplicativos M2M podem ter papéis diferentes em cada organização.
• Permissões (escopos), como invite:member, manage:billing são vinculadas a recursos de API.
• Permissões são aplicadas na camada de API quando o token de acesso inclui um contexto de organização.

Quando usar

Quando você precisa controlar o acesso à API com base no contexto da organização, como permitir que usuários gerenciem os dados de sua própria organização.

dica:

Para um guia passo a passo de implementação, veja Proteger recursos de API em nível de organização.

Projetar e implementar um modelo de permissões

De acordo com a arquitetura do seu produto e as necessidades dos usuários, você pode escolher um modelo RBAC adequado dos exemplos acima. Aqui está um resumo para ajudar você a projetar e implementar seu modelo de permissões de forma eficaz:

Modelo de permissão	Definir recursos de API com permissões?	Definir permissões de organização?	Usar papéis globais?	Usar papéis de organização?
Recursos de API globais	✅	n/a	✅	n/a
Permissões de organização (não-API)	n/a	✅	n/a	✅
Recursos de API em nível de organização	✅	n/a	n/a	✅

Definir recursos de API com permissões

Registre suas APIs no Logto Console ou via Management API para definir os recursos de API e suas permissões (escopos).

nota:

No OAuth 2.0 e OIDC, um "recurso de API" é tecnicamente chamado de indicador de recurso, um URI único que identifica sua API ou serviço protegido.

Registrar recursos de API com permissões no Logto Console

1. Vá para Console → Recursos de API.

2. Clique em Criar recurso de API.

3. Forneça:

   • Nome da API: Nome legível para sua API.
   • Identificador da API: Indicador do recurso de API (ex: https://api.yourapp.com/org).

4. Na aba Permissões, clique em Criar permissão para criar permissões (escopos) para este recurso de API.

5. Na aba Geral, você pode opcionalmente definir o seguinte:

   • Tempo de expiração do token: Defina por quanto tempo os tokens de acesso para este recurso de API serão válidos. Recomendamos manter curto (ex: 1 hora) por segurança.
   • API padrão: Defina este recurso de API como padrão para restrição de público e emissão de tokens se nenhum resource for especificado na solicitação OAuth. Isso é opcional e pode ser útil para clientes que não suportam o parâmetro resource (por exemplo, algumas ferramentas ou plugins de terceiros).

Dicas

• Mapeie indicadores de recurso de API para os endpoints reais da API para fornecer nomes intuitivos.
  • Por exemplo, https://api.example.com/v1/users.
• Use nomes claros e baseados em ação (ex: invite:member, manage:billing, view:analytics).
  • Alternativamente, alguns gêneros podem preferir um prefixo ou agrupar por funcionalidade para clareza (ex: billing:read, billing:manage).
• Mantenha as permissões orientadas ao negócio, não apenas a endpoints técnicos.

Exemplo

Indicador de recurso de API	Permissão	Descrição
https://api.example.com/users	invite:user	Convidar novos usuários
https://api.example.com/users	manage:user	Atualizar ou excluir usuários
https://api.example.com/billing	view:billing	Visualizar detalhes de cobrança
https://api.example.com/billing	manage:billing	Editar configurações de cobrança

Definir permissões de organização

Registre permissões de organização no Logto Console ou via Management API para definir permissões que se aplicam dentro de cada organização. As permissões de organização são definidas no template da organização.

Registrar permissões de organização no Logto Console

1. Vá para Console → Template da organização → Permissões de organização.
2. Clique em Criar permissão de organização.
3. Forneça:
   • Nome da permissão: Um nome claro e baseado em ação para a permissão (ex: invite:member, manage:billing).
   • Descrição: Uma breve descrição do que a permissão permite (ex: "Convidar novos membros para a organização").
4. Clique em Criar permissão para salvar.

Dicas

• Use nomes claros e baseados em ação (ex: invite:member, manage:billing).
• Mantenha permissões de organização distintas das permissões de API para evitar confusão.

Exemplo

Permissão de organização	Descrição
invite:member	Convidar novos membros para a organização
manage:billing	Editar configurações de cobrança da organização

Configurar papéis globais

Crie e configure papéis globais no Logto Console ou via Management API para agrupar permissões que se aplicam em todo o tenant Logto.

Um papel global pode ser um dos seguintes:

• Papel de usuário: Atribuído a usuários finais, concedendo permissões para acessar APIs e funcionalidades.
• Papel máquina para máquina (M2M): Atribuído a aplicativos M2M, concedendo permissões para acessar APIs e funcionalidades, incluindo Logto Management API.

nota:

Observe que esses dois tipos de papéis não podem ser misturados ou atualizados após a criação. Atribua usuários ou aplicativos M2M ao papel, dependendo do tipo.

Criar papéis globais no Logto Console

1. Vá para Console → Papéis.
2. Clique em Criar papel.
3. Forneça:
   • Nome do papel: Um nome claro e descritivo para o papel (ex: admin, viewer, billing-manager).
   • Tipo de papel: Escolha entre Usuário ou Máquina para máquina (M2M). Apenas papéis máquina para máquina (M2M) podem vincular ao Logto Management API.
   • Descrição: Uma breve descrição do propósito do papel (ex: "Papel de admin com acesso total", "Papel de visualizador para acesso somente leitura").
   • Atribuir permissões: Selecione as permissões (escopos) que este papel deve ter dos recursos de API disponíveis. Você pode atualizar as permissões depois, se necessário.
4. Clique em Criar papel para salvar.

Atribuir usuários ou aplicativos M2M a papéis globais

1. Vá para Console → Papéis.
2. Clique no papel ao qual deseja atribuir usuários ou aplicativos M2M.
3. Para Papéis de usuário, clique na aba Usuários; para Papéis M2M, clique na aba aplicativos máquina para máquina.
4. Clique em Atribuir usuários ou Atribuir aplicativos M2M.
5. Pesquise os usuários ou aplicativos M2M que deseja atribuir a este papel.
6. Selecione os usuários ou aplicativos M2M e clique em Atribuir.

Papéis globais padrão

Você pode definir um ou mais papéis globais como papéis padrão para novos usuários. Papéis padrão são atribuídos automaticamente quando os usuários são criados, seja por autoinscrição ou criados via Management API. Você pode ativar esta opção na aba "Geral" na página de detalhes em Console > Papéis.

Configurar papéis de organização

Crie papéis de organização no Logto Console ou via Management API para agrupar permissões que se aplicam dentro de cada organização. Papéis de organização são definidos no template da organização.

Um papel de organização pode ser um dos seguintes:

• Papel de usuário: Atribuído a usuários finais dentro de uma organização, concedendo permissões para acessar APIs e funcionalidades.
• Papel máquina para máquina (M2M): Atribuído a aplicativos M2M dentro de uma organização, concedendo permissões para acessar APIs e funcionalidades. Este papel não pode vincular ao Logto Management API, pois é específico da organização.

nota:

Observe que esses dois tipos de papéis não podem ser misturados ou atualizados após a criação. Atribua usuários ou aplicativos M2M ao papel, dependendo do tipo.

Criar papéis de organização no Logto Console

1. Vá para Console → Template da organização → Papéis de organização.

2. Clique em Criar papel de organização.

3. Forneça:

   • Nome do papel: Um nome claro e descritivo para o papel (ex: admin, member, billing-manager).
   • Tipo de papel: Escolha entre Usuário ou Máquina para máquina (M2M). Apenas papéis máquina para máquina (M2M) podem vincular ao Logto Management API.
   • Descrição: Uma breve descrição do propósito do papel (ex: "Papel de admin com acesso total", "Papel de membro para acesso básico").

4. Clique em Criar papel para salvar.

5. No modal Atribuir permissões, selecione as permissões de organização e/ou permissões de recurso de API que este papel deve ter. Você pode atualizar as permissões depois, se necessário.

Atribuir usuários ou aplicativos M2M a papéis de organização

Como papéis de organização são específicos da organização, você precisa atribuir usuários ou aplicativos M2M a papéis de organização dentro do contexto de uma organização.

1. Vá para Console → Organizações.
2. Selecione a organização que deseja gerenciar.
3. Para Papéis de usuário, clique na aba Usuários; para Papéis M2M, clique na aba aplicativos máquina para máquina.
4. Se o usuário ou aplicativo M2M ainda não for membro da organização, clique em Adicionar membro ou Adicionar aplicativo M2M para adicioná-los à organização. Durante esse processo, você pode atribuí-los a um ou mais papéis de organização.
5. Se o usuário ou aplicativo M2M já for membro, clique no menu de três pontos ao lado do nome e selecione Editar papéis de organização.
6. No modal aberto, selecione e salve os papéis de organização que deseja atribuir ao usuário ou aplicativo M2M.

Provisionamento Just-in-time (JIT)

Você também pode atribuir papéis de organização a usuários ou aplicativos M2M no momento em que eles ingressam em uma organização. Para isso, consulte Provisionamento Just-in-time (JIT).

Aplicando autorização no seu backend ou API

O Logto emite JSON Web Tokens (JWTs) que contêm as reivindicações necessárias para aplicar autorização em sua aplicação ou API.

Para aplicar autorização, seu backend ou API deve:

1. Exigir que o cliente apresente um token de acesso válido no cabeçalho da requisição com o formato Authorization: Bearer <token>.
2. Validar o token de acesso para garantir que foi emitido pelo Logto, não expirou e possui as permissões (escopos) necessárias para a ação solicitada.
3. Responder com um erro (ex: HTTP 401 Unauthorized ou HTTP 403 Forbidden) se o token estiver ausente, inválido ou não possuir as permissões necessárias.

Para guias passo a passo e específicos de linguagem, veja Como validar tokens de acesso.

Integrar o RBAC do Logto à sua aplicação

Você pode integrar o RBAC do Logto à sua aplicação usando uma das duas abordagens:

• SDKs Logto: Use um SDK Logto para lidar com os fluxos de autenticação e autorização integrados.
• Bibliotecas padrão OAuth 2.0/OIDC: Use sua biblioteca OAuth 2.0 ou OpenID Connect preferida para implementar os fluxos necessários.

Uma vez integrado, solicite tokens de acesso com os parâmetros corretos para o modelo RBAC escolhido. Adicione o token de acesso ao cabeçalho Authorization em suas requisições de API para aplicar as permissões.

Veja os guias de implementação nas seções dos modelos acima para exemplos passo a passo.

Cenários avançados

Explore casos de uso RBAC mais sofisticados no Logto:

• Combinando papéis globais e de organização: Atribua ambos a usuários/clientes quando necessário; o Logto irá resolver com base no contexto do token solicitado.
• Múltiplos aplicativos: Use recursos e escopos compartilhados para RBAC entre aplicativos.
• Permissões dinâmicas: Se necessário, combine RBAC com verificações em tempo de execução (ex: propriedade, atributos) para cenários avançados.
• Reivindicações personalizadas de token: Use reivindicações personalizadas para enriquecer tokens conforme necessário.

Melhores práticas & armadilhas comuns

• Princípio do menor privilégio: Conceda apenas as permissões que cada papel precisa.
• Evite dispersão de permissões: Mantenha seu modelo de permissões simples e fácil de manter.
• Revise e atualize papéis/permissões: Audite regularmente seu modelo RBAC conforme seu produto evolui.
• Separação de funções: Crie papéis distintos para ações sensíveis/admin.
• Teste o RBAC em staging: Valide limites e escalonamentos de permissões.

Perguntas frequentes

Como atualizo papéis ou permissões em todas as organizações?

Atualize o template da organização para alterações globais; organizações existentes podem herdar as atualizações.

Posso alterar papéis/permissões dinamicamente?

Sim, papéis e suas permissões podem ser atualizados a qualquer momento.

O que acontece se eu remover uma permissão de um papel?

Usuários/clientes com esse papel perderão a permissão imediatamente para novos tokens.

Como posso auditar quem tem qual papel?

Use o Logto Console ou API para listar as atribuições de papéis.

Papéis e permissões podem ser atribuídos via API?

Sim, tanto o Console quanto o Management API suportam o gerenciamento programático de papéis e atribuições.

Leitura adicional

Template da organização Personalizando reivindicações de token Como validar tokens de acesso Proteger recursos de API globais

Proteger permissões de organização (não-API)

Proteger recursos de API em nível de organização