Utilizar a API de Gestão do Logto: Um guia passo-a-passo

Enquanto o Logto fornece um Console baseado na web para gerir identidades, utilizar a API de Gestão é uma alternativa poderosa quando deseja automatizar o seu fluxo de trabalho ou aceder ao Logto programaticamente. Este guia irá guiá-lo pelos passos para utilizar a API de Gestão do Logto em diferentes cenários.

Visão Geral#

Poderás notar que existe um recurso de API incorporado "API de Gestão do Logto" no Console do Logto. Este será o papel crucial deste guia.

Comparando com outros recursos de API, atualmente a API de Gestão do Logto não permite acesso direto por parte dos usuários finais porque está concebida para comunicação máquina-a-máquina, e é tão poderosa que pode ser usada para gerir a sua conta e recursos do Logto.

Aqui estão alguns cenários típicos em que poderá querer utilizar a API de Gestão do Logto:

CI/CD

Comunicação de serviços

Aplicação de página única

Servidor web que renderiza HTML

Arquitetura#

Independentemente dos cenários, existem dois padrões que pode usar para aceder à API de Gestão do Logto.

Padrão 1: Acesso direto

Neste padrão, o teu cliente ou serviço irá aceder diretamente à API de Gestão do Logto. No Logto, o cliente ou serviço é chamado de aplicação "máquina-a-máquina".

Um exemplo de uso de serviço backend:

Padrão 2: Acesso indireto

Neste padrão, o teu cliente ou serviço irá acessar à API de Gestão do Logto através de um serviço backend. O padrão 2 é construído sobre o padrão 1, que envolve outra aplicação. A nova aplicação pode ser uma aplicação web tradicional, nativa, ou de página única que irá acessar o serviço backend.

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

Este padrão é útil quando deseja ter lógica personalizada para controlar o acesso à API de Gestão do Logto. Por exemplo, pode querer retornar todas as encomendas para um consumidor, e anexar a informação do vendedor a cada encomenda. Neste caso, pode usar a aplicação de página única para solicitar o serviço backend para obter as encomendas, e no serviço backend, pode usar a API de Gestão do Logto para obter a informação do vendedor.

Acessar a API de Gestão do Logto#

Criar uma aplicação máquina-a-máquina#

Primeiro, precisas criar uma aplicação máquina-a-máquina no Console do Logto. Vai ao separador "Aplicações" e clica no botão "Criar aplicação". Depois clica em "Começar a construir" no cartão "Máquina-a-máquina".

Configurar um papel máquina-a-máquina#

Para acessar a API de Gestão do Logto, tens de criar um papel máquina-a-máquina com as permissões adequadas. No Console do Logto, vai ao separador "Papéis" e clica no botão "Criar papel". Clica em "Mostrar mais opções" e seleciona "Papel de aplicação máquina-a-máquina" na seção "Tipo de papel".

Agora podes ver que a "API de Gestão do Logto" aparece na seção "Atribuir permissões". Marca o recurso de API para todas as permissões, e clica no botão "Criar papel".

Uma vez criado o papel, podes atribuí-lo à aplicação máquina-a-máquina que criaste no passo anterior.

Obter token de acesso#

Podes seguir os passos neste artigo para obter um token de acesso através da concessão de credenciais de cliente para a tua aplicação máquina-a-máquina. Testa o token de acesso enviando um pedido a um ponto de acesso na API de Gestão do Logto.

Agora estás pronto para o padrão 1. Observa que o token de acesso é válido por um curto período de tempo, então podes querer renová-lo periodicamente se desejares armazená-lo em cache.

Adicionar outra camada#

Embora o acesso à API de Gestão do Logto não seja permitido para usuários finais, podes adicionar outra camada para aproveitar o poder da API de Gestão do Logto e deixá-la fortalecer o teu serviço.

Por exemplo, estás a construir uma comunidade online com uma aplicação de página única e um serviço backend. Podes querer ter um recurso que permita aos usuários autenticados ver os 10 principais usuários que têm mais seguidores. Um ponto de acesso GET /api/top-users será criado:

Para garantir que o ponto de acesso seja acessível apenas por usuários autenticados, podes criar uma "aplicação de página única" no Console do Logto, e integrar o SDK do Logto nessa aplicação. Depois podes usar o SDK para obter o token de acesso e enviar o pedido ao ponto de acesso:

No serviço backend, podes primeiro consultar os 10 principais usuários da base de dados, e depois usar a API de Gestão do Logto para obter a informação dos usuários:

Finalmente, podes retornar a resposta para a aplicação de página única:

Um diagrama de sequência completo:

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

O primeiro token de acesso é o que obtiveste na seção anterior. O segundo token de acesso é o que podes obter do SDK do Logto.

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

Se não especificares o recurso ao chamar o método getAccessToken nos SDKs do Logto, o token de acesso será uma string opaca destinada a ser usada para o ponto de acesso userinfo. Para obter um JWT:

1. Define um recurso de API no Console do Logto, por exemplo, https://api.example.com.
2. Adiciona o recurso de API à configuração resources do SDK do Logto, por exemplo, resources: ['https://api.example.com'].
3. Chama o método getAccessToken com o recurso de API, por exemplo, getAccessToken('https://api.example.com').

Para validar o JWT no teu serviço backend, por favor consulta Validar o token de autorização do pedido de API.

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

O JWT apenas implica que o usuário se autenticou e tenta acessar ao recurso da API. Não implica que o usuário tenha permissões específicas do recurso da API. Cabe a ti decidir se deves conceder ao usuário acesso ao recurso da API.

Se precisas de controle de acesso mais granular, podes também aplicar controle de acesso baseado em papéis (RBAC) ao usuário. Veja 🔐 Controle de acesso baseado em papéis (RBAC) para detalhes.

Notas de Encerramento#

A API de Gestão do Logto é poderosa e flexível para múltiplos cenários. Com a ajuda de protocolos padrão, podes facilmente integrar a API de Gestão do Logto na tua aplicação e construir um sistema seguro e escalável. Se tiveres alguma dúvida, por favor não hesites em contactar-nos.