Pular para o conteúdo principal

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

Use o template de organização para gerenciar e aplicar papéis e permissões em nível de organização no Logto, controlando o acesso a recursos e fluxos dentro do contexto de uma organização.

O que são permissões de organização (não-API)?​

As permissões de organização (não-API) controlam o que os usuários podem fazer dentro do contexto de uma organização, mas não são aplicadas no nível da API. Em vez disso, elas governam o acesso a recursos do aplicativo, elementos da interface, fluxos ou ações de negócio, e não a APIs de backend.

Casos de uso incluem

  • Convidar ou gerenciar membros dentro de uma organização
  • Atribuir ou alterar papéis da organização
  • Gerenciar cobrança, configurações ou funções administrativas de uma organização
  • Acesso a dashboards, análises ou ferramentas internas que não possuem endpoints de API

O Logto permite proteger essas permissões de organização usando OAuth 2.1 e RBAC, além de suportar arquiteturas SaaS multi-tenant.

Essas permissões são gerenciadas por meio de papéis de organização definidos no template de organização. Todas as organizações usam o mesmo template, garantindo um modelo de permissões consistente em todas as organizações.

Como funciona no Logto​

  • RBAC em nível de organização: Papéis e permissões são definidos no template de organização. Quando um usuário entra em uma organização, ele recebe um ou mais papéis, concedendo permissões específicas.
  • Aplicação não-API: As permissões são verificadas e aplicadas na interface do seu app, fluxo de trabalho ou lógica de backend, não necessariamente por um gateway de API.
  • Separação da proteção de API: As permissões de organização (não-API) são distintas das permissões de recursos de API. Você pode combinar ambas para cenários avançados.
Permissões de organização RBAC

Visão geral da implementação​

  1. Defina permissões de organização no Logto, no template de organização.
  2. Crie papéis de organização que agrupem as permissões necessárias para ações específicas da organização.
  3. Atribua papéis a usuários ou clientes dentro de cada organização.
  4. Obtenha um token de organização (JWT) para a organização atual usando o refresh token ou o fluxo de client credentials.
  5. Valide os tokens de acesso na interface ou backend do seu app para aplicar as permissões de organização.

Fluxo de autorização: autenticando e protegendo permissões de organização​

O fluxo a seguir mostra como um cliente (web, mobile ou backend) obtém e usa tokens de organização para aplicação de permissões não-API.

Observe que o fluxo não inclui detalhes exaustivos sobre parâmetros ou cabeçalhos necessários, mas foca nos passos principais. Continue lendo para ver como o fluxo funciona na prática.

Autenticação do usuário = navegador/app. M2M = serviço de backend ou script usando client credentials + contexto de organização.

Etapas de implementação​

Registrar permissões de organização​

  1. Acesse Console → Template de organização → Permissões de organização.
  2. Defina as permissões de organização necessárias (ex.: invite:member, manage:billing, view:analytics).

Para o passo a passo completo, veja Definir permissões de organização.

Configurar papéis de organização​

  1. Acesse Console → Template de organização → Papéis de organização.
  2. Crie papéis que agrupem as permissões de organização definidas anteriormente (ex.: admin, member, billing).
  3. Atribua esses papéis a usuários ou clientes dentro de cada organização.

Para o passo a passo completo, veja Usar papéis de organização.

Obter tokens de organização (não-API)​

Seu cliente/app deve obter um token de organização (não-API) para acessar permissões de organização. O Logto emite tokens de organização como JSON Web Tokens (JWTs). Você pode obtê-los usando o fluxo de refresh token ou o fluxo de client credentials.

Fluxo de refresh token​

Quase todos os SDKs oficiais do Logto suportam a obtenção de tokens de organização usando o fluxo de refresh token nativamente. Uma biblioteca padrão de cliente OAuth 2.0 / OIDC também pode ser usada para implementar esse fluxo.

Ao inicializar o Logto SDK, adicione urn:logto:scope:organizations e as permissões de organização desejadas (escopos) ao parâmetro scopes.

Alguns SDKs do Logto possuem um escopo predefinido para organizações, como UserScope.Organizations em SDKs JavaScript.

