@point3-logto-module은 Logto 인증 시스템을 NestJS 환경에서 손쉽게 통합할 수 있도록 설계된 모듈 번들입니다.
OAuth, M2M(Machine-to-Machine), 사용자/역할 관리, 토큰 검증, 인증 가드 등 인증/권한 관련 기능을 일관된 DI 패턴으로 제공합니다.

유연한 로깅 연동: 외부 로거 모듈/토큰을 DI로 주입받아, 다양한 로깅 시스템과 쉽게 통합
NestJS Dynamic Module 패턴: 환경/구성에 따라 동적으로 모듈 생성
실제 서비스에서 검증된 인증/권한 관리 기능: OAuth, M2M, 사용자/역할 관리, 토큰 검증, 인증 가드 등

🏗️ 주요 구성요소

1. LogtoModule (Dynamic Module)

외부에서 로거 모듈과 토큰을 주입받아, Logto 인증/권한 기능을 번들로 제공
logto.module.LogtoModule.forLogger(loggerModule, loggerToken) 패턴으로 사용

2. 핵심 서비스/토큰

OAuthClient: OAuth 인증(로그인/로그아웃 URI, 토큰 발급 등)
LogtoM2MClient: 서버 간(M2M) 인증 및 사용자/역할 관리
LogtoLoginSession: 세션 기반 로그인 플로우 관리
LogtoTokenVerifier: JWT 토큰 검증 및 권한 체크
LogtoTokenGuard: NestJS 인증 가드(컨트롤러 보호)
LogtoLoggerServiceToken: DI로 주입받는 외부 로거 토큰
stateless: 미들웨어/핸들러 기반의 Stateless 인증/인가 유틸리티 및 가드 제공

3. 주요 타입/설정

LogtoConfig: 인증/권한 기능을 위한 환경설정 객체
Prompt, GrantType: OAuth 표준 파라미터 Enum
LogtoUser, LogtoRole 등: 사용자/역할 관리용 타입

⚙️ 설치

npm install @point3/logto-module

🚀 사용법

1. 외부 로거 모듈 준비

// my-logger.module.ts
import { Module } from '@nestjs/common';
import { WinstonLoggerService } from './winston-logger.service';

export const MY_LOGGER_TOKEN = Symbol.for('LOGGER');

@Module({
  providers: [
    {
      provide: MY_LOGGER_TOKEN,
      useClass: WinstonLoggerService,
    },
  ],
  exports: [MY_LOGGER_TOKEN],
})
export class MyLoggerModule {}

2. AppModule에서 LogtoModule 동적 생성

import { Module } from '@nestjs/common';
import * as logto from '@point3/logto-module';
import { MyLoggerModule, MY_LOGGER_TOKEN } from './my-logger.module';

@Module({
  imports: [
    logto.module.LogtoModule.forLogger(MyLoggerModule, MY_LOGGER_TOKEN),
  ],
})
export class AppModule {}

3. 서비스 DI 및 사용 예시 (클래식 DI)

import { Injectable, Inject } from '@nestjs/common';
import { client } from '@point3/logto-module';

@Injectable()
export class AuthService {
  constructor(
    @Inject(client.OAuthClientToken)
    private readonly oauthClient: InstanceType<typeof client.OAuthClient>,
    @Inject(client.LogtoM2MClientToken)
    private readonly m2mClient: InstanceType<typeof client.LogtoM2MClient>,
    @Inject(client.LogtoLoginSessionToken)
    private readonly loginSession: InstanceType<typeof client.LogtoLoginSession>,
  ) {}

  // OAuth 로그인 URI 생성
  async loginUri() {
    return this.oauthClient.getSignInURI('admin');
  }

  // M2M 사용자 생성
  async createUser(user) {
    return this.m2mClient.createUser(user);
  }

  // 세션 기반 로그인 플로우 예시
  async sessionLoginFlow(username: string, password: string) {
    const session = await this.loginSession.createSignInSession(username);
    await this.loginSession.verifyPassword(session.sessionId, password);
    // ... 추가 플로우
  }
}

4. stateless 네임스페이스 활용 예시

4-1. Express/Fastify 미들웨어로 토큰 인증

// main.ts
import { stateless } from '@point3/logto-module';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  // JWT Bearer 토큰 인증 미들웨어 (stateless)
  app.use(stateless.createTokenAuthMiddleware({
    requiredScopes: ['admin'],
    requiredRoles: ['superuser'],
  }));
  await app.listen(3000);
}
bootstrap();

4-2. 커스텀 가드/핸들러에서 stateless 유틸리티 활용

// custom.guard.ts
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
import { stateless } from '@point3/logto-module';

@Injectable()
export class MyStatelessGuard implements CanActivate {
  async canActivate(context: ExecutionContext): Promise<boolean> {
    const req = context.switchToHttp().getRequest();
    // stateless 토큰 검증 및 권한 체크
    const payload = await stateless.verifyRequestToken(req, {
      requiredScopes: ['user'],
    });
    // payload에 따라 추가 로직 가능
    return !!payload;
  }
}

4-3. 커스텀 데코레이터로 유저 정보 추출

// user.decorator.ts
import { createParamDecorator, ExecutionContext } from '@nestjs/common';
import { stateless } from '@point3/logto-module';

export const CurrentUser = createParamDecorator(
  async (data, ctx: ExecutionContext) => {
    const req = ctx.switchToHttp().getRequest();
    const payload = await stateless.verifyRequestToken(req);
    return payload;
  },
);

// 컨트롤러에서 사용
@Get('me')
getMe(@CurrentUser() user) {
  return user;
}

4-4. NestJS Provider로 stateless 가드 등록

