@point3/logto-module v1.0.11

point3-logto-module

NestJS 기반 Logto 인증/권한 통합 모듈
(서버/클라이언트, M2M, 사용자/역할 관리, OAuth, DI 기반 확장성 제공)

📦 개요

@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',
};

🗂️ 환경변수 목록 및 설명

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

🧩 확장/커스터마이징

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

❓ FAQ

• Q. 로거 토큰이 다르면 어떻게 하나요?
  → forLogger의 두 번째 인자로 원하는 토큰(Symbol)을 넘기면 됩니다.

• Q. 환경변수 기반 설정은 어떻게 하나요?
  → 각 서비스는 DI로 ConfigService를 받아 환경변수 기반으로 설정을 자동 주입받습니다.

• Q. 인증/권한 외에 사용자/역할 관리도 가능한가요?
  → 네, LogtoM2MClient를 통해 사용자/역할 생성, 조회, 수정, 삭제, 할당 등 모든 관리가 가능합니다.

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

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

📚 참고

• Logto 공식 문서
• NestJS 공식 문서

📝 라이선스

MIT