Criando um SDK de framework baseado em Node.js para Logto em minutos

Anteriormente, neste artigo, criamos um SDK web para Logto em minutos. Agora, vamos nos concentrar no Node.js, outra plataforma popular para desenvolvedores de JavaScript.

Neste guia, vamos te guiar pelos passos para criar um SDK simples para Express para Logto usando @logto/node. Este SDK implementará o fluxo de login, e você pode seguir os mesmos passos para criar um SDK para qualquer outra plataforma baseada em Node.js, como Koa, Next.js, NestJS, etc.

O fluxo de login#

Antes de começarmos, vamos revisar o fluxo de login no Logto. O fluxo de login é composto pelas seguintes etapas:

1. Redirecionar para o Logto: O usuário é redirecionado para a página de login do Logto.
2. Autenticação: O usuário insere suas credenciais e se autentica com o Logto.
3. Redirecionar de volta para o seu app: Após a autenticação bem-sucedida, o usuário é redirecionado de volta para o seu app com um código de autenticação.
4. Troca de código: Seu app troca o código de autenticação por tokens e armazena os tokens como o estado de autenticação.

Breve introdução do @logto/node#

Semelhante ao @logto/browser, o pacote @logto/node expõe uma classe LogtoClient que fornece as funcionalidades principais do Logto, incluindo métodos para o fluxo de login:

1. signIn(): Gera a URL de autenticação OIDC e redireciona para ela.
2. handleSignInCallback(): Verifica e analisa a URL de retorno de chamada e extrai o código de autenticação, depois troca o código por tokens chamando o endpoint de token.
3. getContext(): Obtém o contexto da solicitação atual com base no cookie da sessão, incluindo o estado de autenticação e as informações do usuário.

Criando o SDK para Express#

No SDK, forneceremos dois manipuladores de rota (/sign-in e /sign-in-callback), junto com um middleware withLogto:

1. /sign-in: Um manipulador de rota que aciona o fluxo de login com uma resposta que redireciona para a URL de autenticação OIDC.
2. /sign-in-callback: Um manipulador de rota que processa a URL de retorno de chamada, troca o código de autenticação por tokens, os armazena e completa o fluxo de login.
3. withLogto middleware: Um middleware que chama getContext() para recuperar o contexto da solicitação atual, incluindo o estado de autenticação e as informações do usuário.

Para usar o SDK, você pode simplesmente adicionar o middleware ao seu app Express para proteger as rotas e usar os manipuladores de rota para acionar o fluxo de login e lidar com o retorno de chamada.

Passo 1: Instale o pacote#

Primeiro, instale o pacote @logto/node usando npm ou outro gerenciador de pacotes:

Passo 2: Prepare o adaptador de armazenamento#

É necessário um adaptador de armazenamento para inicializar a instância do LogtoClient.

Supondo que o usuário do SDK já tenha configurado a sessão no express, podemos simplesmente implementar a classe Storage criando um novo arquivo storage.ts:

Passo 3: Implemente os manipuladores de rota#

A solicitação HTTP não tem estado, então precisamos inicializar a instância do cliente para cada solicitação. Vamos preparar uma função auxiliar para criar a instância do cliente:

Nesta função, implementamos o adaptador navigate junto com o adaptador ExpressStorage. O adaptador navigate é usado para redirecionar o usuário para a URL de login.

Em seguida, vamos implementar os manipuladores de rota, embalados em uma função handleAuthRoutes:

1. O manipulador de rota /auth/sign-in aciona o fluxo de login chamando signIn(), um estado de login é armazenado na sessão e será utilizado pelo manipulador de rota /auth/sign-in-callback.
2. O manipulador de rota /auth/sign-in-callback lida com a URL de retorno de chamada e troca o código de autenticação por tokens chamando handleSignInCallback(), os tokens são armazenados na sessão pelo adaptador ExpressStorage. Após a troca, o usuário é redirecionado de volta para a página inicial.

Passo 4: Implemente o middleware#

O middleware withLogto é usado para proteger rotas. Ele chama getContext() para obter o contexto da solicitação atual, incluindo o estado de autenticação e as informações do usuário.

A função getContext usa o adaptador de armazenamento para obter os tokens da sessão.

Ponto de verificação: usando o SDK#

Agora que você criou o SDK Express para Logto, você pode usá-lo no seu app adicionando o middleware para proteger as rotas e usando os manipuladores de rota para acionar o fluxo de login e lidar com o retorno de chamada.

Aqui está um exemplo simples de como usar o SDK no seu app Express:

Neste exemplo, usamos o middleware withLogto para verificar o estado de autenticação e redirecionar o usuário para a página de login caso ele não esteja autenticado. Caso contrário, exibimos uma mensagem de boas-vindas.

Você pode conferir o projeto de exemplo oficial para Express aqui.

Conclusão#

Neste guia, te guiamos pelos passos para criar um SDK para Express implementando o fluxo básico de autenticação. O SDK fornecido aqui é um exemplo básico. Você pode estendê-lo adicionando mais métodos e funcionalidades para atender às necessidades do seu app.

Você pode seguir os mesmos passos para criar um SDK para qualquer outra plataforma baseada em JavaScript que rode em Node.js.

Recursos:

1. Logto Node SDK
2. Logto Express SDK