// app.module.ts
import { Module } from '@nestjs/common';
import { stateless } from '@point3/logto-module';

@Module({
  providers: [
    {
      provide: 'STATLESS_GUARD',
      useClass: stateless.StatelessTokenGuard,
    },
  ],
})
export class AppModule {}

4-5. 직접 토큰 검증/유저 정보 추출 (서비스/핸들러 등)

import { stateless } from '@point3/logto-module';

async function handleRequest(req) {
  const payload = await stateless.verifyRequestToken(req);
  if (!payload) throw new Error('인증 실패');
  // payload.sub, payload.userRoles 등 활용
}

🛠️ 주요 기능 및 역할

LogtoModule

외부 로거 모듈/토큰을 받아, 인증/권한 관련 서비스와 가드를 번들로 제공
DynamicModule 패턴으로 다양한 환경에 유연하게 적용 가능

OAuthClient

OAuth 로그인/로그아웃 URI 생성
인증 코드로 토큰 발급
토큰 해지(로그아웃)

LogtoM2MClient

M2M 인증(서버 간 토큰 발급)
사용자/역할 생성, 조회, 수정, 삭제, 할당 등 관리
인증코드 발송/검증, 비밀번호 변경 등 부가 기능

LogtoLoginSession

세션 기반 로그인 플로우(단계별 API 호출)
비밀번호 검증, 사용자 식별, 동의 처리 등

LogtoTokenVerifier

JWT 토큰 검증 및 권한 체크
인증 가드(LogtoTokenGuard)에서 활용

stateless

미들웨어/핸들러 기반의 Stateless 인증/인가 유틸리티 및 가드 제공
Express/Fastify 등에서 직접 활용 가능한 인증 미들웨어, 데코레이터, 커스텀 가드 등 포함

📝 환경설정 예시 (`LogtoConfig`)

const config: LogtoConfig = {
  endpoint: 'https://auth.example.com/oidc',
  appId: 'my-client-id',
  appSecret: 'my-client-secret',
  grantType: GrantType.AuthorizationCode,
  scopes: ['openid', 'profile', 'email'],
  resources: ['https://api.example.com'],
  prompt: Prompt.Login,
  redirectUri: 'https://myapp.com/callback',
};

🗂️ 환경변수 목록 및 설명

환경변수명	설명	예시 값
LOGTO_AUTH_ENDPOINT	Logto 인증 서버 OIDC 엔드포인트	https://auth.example.com/oidc
LOGTO_CLIENT_ID	OAuth 클라이언트 ID	my-client-id
LOGTO_CLIENT_SECRET	OAuth 클라이언트 시크릿	my-client-secret
LOGTO_RESOURCES	접근할 리소스 서버(여러 개일 경우 쉼표로 구분)	https://api.example.com
LOGTO_SCOPES	요청할 OAuth 스코프(쉼표로 구분)	openid,profile,email
LOGTO_PROMPT	OAuth prompt 파라미터	login
LOGTO_REDIRECT_URI	인증 후 리다이렉트될 URI	https://myapp.com/callback
LOGTO_SIGN_IN_URI	기본 로그인 URI	https://auth.example.com
LOGTO_DASHBOARD_SIGN_IN_URI	대시보드 로그인 URI(선택)	https://dashboard.example.com
LOGTO_M2M_CLIENT_ID	M2M 인증용 클라이언트 ID	my-m2m-client-id
LOGTO_M2M_CLIENT_SECRET	M2M 인증용 클라이언트 시크릿	my-m2m-client-secret
LOGTO_M2M_RESOURCE	M2M 인증용 리소스	https://api.example.com
LOGTO_M2M_API_URL	M2M API 서버의 base URL	https://api.example.com/api
LOGTO_JWKS_URI	JWT 검증용 JWKS 엔드포인트	https://auth.example.com/oidc/jwks
LOGTO_AUTH_ISSUER	JWT 발급자(iss)	https://auth.example.com/oidc

⚠️ 실제로 필요한 환경변수는 사용하는 서비스(OAuth, M2M, 세션 등)에 따라 다를 수 있습니다. 위 표를 참고하여 .env 파일 또는 환경설정에 추가하세요.

🧩 확장/커스터마이징

외부 로깅 시스템과의 연동이 필요할 경우, 원하는 로거 모듈/토큰을 DI로 주입
각 서비스별로 NestJS의 DI/Provider 패턴을 그대로 활용 가능
필요시 각 서비스/가드를 직접 DI 받아 커스텀 비즈니스 로직 구현 가능

❓ FAQ

Q. 로거 토큰이 다르면 어떻게 하나요?
→ forLogger의 두 번째 인자로 원하는 토큰(Symbol)을 넘기면 됩니다.
Q. 환경변수 기반 설정은 어떻게 하나요?
→ 각 서비스는 DI로 ConfigService를 받아 환경변수 기반으로 설정을 자동 주입받습니다.
Q. 인증/권한 외에 사용자/역할 관리도 가능한가요?
→ 네, LogtoM2MClient를 통해 사용자/역할 생성, 조회, 수정, 삭제, 할당 등 모든 관리가 가능합니다.

🏷️ 내보내는 토큰/서비스

OAuthClientToken, LogtoM2MClientToken, LogtoTokenVerifierToken, LogtoLoginSessionToken, LogtoTokenGuard
각 서비스/가드는 NestJS DI로 바로 주입받아 사용 가능

📚 참고

📝 라이선스

MIT

FAQs

What is @point3/logto-module?

Is @point3/logto-module popular?

Is @point3/logto-module well maintained?

Package last updated on 11 Jun 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@point3/logto-module