인증 - 🌲 Sonamu

Sonamu는 better-auth를 기반으로 하는 인증 시스템을 제공합니다. 이메일/비밀번호 인증, 소셜 로그인 등 다양한 인증 방식을 지원하며, /api/auth/* 경로로 인증 API가 자동 등록됩니다.

기본 구조

import { defineConfig } from "sonamu";

export default defineConfig({
  server: {
    // 기본 설정으로 인증 활성화
    auth: {
      emailAndPassword: {
        enabled: true,
      },
    },

    // 또는 상세 설정
    auth: {
      basePath: "/api/auth",
      emailAndPassword: {
        enabled: true,
      },
      socialProviders: {
        google: {
          clientId: process.env.GOOGLE_CLIENT_ID!,
          clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
        },
      },
    },
  },
  // ...
});

auth 설정

타입

타입: BetterAuthOptions (better-auth 라이브러리의 설정 타입)

export default defineConfig({
  server: {
    auth: {
      // better-auth 설정 옵션
    },
  },
});

이메일/비밀번호 인증

export default defineConfig({
  server: {
    auth: {
      emailAndPassword: {
        enabled: true,
        // 선택: 비밀번호 최소 길이
        minPasswordLength: 8,
      },
    },
  },
});

소셜 로그인 (Google)

export default defineConfig({
  server: {
    auth: {
      emailAndPassword: {
        enabled: true,
      },
      socialProviders: {
        google: {
          clientId: process.env.GOOGLE_CLIENT_ID!,
          clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
        },
      },
    },
  },
});

소셜 로그인 (GitHub)

export default defineConfig({
  server: {
    auth: {
      socialProviders: {
        github: {
          clientId: process.env.GITHUB_CLIENT_ID!,
          clientSecret: process.env.GITHUB_CLIENT_SECRET!,
        },
      },
    },
  },
});

basePath 커스터마이징

기본 경로는 /api/auth입니다. 변경이 필요한 경우:

export default defineConfig({
  server: {
    auth: {
      basePath: "/auth",  // /auth/* 로 변경
      emailAndPassword: {
        enabled: true,
      },
    },
  },
});

엔티티 생성

better-auth를 사용하려면 먼저 필요한 엔티티들을 생성해야 합니다.

CLI로 엔티티 생성

pnpm sonamu better-auth

이 명령은 다음 엔티티들을 생성합니다:

엔티티	테이블	설명
User	users	사용자 정보
Session	sessions	세션 정보
Account	accounts	OAuth 계정 연동 정보
Verification	verifications	이메일 인증 등

이미 User 엔티티가 있는 경우, 명령 실행 시 누락된 필드만 추가됩니다.

플러그인과 함께 엔티티 생성

better-auth 플러그인을 사용하려면 --plugins 옵션으로 필요한 플러그인들을 지정합니다:

# 단일 플러그인
pnpm sonamu better-auth --plugins=2fa

# 여러 플러그인 (쉼표로 구분)
pnpm sonamu better-auth --plugins=2fa,admin,username

지원하는 플러그인:

플러그인 ID	설명	추가되는 필드/테이블
`2fa`	2단계 인증 (TOTP)	TwoFactor 테이블, User.two_factor_enabled
`admin`	관리자 기능	User.role, User.banned, User.ban_reason, User.ban_expires, Session.impersonated_by
`username`	사용자명 로그인	User.username (unique), User.display_username
`phone-number`	전화번호 인증	User.phone_number (unique), User.phone_number_verified
`passkey`	WebAuthn 패스키 인증	Passkey 테이블
`sso`	SSO 로그인 (OIDC/SAML)	SsoProvider 테이블
`api-key`	API 키 인증	ApiKey 테이블
`jwt`	JWT 토큰 발급	Jwks 테이블
`organization`	조직/팀 관리	Organization, Member, Invitation, Team, TeamMember 테이블, Session.active_organization_id, Session.active_team_id
`anonymous`	익명 사용자	User.is_anonymous

플러그인 사용 시 sonamu.config.ts에서도 해당 플러그인을 활성화해야 합니다. 자세한 내용은 아래 플러그인 설정 섹션을 참조하세요.

필드 매핑

Sonamu는 snake_case 컬럼명을 사용하므로, better-auth의 camelCase 필드명이 자동으로 매핑됩니다:

// better-auth → Sonamu
emailVerified → email_verified
createdAt → created_at
updatedAt → updated_at
ipAddress → ip_address
userAgent → user_agent
userId → user_id
// ...

인증 API

better-auth가 등록되면 다음 API들이 자동으로 사용 가능합니다:

회원가입

POST /api/auth/sign-up/email
Content-Type: application/json

{
  "name": "홍길동",
  "email": "user@example.com",
  "password": "password123"
}

로그아웃

POST /api/auth/sign-out

현재 세션

GET /api/auth/get-session

소셜 로그인 (Google)

GET /api/auth/sign-in/social?provider=google

전체 API 목록은 better-auth 문서를 참조하세요.

Context에서 사용자 정보 접근

인증된 요청에서는 Context를 통해 사용자 정보에 접근할 수 있습니다.

import { api, getContext } from "sonamu";

export class MyModel {
  @api()
  static async myApi() {
    const ctx = getContext();

    // 현재 로그인한 사용자
    const user = ctx.user;  // User | null

    // 현재 세션 정보
    const session = ctx.session;  // Session | null

    if (!user) {
      throw new UnauthorizedError("로그인이 필요합니다");
    }

    return { userId: user.id, userName: user.name };
  }
}

User 타입

type User = {
  id: string;
  name: string;
  email: string;
  emailVerified: boolean;
  image: string | null;
  createdAt: Date;
  updatedAt: Date;
};

Session 타입

type Session = {
  id: string;
  expiresAt: Date;
  token: string;
  createdAt: Date;
  updatedAt: Date;
  ipAddress: string | null;
  userAgent: string | null;
  userId: string;
};

Guard를 이용한 접근 제어

import { api } from "sonamu";

export class AdminModel {
  @api({ guards: ["admin"] })
  static async adminOnly() {
    // admin guard가 통과한 경우에만 실행
    return { message: "관리자 전용 API" };
  }
}

guardHandler 설정:

export default defineConfig({
  server: {
    auth: {
      emailAndPassword: { enabled: true },
    },

    apiConfig: {
      guardHandler: async (guard, request) => {
        // Context에서 user 가져오기
        const { user } = getContext();

        if (guard === "auth" && !user) {
          throw new UnauthorizedError("로그인이 필요합니다");
        }

        if (guard === "admin") {
          if (!user) {
            throw new UnauthorizedError("로그인이 필요합니다");
          }
          // User 엔티티에 role 필드가 있다고 가정
          const fullUser = await UserModel.findById("A", user.id);
          if (fullUser.role !== "admin") {
            throw new UnauthorizedError("관리자 권한이 필요합니다");
          }
        }
      },
    },
  },
});

클라이언트 측 연동

React에서 사용

// lib/auth-client.ts
import { createAuthClient } from "better-auth/react";

export const authClient = createAuthClient({
  baseURL: "http://localhost:4000",
});

// components/LoginForm.tsx
import { authClient } from "../lib/auth-client";

export function LoginForm() {
  const handleLogin = async (email: string, password: string) => {
    const result = await authClient.signIn.email({
      email,
      password,
    });

    if (result.error) {
      alert(result.error.message);
      return;
    }

    // 로그인 성공
    window.location.href = "/dashboard";
  };

  // ...
}

// components/GoogleLoginButton.tsx
import { authClient } from "../lib/auth-client";

export function GoogleLoginButton() {
  const handleGoogleLogin = () => {
    authClient.signIn.social({
      provider: "google",
      callbackURL: "/dashboard",
    });
  };

  return (
    <button onClick={handleGoogleLogin}>
      Google로 로그인
    </button>
  );
}

플러그인 설정

better-auth 플러그인을 사용하려면 sonamu.config.ts의 auth.plugins 배열에 플러그인을 추가합니다.

플러그인을 설정하기 전에 먼저 pnpm sonamu better-auth --plugins=... 명령으로 필요한 엔티티와 필드를 생성해야 합니다.

2단계 인증 (2FA)

TOTP 기반 2단계 인증을 활성화합니다:

import { defineConfig } from "sonamu";
import { twoFactor, TWO_FACTOR_SCHEMA } from "sonamu/auth";

export default defineConfig({
  server: {
    auth: {
      emailAndPassword: { enabled: true },
      plugins: [
        twoFactor({
          issuer: "My App",  // OTP 앱에 표시될 이름
          schema: TWO_FACTOR_SCHEMA,
        }),
      ],
    },
  },
});

2FA 관련 API:

POST /api/auth/two-factor/enable - 2FA 활성화 시작
POST /api/auth/two-factor/verify - 2FA 코드 검증
POST /api/auth/two-factor/disable - 2FA 비활성화

관리자 플러그인 (Admin)

사용자 역할, 차단 기능, 대리 로그인(impersonation)을 지원합니다:

import { defineConfig } from "sonamu";
import { admin, ADMIN_SCHEMA } from "sonamu/auth";

export default defineConfig({
  server: {
    auth: {
      emailAndPassword: { enabled: true },
      plugins: [
        admin({
          schema: ADMIN_SCHEMA,
        }),
      ],
    },
  },
});

Admin 플러그인이 User 테이블에 추가하는 필드:

role - 사용자 역할 (기본값: “user”)
banned - 차단 여부
ban_reason - 차단 사유
ban_expires - 차단 만료 시간 (Unix timestamp)

사용자명 플러그인 (Username)

이메일 대신 사용자명으로 로그인할 수 있습니다:

import { defineConfig } from "sonamu";
import { username, USERNAME_SCHEMA } from "sonamu/auth";

export default defineConfig({
  server: {
    auth: {
      plugins: [
        username({
          schema: USERNAME_SCHEMA,
        }),
      ],
    },
  },
});

Username 플러그인이 User 테이블에 추가하는 필드:

username - 정규화된 사용자명 (소문자, unique 인덱스)
display_username - 표시용 사용자명 (원본 케이스 유지)

전화번호 플러그인 (Phone Number)

전화번호 인증을 지원합니다:

import { defineConfig } from "sonamu";
import { phoneNumber, PHONE_NUMBER_SCHEMA } from "sonamu/auth";

export default defineConfig({
  server: {
    auth: {
      plugins: [
        phoneNumber({
          schema: PHONE_NUMBER_SCHEMA,
        }),
      ],
    },
  },
});

Phone Number 플러그인이 User 테이블에 추가하는 필드:

phone_number - 전화번호 (unique 인덱스)
phone_number_verified - 전화번호 인증 여부

패스키 플러그인 (Passkey)

WebAuthn/FIDO2 기반 패스키 인증을 지원합니다:

import { defineConfig } from "sonamu";
import { passkey, PASSKEY_SCHEMA } from "sonamu/auth";

export default defineConfig({
  server: {
    auth: {
      emailAndPassword: { enabled: true },
      plugins: [
        passkey({
          schema: PASSKEY_SCHEMA,
        }),
      ],
    },
  },
});

Passkey 플러그인이 생성하는 테이블:

passkeys - 사용자의 패스키 정보 (공개키, 자격 증명 ID 등)

Passkey 관련 API:

POST /api/auth/passkey/generate-register-options - 패스키 등록 옵션 생성
POST /api/auth/passkey/verify-registration - 패스키 등록 검증
POST /api/auth/passkey/generate-authentication-options - 패스키 인증 옵션 생성
POST /api/auth/passkey/verify-authentication - 패스키 인증 검증

Passkey 플러그인 사용 시 @better-auth/passkey 패키지가 필요합니다.

SSO 플러그인

외부 IdP(OIDC, SAML)를 통한 SSO 로그인을 지원합니다:

import { defineConfig } from "sonamu";
import { sso, SSO_SCHEMA } from "sonamu/auth";

export default defineConfig({
  server: {
    auth: {
      plugins: [
        sso({
          ...SSO_SCHEMA,
        }),
      ],
    },
  },
});

SSO 플러그인이 생성하는 테이블:

sso_providers - SSO 제공자 설정 (OIDC/SAML 설정 포함)

SSO 플러그인 사용 시 @better-auth/sso 패키지가 필요합니다.

API 키 플러그인 (API Key)

API 키 기반 인증을 지원합니다:

import { defineConfig } from "sonamu";
import { apiKey, API_KEY_SCHEMA } from "sonamu/auth";

export default defineConfig({
  server: {
    auth: {
      plugins: [
        apiKey({
          schema: API_KEY_SCHEMA,
        }),
      ],
    },
  },
});

API Key 플러그인이 생성하는 테이블:

api_keys - API 키 정보 (해시된 키, Rate Limit 설정 등)

API Key 관련 API:

POST /api/auth/api-key/create - API 키 생성
POST /api/auth/api-key/revoke - API 키 폐기
GET /api/auth/api-key/list - API 키 목록 조회

JWT 플러그인

JWT 토큰 발급 및 JWKS 키 관리를 지원합니다:

import { defineConfig } from "sonamu";
import { jwt, JWT_SCHEMA } from "sonamu/auth";

export default defineConfig({
  server: {
    auth: {
      plugins: [
        jwt({
          schema: JWT_SCHEMA,
        }),
      ],
    },
  },
});

JWT 플러그인이 생성하는 테이블:

jwks - JSON Web Key Set 정보 (공개키, 비밀키)

JWT 관련 API:

GET /api/auth/.well-known/jwks.json - JWKS 엔드포인트
POST /api/auth/jwt/generate - JWT 토큰 생성

조직 플러그인 (Organization)

조직, 멤버, 초대, 팀 관리를 지원합니다:

import { defineConfig } from "sonamu";
import { organization, ORGANIZATION_SCHEMA } from "sonamu/auth";

export default defineConfig({
  server: {
    auth: {
      plugins: [
        organization({
          schema: ORGANIZATION_SCHEMA,
        }),
      ],
    },
  },
});

Organization 플러그인이 생성하는 테이블:

organizations - 조직 정보
members - 조직 멤버
invitations - 조직 초대
teams - 팀
team_members - 팀 멤버

Organization 플러그인이 Session 테이블에 추가하는 필드:

active_organization_id - 현재 활성 조직 ID
active_team_id - 현재 활성 팀 ID

Organization 관련 API:

POST /api/auth/organization/create - 조직 생성
POST /api/auth/organization/invite - 멤버 초대
POST /api/auth/organization/accept-invitation - 초대 수락
POST /api/auth/organization/set-active - 활성 조직 설정

익명 사용자 플러그인 (Anonymous)

익명 사용자 인증을 지원합니다. 회원가입 없이 임시 사용자를 생성할 수 있습니다:

import { defineConfig } from "sonamu";
import { anonymous, ANONYMOUS_SCHEMA } from "sonamu/auth";

export default defineConfig({
  server: {
    auth: {
      plugins: [
        anonymous({
          schema: ANONYMOUS_SCHEMA,
        }),
      ],
    },
  },
});

Anonymous 플러그인이 User 테이블에 추가하는 필드:

is_anonymous - 익명 사용자 여부

Anonymous 관련 API:

POST /api/auth/sign-in/anonymous - 익명 로그인
POST /api/auth/anonymous/link - 익명 계정을 정식 계정으로 연결

여러 플러그인 함께 사용

import { defineConfig } from "sonamu";
import {
  admin,
  ADMIN_SCHEMA,
  twoFactor,
  TWO_FACTOR_SCHEMA,
  username,
  USERNAME_SCHEMA,
  passkey,
  PASSKEY_SCHEMA,
  organization,
  ORGANIZATION_SCHEMA,
} from "sonamu/auth";

export default defineConfig({
  server: {
    auth: {
      emailAndPassword: { enabled: true },
      plugins: [
        admin({ schema: ADMIN_SCHEMA }),
        twoFactor({
          issuer: "My App",
          schema: TWO_FACTOR_SCHEMA,
        }),
        username({ schema: USERNAME_SCHEMA }),
        passkey({ schema: PASSKEY_SCHEMA }),
        organization({ schema: ORGANIZATION_SCHEMA }),
      ],
    },
  },
});

각 플러그인의 스키마(*_SCHEMA)는 Sonamu의 snake_case 컬럼명과 better-auth의 camelCase 필드명을 매핑하는 역할을 합니다. 반드시 해당 플러그인과 함께 전달해야 합니다.

실전 예시

기본 설정

import { defineConfig } from "sonamu";

export default defineConfig({
  server: {
    auth: {
      emailAndPassword: {
        enabled: true,
      },
    },

    apiConfig: {
      guardHandler: async (guard) => {
        const { user } = getContext();

        if (guard === "auth" && !user) {
          throw new UnauthorizedError("로그인이 필요합니다");
        }
      },
    },
  },
});

소셜 로그인 + 이메일 인증

import { defineConfig } from "sonamu";

export default defineConfig({
  server: {
    auth: {
      emailAndPassword: {
        enabled: true,
        requireEmailVerification: true,
      },
      socialProviders: {
        google: {
          clientId: process.env.GOOGLE_CLIENT_ID!,
          clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
        },
        github: {
          clientId: process.env.GITHUB_CLIENT_ID!,
          clientSecret: process.env.GITHUB_CLIENT_SECRET!,
        },
      },
    },
  },
});

주의사항

1. 엔티티 생성 필수

# auth 설정 전에 먼저 엔티티 생성
pnpm sonamu better-auth

# 마이그레이션 실행
pnpm sonamu migrate run

2. 환경 변수 설정

# .env
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

3. CORS 설정

클라이언트가 다른 도메인에서 실행되는 경우:

export default defineConfig({
  server: {
    plugins: {
      cors: {
        origin: ["http://localhost:3000"],
        credentials: true,
      },
    },

    auth: {
      emailAndPassword: { enabled: true },
    },
  },
});

4. 기존 User 엔티티와의 호환성

이미 User 엔티티가 있는 경우, pnpm sonamu better-auth 실행 시 누락된 필드만 추가됩니다. 기존 데이터는 유지됩니다.

다음 단계

인증 설정을 완료했다면:

Context - Context에서 사용자 정보 접근
Guards - API 접근 제어

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​기본 구조

​auth 설정

​타입

​이메일/비밀번호 인증

​소셜 로그인 (Google)

​소셜 로그인 (GitHub)

​basePath 커스터마이징

​엔티티 생성

​CLI로 엔티티 생성

​플러그인과 함께 엔티티 생성

​필드 매핑

​인증 API

​회원가입

​로그인

​로그아웃

​현재 세션

​소셜 로그인 (Google)

​Context에서 사용자 정보 접근

​User 타입

​Session 타입

​Guard를 이용한 접근 제어

​클라이언트 측 연동

​React에서 사용

​플러그인 설정

​2단계 인증 (2FA)

​관리자 플러그인 (Admin)

​사용자명 플러그인 (Username)

​전화번호 플러그인 (Phone Number)

​패스키 플러그인 (Passkey)

​SSO 플러그인

​API 키 플러그인 (API Key)

​JWT 플러그인

​조직 플러그인 (Organization)

​익명 사용자 플러그인 (Anonymous)

​여러 플러그인 함께 사용

​실전 예시

​기본 설정

​소셜 로그인 + 이메일 인증

​주의사항

​1. 엔티티 생성 필수

​2. 환경 변수 설정

​3. CORS 설정

​4. 기존 User 엔티티와의 호환성

​다음 단계

기본 구조

auth 설정

타입

이메일/비밀번호 인증

소셜 로그인 (Google)

소셜 로그인 (GitHub)

basePath 커스터마이징

엔티티 생성

CLI로 엔티티 생성

플러그인과 함께 엔티티 생성

필드 매핑

인증 API

회원가입

로그인

로그아웃

현재 세션

소셜 로그인 (Google)

Context에서 사용자 정보 접근

User 타입

Session 타입

Guard를 이용한 접근 제어

클라이언트 측 연동

React에서 사용

플러그인 설정

2단계 인증 (2FA)

관리자 플러그인 (Admin)

사용자명 플러그인 (Username)

전화번호 플러그인 (Phone Number)

패스키 플러그인 (Passkey)

SSO 플러그인

API 키 플러그인 (API Key)

JWT 플러그인

조직 플러그인 (Organization)

익명 사용자 플러그인 (Anonymous)

여러 플러그인 함께 사용

실전 예시

기본 설정

소셜 로그인 + 이메일 인증

주의사항

1. 엔티티 생성 필수

2. 환경 변수 설정

3. CORS 설정

4. 기존 User 엔티티와의 호환성

다음 단계