Crear un SDK de framework basado en Node.js para Logto en minutos

Anteriormente, en este artículo, creamos un SDK web para Logto en minutos. Ahora, centrémonos en Node.js, otra plataforma popular para desarrolladores de JavaScript.

En esta guía, te guiaremos a través de los pasos para crear un simple SDK de Express para Logto usando @logto/node. Este SDK implementará el flujo de inicio de sesión, y puedes seguir los mismos pasos para crear un SDK para cualquier otra plataforma basada en Node.js, como Koa, Next.js, NestJS, etc.

El flujo de inicio de sesión#

Antes de comenzar, repasemos el flujo de inicio de sesión en Logto. El flujo de inicio de sesión comprende los siguientes pasos:

1. Redirigir a Logto: El usuario es redirigido a la página de inicio de sesión de Logto.
2. Autenticarse: El usuario ingresa sus credenciales y se autentica con Logto.
3. Redirigir de vuelta a tu aplicación: Después de la autenticación exitosa, el usuario es redirigido de vuelta a tu aplicación con un código de autorización.
4. Intercambio de código: Tu aplicación intercambia el código de autorización por tokens y almacena los tokens como estado de autenticación.

Breve introducción a @logto/node#

Similar a @logto/browser, el paquete @logto/node expone una clase LogtoClient que proporciona las funcionalidades principales de Logto, incluyendo métodos para el flujo de inicio de sesión:

1. signIn(): Genera la URL de autenticación OIDC y redirige a ella.
2. handleSignInCallback(): Verifica y analiza la URL del callback y extrae el código de autorización, luego intercambia el código por tokens al llamar al endpoint de token.
3. getContext(): Obtén el contexto de la solicitud actual basado en la cookie de sesión, incluyendo el estado de autenticación e información del usuario.

Crear el SDK de Express#

En el SDK, proporcionaremos dos manejadores de rutas (/sign-in y /sign-in-callback) junto con un middleware withLogto:

1. /sign-in: Un manejador de rutas que inicia el flujo de inicio de sesión con una respuesta que redirige a la URL de autenticación OIDC.
2. /sign-in-callback: Un manejador de rutas que procesa la URL del callback, intercambia el código de autorización por tokens, los almacena y completa el flujo de inicio de sesión.
3. Middleware withLogto: Un middleware que llama a getContext() para recuperar el contexto de la solicitud actual, incluyendo el estado de autenticación e información del usuario.

Para usar el SDK, simplemente puedes añadir el middleware a tu aplicación Express para proteger las rutas y usar los manejadores de rutas para iniciar el flujo de inicio de sesión y manejar el callback.

Paso 1: Instalar el paquete#

Primero, instala el paquete @logto/node usando npm u otros gestores de paquetes:

Paso 2: Preparar el adaptador de almacenamiento#

Se requiere un adaptador de almacenamiento para inicializar la instancia de LogtoClient.

Suponiendo que el usuario del SDK ya configuró la sesión de express, podemos simplemente implementar la clase Storage creando un nuevo archivo storage.ts:

Paso 3: Implementar los manejadores de rutas#

La solicitud HTTP es sin estado, por lo que necesitamos inicializar la instancia del cliente para cada solicitud. Vamos a preparar una función auxiliar para crear la instancia del cliente:

En esta función, implementamos el adaptador navigate junto con el adaptador ExpressStorage. El adaptador navigate se usa para redirigir al usuario a la URL de inicio de sesión.

A continuación, implementemos los manejadores de rutas, envueltos en una función handleAuthRoutes:

1. El manejador de la ruta /auth/sign-in inicia el flujo de inicio de sesión llamando a signIn(), se almacena un estado de inicio de sesión en la sesión y será consumido por el manejador de la ruta /auth/sign-in-callback.
2. El manejador de la ruta /auth/sign-in-callback maneja la URL del callback e intercambia el código de autorización por tokens llamando a handleSignInCallback(), los tokens se almacenan en la sesión mediante el adaptador ExpressStorage. Después de completar el intercambio, el usuario es redirigido de vuelta a la página de inicio.

Paso 4: Implementar el middleware#

El middleware withLogto se utiliza para proteger las rutas. Llama a getContext() para obtener el contexto de la solicitud actual, incluyendo el estado de autenticación y la información del usuario.

La función getContext usa el adaptador de almacenamiento para obtener los tokens de la sesión.

Punto de control: usando el SDK#

Ahora que has creado el SDK de Express para Logto, puedes usarlo en tu aplicación añadiendo el middleware para proteger rutas y usando los manejadores de rutas para iniciar el flujo de inicio de sesión y manejar el callback.

Aquí tienes un ejemplo simple de cómo usar el SDK en tu aplicación Express:

En este ejemplo, usamos el middleware withLogto para verificar el estado de autenticación y redirigir al usuario a la página de inicio de sesión si no está autenticado, de lo contrario, mostramos un mensaje de bienvenida.

Puedes consultar el proyecto de ejemplo oficial de Express aquí.

Conclusión#

En esta guía, te hemos llevado a través de los pasos para crear un SDK de Express para Logto implementando el flujo de autenticación básico. El SDK proporcionado aquí es un ejemplo básico. Puedes extenderlo añadiendo más métodos y funcionalidades para satisfacer las necesidades de tu aplicación.

Puedes seguir los mismos pasos para crear un SDK para cualquier otra plataforma basada en JavaScript que se ejecute en Node.js.

Recursos:

1. Logto Node SDK
2. Logto Express SDK