몇 분 안에 Logto 를 위한 Node.js 기반 프레임워크 SDK 제작하기

이전 기사에서는 몇 분 만에 Logto 를 위한 웹 SDK 를 제작했습니다. 이제, JavaScript 개발자들에게 인기가 많은 또 다른 플랫폼인 Node.js 에 초점을 맞춰보겠습니다.

이 가이드에서는 @logto/node를 사용하여 Logto 를 위한 간단한 Express SDK 를 만드는 단계에 대해 설명합니다. 이 SDK 는 로그인 흐름을 구현하며, 다른 Node.js 기반 플랫폼(Koa, Next.js, NestJS 등)을 위해 SDK 를 만들기 위해 동일한 단계를 따를 수 있습니다.

로그인 흐름#

시작하기 전에, Logto 에서의 로그인 흐름을 검토해 봅시다. 로그인 흐름은 다음 단계로 이루어집니다:

1. Logto 로 리디렉션: 사용자가 Logto 로그인 페이지로 리디렉션됩니다.
2. 인증: 사용자가 크리덴셜을 입력하고 Logto 와 함께 인증합니다.
3. 앱으로 다시 리디렉션: 인증에 성공하면 사용자는 인증 코드와 함께 앱으로 다시 리디렉션됩니다.
4. 코드 교환: 앱이 인증 코드를 토큰으로 교환하고 이 토큰을 인증 상태로 저장합니다.

@logto/node 간단 소개#

@logto/browser와 유사하게, @logto/node 패키지는 Logto 의 주요 기능을 제공하는 LogtoClient 클래스를 노출합니다. 여기에 로그인 흐름을 위한 메소드도 포함되어 있습니다:

1. signIn(): OIDC 인증 URL 을 생성하고 그곳으로 리디렉션합니다.
2. handleSignInCallback(): 콜백 URL 을 확인하고 분석하여 인증 코드를 추출한 후, 토큰 엔드포인트를 호출하여 코드와 토큰을 교환합니다.
3. getContext(): 세션 쿠키를 기반으로 현재 요청의 컨텍스트를 가져오며, 인증 상태와 사용자 정보를 포함합니다.

Express SDK 제작#

이 SDK 에서는 두 개의 라우트 핸들러(/sign-in 및 /sign-in-callback)와 withLogto 미들웨어를 제공합니다:

1. /sign-in: OIDC 인증 URL 로 리디렉션하는 응답과 함께 로그인 흐름을 시작하는 라우트 핸들러입니다.
2. /sign-in-callback: 콜백 URL 을 처리하고, 인증 코드를 토큰과 교환하여 저장하고, 로그인 흐름을 완료하는 라우트 핸들러입니다.
3. withLogto 미들웨어: 현재 요청의 컨텍스트를 가져오기 위해 getContext()를 호출하는 미들웨어로, 인증 상태와 사용자 정보를 포함합니다.

SDK 를 사용하려면, 미들웨어를 Express 앱에 추가하여 라우트를 보호하고, 라우트 핸들러를 사용하여 로그인 흐름을 트리거하고 콜백을 처리하세요.

1단계: 패키지 설치#

먼저, npm 또는 다른 패키지 관리자를 사용하여 @logto/node 패키지를 설치하세요:

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단계: 미들웨어 구현#

withLogto 미들웨어는 라우트를 보호하는 데 사용됩니다. 이 미들웨어는 getContext()를 호출하여 현재 요청의 컨텍스트, 인증 상태 및 사용자 정보를 가져옵니다.

getContext 함수는 세션에서 토큰을 가져오기 위해 스토리지 어댑터를 사용합니다.

체크포인트: SDK 사용하기#

이제 Logto 를 위한 Express SDK 를 제작했으니, 이를 앱에서 사용하여 라우트를 보호하고, 라우트 핸들러를 사용하여 로그인 흐름을 트리거하고 콜백을 처리할 수 있습니다.

여기에서 Express 앱에서 SDK 를 사용하는 간단한 예제를 확인할 수 있습니다:

이 예제에서는 withLogto 미들웨어를 사용하여 인증 상태를 확인하고, 사용자가 인증되지 않은 경우 로그인 페이지로 리디렉션하며, 그렇지 않은 경우 환영 메시지를 표시합니다.

공식 Express 샘플 프로젝트는 여기에서 확인할 수 있습니다.

결론#

이 가이드에서는 기본 인증 흐름을 구현한 Logto 를 위한 Express SDK 를 만드는 단계를 설명했습니다. 여기 제공된 SDK 는 기본적인 예제이며, 필요에 따라 더 많은 메소드 및 기능을 추가하여 확장할 수 있습니다.

같은 단계를 따라 Node.js 에서 실행되는 다른 JavaScript 기반 플랫폼에 대한 SDK 도 만들 수 있습니다.

참고 자료:

1. Logto Node SDK
2. Logto Express SDK