Criar um SDK baseado em Node.js para Logto em minutos

Anteriormente neste artigo, criámos um SDK web para Logto em minutos. Agora, vamos focar em Node.js, outra plataforma popular para programadores de JavaScript.

Neste guia, vamos guiá-lo pelos passos para criar um SDK simples para Express usando @logto/node. Este SDK irá implementar o fluxo de início de sessão, 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 início de sessão#

Antes de começarmos, vamos rever o fluxo de início de sessão no Logto. O fluxo de início de sessão compreende os seguintes passos:

1. Redirecionar para Logto: O utilizador é redirecionado para a página de início de sessão do Logto.
2. Autenticar: O utilizador insere as suas credenciais e autentica-se com o Logto.
3. Redirecionar de volta para a sua aplicação: Após a autenticação bem-sucedida, o utilizador é redirecionado de volta para a sua aplicação com um código de autenticação.
4. Troca de código: A sua aplicação troca o código de autenticação por tokens e armazena os tokens como o estado de autenticação.

Breve introdução ao @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 início de sessão:

1. signIn(): Gera o URL de autenticação OIDC e redireciona para ele.
2. handleSignInCallback(): Verifica e analisa o URL de callback e extrai o código de autenticação, depois troca o código por tokens chamando o endpoint de tokens.
3. getContext(): Obtém o contexto do pedido atual com base no cookie de sessão, incluindo o estado de autenticação e as informações do utilizador.

Criando o SDK para Express#

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

1. /sign-in: Um manipulador de rota que inicia o fluxo de início de sessão com uma resposta que redireciona para o URL de autenticação OIDC.
2. /sign-in-callback: Um manipulador de rota que processa o URL de callback, troca o código de autenticação por tokens, armazena-os e completa o fluxo de início de sessão.
3. withLogto middleware: Um middleware que chama getContext() para obter o contexto do pedido atual, incluindo o estado de autenticação e as informações do utilizador.

Para usar o SDK, você pode simplesmente adicionar o middleware à sua app Express para proteger as rotas, e usar os manipuladores de rotas para iniciar o fluxo de início de sessão e lidar com o callback.

Passo 1: Instalar o pacote#

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

Passo 2: Preparar o adaptador de armazenamento#

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

Assumindo que o utilizador do SDK já configurou a sessão Express, podemos simplesmente implementar a classe Storage criando um novo ficheiro storage.ts:

Passo 3: Implementar os manipuladores de rotas#

O pedido HTTP é sem estado, por isso precisamos de iniciar a instância do cliente para cada pedido. Vamos preparar uma função helper para criar a instância do cliente:

Nesta função, implementamos o adaptador navigate juntamente com o adaptador ExpressStorage. O adaptador navigate é usado para redirecionar o utilizador para o URL de início de sessão.

A seguir, vamos implementar os manipuladores de rotas, envolvidos numa função handleAuthRoutes:

1. O manipulador da rota /auth/sign-in inicia o fluxo de início de sessão chamando signIn(), um estado de início de sessão é armazenado na sessão e será consumido pelo manipulador da rota /auth/sign-in-callback.
2. O manipulador da rota /auth/sign-in-callback lida com o URL de callback e troca o código de autenticação por tokens chamando handleSignInCallback(), os tokens são armazenados na sessão pelo adaptador ExpressStorage. Depois da troca estar concluída, o utilizador é redirecionado de volta para a página inicial.

Passo 4: Implementar o middleware#

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

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 para Express do Logto, pode usá-lo na sua aplicação adicionando o middleware para proteger rotas e utilizando os manipuladores de rotas para iniciar o fluxo de início de sessão e lidar com o callback.

Aqui está um exemplo simples de como usar o SDK na sua aplicação Express:

Neste exemplo, usamos o middleware withLogto para verificar o estado de autenticação e redirecionar o utilizador para a página de início de sessão se não estiver autenticado, caso contrário, exibimos uma mensagem de boas-vindas.

Você pode verificar o projeto de exemplo oficial do Express aqui.

Conclusão#

Neste guia, passámos pelos passos para criar um SDK para Express do Logto implementando o fluxo de autenticação básico. O SDK fornecido aqui é um exemplo básico. Você pode expandi-lo adicionando mais métodos e funcionalidades para atender às necessidades da sua aplicação.

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

Recursos:

1. Logto Node SDK
2. Logto Express SDK