Usar la API de Gestión de Logto: Una guía paso a paso

Aunque Logto ofrece una consola web para que administres identidades, usar la API de Gestión es una alternativa poderosa cuando deseas automatizar tu flujo de trabajo o acceder a Logto de manera programática. Esta guía te llevará a través de los pasos para usar la API de Gestión de Logto en diferentes escenarios.

Descripción general#

Puedes notar que hay un recurso de API incorporado "API de Gestión de Logto" en la consola de Logto. Será la pieza clave en esta guía.

Comparado con otros recursos de API, actualmente la API de Gestión de Logto no permite el acceso directo por parte de los usuarios finales porque está diseñada para la comunicación máquina a máquina, y es tan poderosa que puede ser usada para gestionar tu cuenta y recursos de Logto.

Aquí hay algunos escenarios típicos en los que podrías querer usar la API de Gestión de Logto:

CI/CD

Comunicación de servicio

Aplicación de una sola página

Servidor web que renderiza HTML

Arquitectura#

Independientemente de los escenarios, hay dos patrones que puedes usar para acceder a la API de Gestión de Logto.

Patrón 1: Acceso directo

En este patrón, tu cliente o servicio accederá directamente a la API de Gestión de Logto. En Logto, el cliente o servicio se llama una aplicación "máquina a máquina".

Un ejemplo de usar un servicio de backend:

Patrón 2: Acceso indirecto

En este patrón, tu cliente o servicio accederá a la API de Gestión de Logto a través de un servicio de backend. El patrón 2 se construye sobre el patrón 1, que involucra otra aplicación. La nueva aplicación puede ser una web tradicional, nativa, o aplicación de una sola página que accederá al servicio de backend.

Un ejemplo de usar una aplicación de una sola página:

Este patrón es útil cuando deseas tener lógica personalizada para controlar el acceso a la API de Gestión de Logto. Por ejemplo, quizás desees devolver todos los pedidos para un consumidor y adjuntar la información del vendedor a cada pedido. En este caso, puedes usar la aplicación de una sola página para solicitar el servicio de backend para obtener los pedidos, y en el servicio de backend, puedes usar la API de Gestión de Logto para obtener la información del vendedor.

Acceder a la API de Gestión de Logto#

Crear una aplicación máquina a máquina#

Primero, necesitas crear una aplicación máquina a máquina en la consola de Logto. Dirígete a la pestaña "Aplicaciones" y haz clic en el botón "Crear aplicación". Luego haz clic en "Comenzar a construir" en la tarjeta "Máquina a máquina".

Configurar un rol máquina a máquina#

Para acceder a la API de Gestión de Logto, necesitas crear un rol máquina a máquina con los permisos adecuados. En la consola de Logto, dirígete a la pestaña "Roles" y haz clic en el botón "Crear rol". Haz clic en "Mostrar más opciones" y selecciona "Rol de aplicación máquina a máquina" en la sección "Tipo de rol".

Ahora puedes ver que "API de Gestión de Logto" aparece en la sección "Asignar permisos". Marca el recurso de API para todos los permisos y haz clic en el botón "Crear rol".

Una vez que el rol está creado, puedes asignarlo a la aplicación máquina a máquina que creaste en el paso anterior.

Obtener token de acceso#

Puedes seguir los pasos en este artículo para obtener un token de acceso a través del establecimiento de credenciales de cliente para tu aplicación máquina a máquina. Prueba el token de acceso enviando una solicitud a un endpoint en la API de Gestión de Logto.

Ahora estás listo para el patrón 1. Ten en cuenta que el token de acceso es válido por un corto período de tiempo, por lo que podrías querer actualizarlo periódicamente si quieres almacenarlo en caché.

Agregar otra capa#

Aunque no se permite a los usuarios finales acceder a la API de Gestión de Logto, puedes agregar otra capa para aprovechar el poder de la API de Gestión de Logto y permitirle potenciar tu servicio.

Por ejemplo, estás construyendo una comunidad en línea con una aplicación de una sola página y un servicio de backend. Puede que quieras tener una función que permita a los usuarios registrados ver los 10 usuarios con más seguidores. Se creará un endpoint GET /api/top-users:

Para asegurarte de que el endpoint sea accesible solo por usuarios registrados, puedes crear una "aplicación de una sola página" en la consola de Logto, y integrar el SDK de Logto en esa aplicación. Luego puedes usar el SDK para obtener el token de acceso y enviar la solicitud al endpoint:

En el servicio de backend, puedes primero consultar los 10 mejores usuarios de la base de datos, y luego usar la API de Gestión de Logto para obtener la información del usuario:

Finalmente, puedes devolver la respuesta a la aplicación de una sola página:

Un diagrama de secuencia completo:

En este flujo, se involucran dos tipos de tokens de acceso: uno para el servicio de backend para acceder a la API de Gestión de Logto, y el otro para la aplicación de una sola página para acceder al servicio de backend.

El primer token de acceso es el que obtuviste en la sección anterior. El segundo token de acceso es el que puedes obtener del SDK de Logto.

Mi token de acceso en la aplicación de una sola página no es un Token Web JSON (JWT)

Si no especificas el recurso al llamar al método getAccessToken en los SDK de Logto, el token de acceso será una cadena opaca que está destinada para ser usada en el endpoint de información del usuario. Para obtener un JWT:

1. Define un recurso de API en la consola de Logto, por ejemplo, https://api.example.com.
2. Agrega el recurso de API a la configuración resources del SDK de Logto, por ejemplo, resources: ['https://api.example.com'].
3. Llama al método getAccessToken con el recurso de API, por ejemplo, getAccessToken('https://api.example.com').

Para validar el JWT en tu servicio de backend, por favor, consulta Validar el token de autorización de la solicitud API.

¿Qué implica el JWT en la aplicación de una sola página?

El JWT solo implica que el usuario ha iniciado sesión y trata de acceder al recurso de API. No implica que el usuario tenga permisos específicos del recurso de API. Depende de ti decidir si le concedes al usuario acceso al recurso de API.

Si necesitas un control de acceso más granular, también puedes aplicar control de acceso basado en roles (RBAC) al usuario. Consulta 🔐 Control de acceso basado en roles (RBAC) para más detalles.

Notas finales#

La API de Gestión de Logto es poderosa y flexible para múltiples escenarios. Con la ayuda de protocolos estándar, puedes integrar fácilmente la API de Gestión de Logto en tu aplicación y construir un sistema seguro y escalable. Si tienes alguna pregunta, no dudes en contactarnos.