Crafting a Node.js based framework SDK for Logto in minutes

Previously in this article, we crafted a web SDK for Logto in minutes. Now, let's focus on Node.js, another popular platform for JavaScript developers.

In this guide, we will walk you through the steps to create a simple Express SDK for Logto using @logto/node. This SDK will implement the sign-in flow, and you can follow the same steps to create an SDK for any other Node.js-based platform such as Koa, Next.js, NestJS, etc.

The sign-in flow#

Before we start, let's review the sign-in flow in Logto. The sign-in flow comprises of the following steps:

1. Redirect to Logto: The user is redirected to the Logto sign-in page.
2. Authenticate: The user inputs their credentials and authenticates with Logto.
3. Redirect back to your app: After successful authentication, the user is redirected back to your app with an auth code.
4. Code exchange: Your app exchanges the auth code for tokens and stores the tokens as the authentication state.

Brief introduction of @logto/node#

Similar to @logto/browser, the @logto/node package exposes a LogtoClient class that provides the core functionalities of Logto, including methods for sign-in flow:

1. signIn(): Generates the OIDC auth URL, and redirects to it.
2. handleSignInCallback(): Checks and parse the callback URL and extract the auth code, then exchange the code for tokens by calling token endpoint.
3. getContext(): Get the context of the current request based on the session cookie, including the authentication state and user information.

Crafting the Express SDK#

In the SDK, we will provide two route handlers (/sign-in and /sign-in-callback) along with a withLogto middleware:

1. /sign-in: A route handler that triggers the sign-in flow with a response that redirects to the OIDC auth URL.
2. /sign-in-callback: A route handler that processes the callback URL, exchanges the auth code for tokens, stores them, and completes the sign-in flow.
3. withLogto middleware: A middleware that calls getContext() to retrieve the context of the current request, including the authentication state and user information.

To use the SDK, you can simply add the middleware to your Express app to protect routes, and use the route handlers to trigger the sign-in flow and handle the callback.

Step 1: Install the package#

First, install the @logto/node package using npm or other package managers:

Step 2: Prepare the storage adapter#

A storage adapter is required to initialize the LogtoClient instance.

Assuming that the SDK user already setup the express session, we can simply implement the Storage class by creating a new file storage.ts:

Step 3: Implement the route handlers#

The HTTP request is stateless, so we need to init the client instance for each request. Let's prepare a function helper to create the client instance:

In this function, we implement the navigate adapter along with the ExpressStorage adapter. The navigate adapter is used to redirect the user to the sign in URL.

Next, let's implement the route handlers, wrapped in a function handleAuthRoutes:

1. The /auth/sign-in route handler triggers the sign-in flow by calling signIn(), a sign-in state is stored in the session, and will be consumed by the /auth/sign-in-callback route handler.
2. The /auth/sign-in-callback route handler handles the callback URL and exchanges the auth code for tokens by calling handleSignInCallback(), the tokens are stored in the session by the ExpressStorage adapter. After the exchange is done, the user is redirected back to the home page.

Step 4: Implement the middleware#

The withLogto middleware is used to protect routes. It calls getContext() to get the context of the current request, including the authentication state and user information.

The function getContext uses the storage adapter to get the tokens from the session.

Checkpoint: using the SDK#

Now that you have crafted the Express SDK for Logto, you can use it in your app by adding the middleware to protect routes and using the route handlers to trigger the sign-in flow and handle the callback.

Here is a simple example of how to use the SDK in your Express app:

In this example, we use the withLogto middleware to check the authentication state, and redirect the user to the sign-in page if they are not authenticated, otherwise, we display a welcome message.

You can check the official Express sample project here.

Conclusion#

In this guide, we have walked you through the steps to create a Express SDK for Logto implementing the basic auth flow. The SDK provided here is a basic example. You can extend it by adding more methods and functionalities to meet your app's needs.

You can follow the same steps to create an SDK for any other JavaScript-based platform that runs in Node.js.

Resources:

1. Logto Node SDK
2. Logto Express SDK