Создание SDK на базе фреймворка Node.js для Logto за считанные минуты

Ранее в этой статье мы создали веб-SDK для Logto за считанные минуты. Теперь давайте сосредоточимся на Node.js, ещё одной популярной платформе для разработчиков на JavaScript.

В этом руководстве мы проведём вас через шаги по созданию простого SDK на базе Express для Logto, используя @logto/node. Этот SDK будет реализовывать поток входа, и вы сможете повторить те же шаги для создания SDK для любой другой платформы, основанной на Node.js, такой как Koa, Next.js, NestJS и т.д.

Поток входа#

Прежде чем начать, давайте рассмотрим поток входа в Logto. Поток входа состоит из следующих шагов:

1. Перенаправление на Logto: Пользователь перенаправляется на страницу входа в Logto.
2. Аутентификация: Пользователь вводит свои учетные данные и аутентифицируется в Logto.
3. Перенаправление обратно в ваше приложение: После успешной аутентификации пользователь перенаправляется обратно в ваше приложение с кодом авторизации.
4. Обмен кода на токены: Ваше приложение обменивает код авторизации на токены и сохраняет их как состояние аутентификации.

Краткое введение в @logto/node#

Подобно @logto/browser, пакет @logto/node предоставляет класс LogtoClient, который реализует основные функции Logto, включая методы для потока входа:

1. signIn(): Генерирует URL для авторизации OIDC и перенаправляет на него.
2. handleSignInCallback(): Проверяет и анализирует URL-адрес обратного вызова, извлекает код авторизации и обменивает код на токены через конечную точку токенов.
3. getContext(): Получает контекст текущего запроса на основе куки сессии, включая состояние аутентификации и информацию о пользователе.

Создание SDK для Express#

В SDK мы предоставим два обработчика маршрутов (/sign-in и /sign-in-callback) вместе с middleware withLogto:

1. /sign-in: Обработчик маршрута, который инициирует поток входа с ответом, перенаправляющим на URL авторизации OIDC.
2. /sign-in-callback: Обработчик маршрута, который обрабатывает URL-адрес обратного вызова, обменивает код авторизации на токены, сохраняет их и завершает поток входа.
3. Middleware withLogto: Middleware, который вызывает функцию getContext() для получения контекста текущего запроса, включая состояние аутентификации и информацию о пользователе.

Для использования SDK вы можете просто добавить middleware в ваше приложение на Express для защиты маршрутов и использовать обработчики маршрутов для запуска потока входа и обработки обратного вызова.

Шаг 1: Установка пакета#

Сначала установите пакет @logto/node с помощью npm или других менеджеров пакетов:

Шаг 2: Подготовка адаптера хранения#

Для инициализации экземпляра LogtoClient требуется адаптер хранения.

Предполагая, что пользователь SDK уже настроил сессию Express, мы можем просто реализовать класс Storage, создав новый файл storage.ts:

Шаг 3: Реализация обработчиков маршрутов#

HTTP-запросы не сохраняют состояние, поэтому для каждого запроса нужно инициализировать экземпляр клиента. Давайте подготовим вспомогательную функцию для создания экземпляра клиента:

В этой функции мы реализуем адаптер navigate вместе с адаптером ExpressStorage. Адаптер navigate используется для перенаправления пользователя на URL авторизации.

Теперь давайте реализуем обработчики маршрутов, которые будут обёрнуты в функцию handleAuthRoutes:

1. Обработчик маршрута /auth/sign-in инициирует поток входа, вызывая signIn(). Состояние входа сохраняется в сессии и будет использовано обработчиком маршрута /auth/sign-in-callback.
2. Обработчик маршрута /auth/sign-in-callback обрабатывает URL-адрес обратного вызова и обменивает код авторизации на токены, вызывая handleSignInCallback(). Токены сохраняются в сессии адаптером ExpressStorage. После завершения обмена пользователь перенаправляется на главную страницу.

Шаг 4: Реализация middleware#

Middleware withLogto используется для защиты маршрутов. Оно вызывает getContext() для получения контекста текущего запроса, включая состояние аутентификации и информацию о пользователе.

Функция getContext использует адаптер хранилища для получения токенов из сессии.

Контрольная точка: использование SDK#

Теперь, когда вы создали SDK на базе Express для Logto, вы можете использовать его в своём приложении, добавив middleware для защиты маршрутов и используя обработчики маршрутов для запуска потока входа и обработки обратного вызова.

Вот простой пример того, как использовать SDK в вашем приложении на Express:

В этом примере мы используем middleware withLogto для проверки состояния аутентификации и перенаправляем пользователя на страницу входа, если он не аутентифицирован, в противном случае мы отображаем приветственное сообщение.

Вы можете ознакомиться с официальным примером проекта на Express здесь.

Заключение#

В этом руководстве мы рассмотрели шаги по созданию SDK для Express, реализующего базовый поток аутентификации в Logto. Здесь представлен базовый пример SDK. Вы можете расширить его, добавив больше методов и функциональности в зависимости от потребностей вашего приложения.

Вы можете следовать тем же шагам для создания SDK для любой другой платформы на JavaScript, работающей на Node.js.

Ресурсы:

1. Logto Node SDK
2. Logto Express SDK