nota:

Inspecione a reivindicação organizations no Token de ID (ID token) para obter uma lista de IDs das organizações às quais o usuário pertence. Essa reivindicação lista todas as organizações das quais o usuário é membro, facilitando a enumeração ou troca de organizações em seu aplicativo.

Use getOrganizationToken ou método similar (como getAccessToken com um ID de organização) para solicitar um token de organização para uma organização específica.

Para detalhes de cada SDK, veja Inícios rápidos.

Fluxo de client credentials​

Para cenários máquina para máquina (M2M), você pode usar o fluxo de client credentials para obter um token de acesso para permissões de organização. Fazendo uma requisição POST para o endpoint /oidc/token do Logto com parâmetros de organização, você pode solicitar um token de organização usando seu client ID e secret.

Aqui estão os principais parâmetros a serem incluídos na requisição:

  • organization_id: O ID da organização para a qual deseja o token.
  • scope: As permissões de organização que deseja solicitar (ex.: invite:member, manage:billing).

Veja um exemplo não normativo da requisição de token usando o grant type client credentials:

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials
&organization_id=your-organization-id
&scope=invite:member manage:billing

Validar tokens de organização​

Os tokens de organização emitidos pelo Logto (JWTs) contêm reivindicações que seu app/interface/backend pode usar para aplicar o controle de acesso em nível de organização.

Quando seu app recebe um token de organização, você deve:

  • Verificar a assinatura do token (usando os JWKs do Logto).
  • Confirmar que o token não está expirado (reivindicação exp).
  • Checar se o iss (emissor) corresponde ao seu endpoint Logto.
  • Garantir que o aud (público) corresponde ao identificador formatado da organização (ex.: urn:logto:organization:{organization_id}).
  • Separar a reivindicação scope (separada por espaço) e verificar as permissões necessárias.

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

Optional: Handle user permission change​

User permissions can change at any time. Because Logto issues JWTs for RBAC, permission updates only appear in newly issued tokens, and never modify existing JWTs.

Scope subset rule:

An access token can only include scopes that were requested in the original OAuth authorization flow. Even if a user gains new permissions, the token issued later can only contain a subset of the originally requested scopes. To access newly granted scopes that were not part of the initial request, the client must run a new authorization flow.

Downscoped permissions​

When a user loses permissions:

  • Newly issued tokens immediately reflect the reduced scopes.
  • Existing JWTs keep the old scopes until they expire.
  • Your API should always validate scopes and rely on short token lifetimes.

If you need faster reactions, implement your own signal that tells clients to refresh their tokens.

Enlarged permissions​

For organization tokens, when a user gains permissions, enlarged permissions will show up on the next issuance (refresh or token request). A new token is still required, but no full re-auth is needed unless the new scopes exceed the original request set.

Recommendations​

  • Validate scopes in your API on every call.
  • Keep token expiration short.
  • Add optional notifications if you need immediate permission-change propagation.

Boas práticas e dicas de segurança​

  • Nunca confie apenas na aplicação pela interface: Sempre valide permissões no backend para ações críticas.
  • Use restrições de público: Sempre verifique a reivindicação aud para garantir que o token é para a organização pretendida.
  • Mantenha as permissões orientadas ao negócio: Use nomes claros que correspondam a ações reais; conceda apenas o necessário para cada papel da organização.
  • Separe permissões de API e não-API quando possível (mas ambas podem estar em um único papel).
  • Revise o template de organização regularmente conforme seu produto evolui.

Perguntas frequentes​

Posso misturar permissões de organização e não-organização em um único papel?​

Não, permissões de organização (incluindo permissões de API em nível de organização) são definidas pelo template de organização e não podem ser misturadas com permissões globais de API. No entanto, você pode criar papéis que incluam tanto permissões de organização quanto permissões de API em nível de organização.

Onde devo aplicar permissões não-API?​

Verifique permissões não-API tanto na interface (para controle de recursos) quanto na lógica do servidor para ações sensíveis.

Leitura adicional​

Como validar tokens de acesso Personalizando reivindicações de token

Caso de uso: Construir um aplicativo SaaS multi-tenant