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 funcionalidades 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 funcionalidades do aplicativo, elementos da interface, fluxos de trabalho 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 através 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 entre 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 as permissões de organização no Logto, dentro do 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 fluxo de token de atualização ou 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 utiliza tokens de organização para aplicação de permissões não-API.

Observe que o fluxo não inclui detalhes exaustivos sobre os 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.

Passos 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 token de atualização ou o fluxo client credentials.

Fluxo de token de atualização​

Quase todos os SDKs oficiais do Logto suportam a obtenção de tokens de organização usando o fluxo de token de atualização 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 pré-definido 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 um 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 client credentials​

Para cenários máquina para máquina (M2M), você pode usar o fluxo 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.

Boas práticas e dicas de segurança​

  • Nunca confie apenas na aplicação na 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 de organização.
  • Separe permissões de API e não-API sempre que 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, as 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 permissões de organização e 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 funcionalidades) 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