Usar Logto Management API: Um guia passo a passo

Embora o Logto forneça um Console baseado na web para gerenciar identidades, usar a Management API é uma poderosa alternativa quando você deseja automatizar seu fluxo de trabalho ou acessar o Logto programaticamente. Este guia irá guiá-lo através das etapas para usar o Logto Management API em diferentes cenários.

Visão geral#

Você pode notar que há um recurso de API embutido "Logto Management API" no Logto Console. Ele será a peça-chave neste guia.

Comparado a outros recursos de API, atualmente o Logto Management API não permite acesso direto de usuários finais, pois é projetado para comunicação de máquina para máquina, e é tão poderoso que pode ser usado para gerenciar sua conta Logto e recursos.

Aqui estão alguns cenários típicos onde você pode querer usar o Logto Management API:

CI/CD

Comunicação de serviço

Aplicação de página única

Servidor web que renderiza HTML

Arquitetura#

Independentemente dos cenários, há dois padrões que você pode usar para acessar o Logto Management API.

Padrão 1: Acesso direto

Neste padrão, seu cliente ou serviço acessará diretamente o Logto Management API. No Logto, o cliente ou serviço é chamado de app "machine-to-machine".

Um exemplo de uso de serviço de backend:

Padrão 2: Acesso indireto

Neste padrão, seu cliente ou serviço acessará o Logto Management API através de um serviço de backend. O padrão 2 é construído sobre o padrão 1, que envolve outro app. O novo app pode ser um web tradicional, nativo ou aplicação de página única que acessará o serviço de backend.

Um exemplo de uso de aplicação de página única:

Este padrão é útil quando você deseja ter lógica customizada para controlar o acesso ao Logto Management API. Por exemplo, você pode querer retornar todos os pedidos para um consumidor e anexar as informações do vendedor a cada pedido. Nesse caso, você pode usar a aplicação de página única para solicitar o serviço de backend para obter os pedidos e, no serviço de backend, usar o Logto Management API para obter as informações do vendedor.

Acessar Logto Management API#

Criar um app machine-to-machine#

Primeiro, você precisa criar um app machine-to-machine no Logto Console. Vá para a aba "Aplicações" e clique no botão "Criar aplicação". Depois clique em "Começar a construir" na cartão "Machine-to-machine".

Configurar uma função de machine-to-machine#

Para acessar o Logto Management API, você precisa criar uma função de machine-to-machine com as permissões adequadas. No Logto Console, vá para a aba "Funções" e clique no botão "Criar função". Clique em "Mostrar mais opções" e selecione "Função de app machine-to-machine" na seção "Tipo de função".

Agora você pode ver a "Logto Management API" aparecer na seção "Atribuir permissões". Marque o recurso da API para todas as permissões e clique no botão "Criar função".

Uma vez que a função é criada, você pode atribuí-la ao app machine-to-machine que você criou no passo anterior.

Obter token de acesso#

Você pode seguir os passos neste artigo para obter um token de acesso via concessão de credenciais de cliente para seu app machine-to-machine. Teste o token de acesso enviando uma solicitação para um endpoint no Logto Management API.

Agora você está pronto para o padrão 1. Note que o token de acesso é válido por um curto período de tempo, então você pode querer atualizá-lo periodicamente se desejar armazená-lo em cache.

Adicionar outra camada#

Embora o acesso ao Logto Management API não seja permitido para usuários finais, você pode adicionar outra camada para aproveitar o poder do Logto Management API e deixar que ele potencialize seu serviço.

Por exemplo, você está construindo uma comunidade online com uma aplicação de página única e um serviço de backend. Você pode querer ter um recurso que permita aos usuários logados ver os 10 principais usuários que têm mais seguidores. Um endpoint GET /api/top-users será criado:

Para garantir que o endpoint seja acessível apenas por usuários logados, você pode criar uma "aplicação de página única" no Logto Console e integrar o Logto SDK nesse app. Depois, você pode usar o SDK para obter o token de acesso e enviar a solicitação ao endpoint:

No serviço de backend, você pode primeiro consultar os 10 principais usuários do banco de dados e então usar o Logto Management API para obter as informações do usuário:

Finalmente, você pode devolver a resposta para a aplicação de página única:

Um diagrama de sequência completo:

Neste fluxo, ele envolve dois tipos de tokens de acesso: um para o serviço de backend acessar o Logto Management API e o outro para a aplicação de página única acessar o serviço de backend.

O primeiro token de acesso é o que você obteve na seção anterior. O segundo token de acesso é aquele que você pode obter com o Logto SDK.

Meu token de acesso na aplicação de página única não é um JSON Web Token (JWT)

Se você não especificar o recurso ao chamar o método getAccessToken nos SDKs do Logto, o token de acesso será uma string opaca que é destinada para ser usada no endpoint userinfo. Para obter um JWT:

1. Defina um recurso de API no Logto Console, por exemplo, https://api.example.com.
2. Adicione o recurso de API ao resources config do Logto SDK, por exemplo, resources: ['https://api.example.com'].
3. Chame o método getAccessToken com o recurso de API, por exemplo, getAccessToken('https://api.example.com').

Para validar o JWT no seu serviço de backend, consulte Validar o token de autorização da solicitação de API.

O que o JWT na aplicação de página única implica?

O JWT apenas implica que o usuário fez login e tenta acessar o recurso da API. Não implica que o usuário tenha permissões específicas do recurso da API. Cabe a você decidir se concede ao usuário acesso ao recurso da API.

Se você precisar de controle de acesso mais granular, também pode aplicar controle de acesso baseado em função (RBAC) ao usuário. Veja 🔐 Controle de acesso baseado em função (RBAC) para detalhes.

Notas finais#

O Logto Management API é poderoso e flexível para múltiplos cenários. Com a ajuda de protocolos padrão, você pode facilmente integrar o Logto Management API em sua aplicação e construir um sistema seguro e escalável. Se você tiver alguma dúvida, sinta-se à vontade para nos contactar.