Creare un SDK basato su Node.js per Logto in pochi minuti

In precedenza, in questo articolo, abbiamo creato un SDK web per Logto in pochi minuti. Ora concentriamoci su Node.js, un'altra popolare piattaforma per sviluppatori JavaScript.

In questa guida, ti guideremo nei passaggi per creare un semplice SDK Express per Logto utilizzando @logto/node. Questo SDK implementerà il flusso di accesso e puoi seguire gli stessi passaggi per creare un SDK per qualsiasi altra piattaforma basata su Node.js come Koa, Next.js, NestJS, ecc.

Il flusso di accesso#

Prima di iniziare, rivediamo il flusso di accesso in Logto. Il flusso di accesso comprende i seguenti passaggi:

1. Reindirizzamento a Logto: L'utente viene reindirizzato alla pagina di accesso di Logto.
2. Autenticazione: L'utente immette le proprie credenziali e si autentica con Logto.
3. Reindirizzamento alla tua app: Dopo l'autenticazione riuscita, l'utente viene reindirizzato alla tua app con un codice di autorizzazione.
4. Scambio del codice: La tua app scambia il codice di autorizzazione per i token e li memorizza come stato di autenticazione.

Breve introduzione di @logto/node#

Simile a @logto/browser, il pacchetto @logto/node espone una classe LogtoClient che fornisce le funzionalità principali di Logto, inclusi i metodi per il flusso di accesso:

1. signIn(): Genera l'URL di autenticazione OIDC e reindirizza ad esso.
2. handleSignInCallback(): Controlla e analizza l'URL di callback ed estrae il codice di autorizzazione, quindi scambia il codice per i token chiamando l'endpoint token.
3. getContext(): Ottieni il contesto della richiesta corrente basato sul cookie di sessione, compreso lo stato di autenticazione e le informazioni dell'utente.

Creazione dell'SDK Express#

Nell'SDK forniremo due handler di route (/sign-in e /sign-in-callback) insieme a un middleware withLogto:

1. /sign-in: Un handler di route che avvia il flusso di accesso con una risposta che reindirizza all'URL di autenticazione OIDC.
2. /sign-in-callback: Un handler di route che elabora l'URL di callback, scambia il codice di autorizzazione per i token, li memorizza e completa il flusso di accesso.
3. Middleware withLogto: Un middleware che chiama getContext() per recuperare il contesto della richiesta corrente, includendo lo stato di autenticazione e le informazioni dell'utente.

Per utilizzare l'SDK, puoi semplicemente aggiungere il middleware alla tua app Express per proteggere le route e usare gli handler di route per avviare il flusso di accesso e gestire il callback.

Passo 1: Installa il pacchetto#

Prima di tutto, installa il pacchetto @logto/node utilizzando npm o altri gestori di pacchetti:

Passo 2: Prepara l'adattatore di storage#

È necessario un adattatore di storage per inizializzare l'istanza di LogtoClient.

Supponendo che l'utente dell'SDK abbia già configurato la sessione express, possiamo semplicemente implementare la classe Storage creando un nuovo file storage.ts:

Passo 3: Implementa gli handler di route#

La richiesta HTTP è stateless, quindi dobbiamo inizializzare l'istanza del client per ogni richiesta. Prepariamo una funzione helper per creare l'istanza del client:

In questa funzione, implementiamo l'adattatore navigate insieme all'adattatore ExpressStorage. L'adattatore navigate viene utilizzato per reindirizzare l'utente all'URL di accesso.

Successivamente, implementiamo gli handler di route, incapsulati in una funzione handleAuthRoutes:

1. L'handler di route /auth/sign-in avvia il flusso di accesso chiamando signIn(), uno stato di accesso viene memorizzato nella sessione e verrà consumato dall'handler di route /auth/sign-in-callback.
2. L'handler di route /auth/sign-in-callback gestisce l'URL di callback e scambia il codice di autorizzazione per i token chiamando handleSignInCallback(), i token vengono memorizzati nella sessione dall'adattatore ExpressStorage. Dopo che lo scambio è completato, l'utente viene reindirizzato alla home page.

Passo 4: Implementa il middleware#

Il middleware withLogto viene utilizzato per proteggere le route. Chiama getContext() per ottenere il contesto della richiesta corrente, inclusi lo stato di autenticazione e le informazioni sull'utente.

La funzione getContext utilizza l'adattatore di storage per ottenere i token dalla sessione.

Verifica: utilizzo dell'SDK#

Ora che hai creato l'SDK Express per Logto, puoi usarlo nella tua app aggiungendo il middleware per proteggere le route e utilizzando gli handler di route per avviare il flusso di accesso e gestire il callback.

Ecco un semplice esempio di come utilizzare l'SDK nella tua app Express:

In questo esempio, utilizziamo il middleware withLogto per verificare lo stato di autenticazione e reindirizzare l'utente alla pagina di accesso se non è autenticato, altrimenti mostriamo un messaggio di benvenuto.

Puoi consultare il progetto di esempio ufficiale di Express qui.

Conclusione#

In questa guida ti abbiamo guidato attraverso i passaggi per creare un SDK Express per Logto implementando il flusso di autenticazione di base. L'SDK fornito qui è un esempio di base. Puoi estenderlo aggiungendo più metodi e funzionalità per soddisfare le esigenze della tua app.

Puoi seguire gli stessi passaggi per creare un SDK per qualsiasi altra piattaforma basata su JavaScript che gira su Node.js.

Risorse:

1. Logto Node SDK
2. Logto Express SDK