Options

Better Auth를 구성하기 위한 사용 가능한 모든 옵션 목록입니다. Better Auth Options를 참조하세요.

appName

애플리케이션의 이름입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	appName: "My App",
})

baseURL

Better Auth의 기본 URL입니다. 일반적으로 애플리케이션 서버가 호스팅되는 루트 URL입니다. 참고: baseURL에 경로를 포함하면 기본 경로보다 우선합니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	baseURL: "https://example.com",
})

명시적으로 설정하지 않으면, 시스템은 환경 변수 process.env.BETTER_AUTH_URL을 확인합니다.

basePath

Better Auth의 기본 경로입니다. 일반적으로 Better Auth 라우트가 마운트되는 경로입니다. baseURL 내에 경로 컴포넌트가 있으면 이 값이 재정의됩니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	basePath: "/api/auth",
})

기본값: /api/auth

trustedOrigins

신뢰할 수 있는 origin 목록입니다. 정적 origin 배열, 동적으로 origin을 반환하는 함수를 제공하거나, 와일드카드 패턴을 사용하여 여러 도메인을 매칭할 수 있습니다.

정적 Origins

정적 origin 배열을 제공할 수 있습니다:

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	trustedOrigins: ["http://localhost:3000", "https://example.com"],
})

동적 Origins

동적으로 origin을 반환하는 함수를 제공할 수 있습니다:

export const auth = betterAuth({
	trustedOrigins: async (request: Request) => {
		// 요청을 기반으로 신뢰할 수 있는 origin의 배열을 반환합니다
		return ["https://dynamic-origin.com"];
	}
})

와일드카드 지원

신뢰할 수 있는 origin에서 와일드카드 패턴을 사용할 수 있습니다:

export const auth = betterAuth({
	trustedOrigins: [
		"*.example.com",             // example.com의 모든 서브도메인 신뢰
		"https://*.example.com",     // HTTPS 서브도메인만 신뢰
		"http://*.dev.example.com"   // dev.example.com의 HTTP 서브도메인 신뢰
	]
})

secret

암호화, 서명 및 해싱에 사용되는 시크릿입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	secret: "your-secret-key",
})

기본적으로 Better Auth는 다음 환경 변수를 찾습니다:

  • process.env.BETTER_AUTH_SECRET
  • process.env.AUTH_SECRET

이러한 환경 변수가 설정되지 않으면, "better-auth-secret-123456789"로 기본 설정됩니다. 프로덕션 환경에서 설정되지 않으면 오류를 발생시킵니다.

다음 명령을 사용하여 안전한 시크릿을 생성할 수 있습니다:

openssl rand -base64 32

database

Better Auth의 데이터베이스 구성입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	database: {
		dialect: "postgres",
		type: "postgres",
		casing: "camel"
	},
})

Better Auth는 PostgreSQL, MySQL, SQLite를 포함한 다양한 데이터베이스 구성을 지원합니다.

데이터베이스에 대한 자세한 내용은 여기를 참조하세요.

secondaryStorage

세션 및 rate limit 데이터를 저장하는 데 사용되는 보조 스토리지 구성입니다.

import { betterAuth } from "better-auth";

export const auth = betterAuth({
	// ... 기타 옵션
    secondaryStorage: {
    	// 여기에 구현을 작성하세요
    },
})

보조 스토리지에 대한 자세한 내용은 여기를 참조하세요.

emailVerification

이메일 인증 구성입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	emailVerification: {
		sendVerificationEmail: async ({ user, url, token }) => {
			// 사용자에게 인증 이메일 전송
		},
		sendOnSignUp: true,
		autoSignInAfterVerification: true,
		expiresIn: 3600 // 1시간
	},
})
  • sendVerificationEmail: 인증 이메일을 전송하는 함수
  • sendOnSignUp: 회원가입 후 자동으로 인증 이메일 전송 (기본값: false)
  • sendOnSignIn: 사용자의 이메일이 인증되지 않은 경우 로그인 시 자동으로 인증 이메일 전송 (기본값: false)
  • autoSignInAfterVerification: 이메일 인증 후 자동으로 사용자 로그인
  • expiresIn: 인증 토큰이 유효한 시간(초) (기본값: 3600초)

emailAndPassword

이메일 및 비밀번호 인증 구성입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	emailAndPassword: {
		enabled: true,
		disableSignUp: false,
		requireEmailVerification: true,
		minPasswordLength: 8,
		maxPasswordLength: 128,
		autoSignIn: true,
		sendResetPassword: async ({ user, url, token }) => {
			// 비밀번호 재설정 이메일 전송
		},
		resetPasswordTokenExpiresIn: 3600, // 1시간
		password: {
			hash: async (password) => {
				// 커스텀 비밀번호 해싱
				return hashedPassword;
			},
			verify: async ({ hash, password }) => {
				// 커스텀 비밀번호 검증
				return isValid;
			}
		}
	},
})
  • enabled: 이메일 및 비밀번호 인증 활성화 (기본값: false)
  • disableSignUp: 이메일 및 비밀번호 회원가입 비활성화 (기본값: false)
  • requireEmailVerification: 세션 생성 전 이메일 인증 필수
  • minPasswordLength: 최소 비밀번호 길이 (기본값: 8)
  • maxPasswordLength: 최대 비밀번호 길이 (기본값: 128)
  • autoSignIn: 회원가입 후 자동으로 사용자 로그인
  • sendResetPassword: 비밀번호 재설정 이메일을 전송하는 함수
  • resetPasswordTokenExpiresIn: 비밀번호 재설정 토큰이 유효한 시간(초) (기본값: 3600초)
  • password: 커스텀 비밀번호 해싱 및 검증 함수

socialProviders

소셜 로그인 provider를 구성합니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	socialProviders: {
		google: {
			clientId: "your-client-id",
			clientSecret: "your-client-secret",
			redirectURI: "https://example.com/api/auth/callback/google"
		},
		github: {
			clientId: "your-client-id",
			clientSecret: "your-client-secret",
			redirectURI: "https://example.com/api/auth/callback/github"
		}
	},
})

plugins

Better Auth 플러그인 목록입니다.

import { betterAuth } from "better-auth";
import { emailOTP } from "better-auth/plugins";

export const auth = betterAuth({
	plugins: [
		emailOTP({
			sendVerificationOTP: async ({ email, otp, type }) => {
				// 사용자의 이메일로 OTP 전송
			}
		})
	],
})

user

사용자 구성 옵션입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	user: {
		modelName: "users",
		fields: {
			email: "emailAddress",
			name: "fullName"
		},
		additionalFields: {
			customField: {
				type: "string",
			}
		},
		changeEmail: {
			enabled: true,
			sendChangeEmailVerification: async ({ user, newEmail, url, token }) => {
				// 이메일 변경 인증 전송
			}
		},
		deleteUser: {
			enabled: true,
			sendDeleteAccountVerification: async ({ user, url, token }) => {
				// 계정 삭제 인증 전송
			},
			beforeDelete: async (user) => {
				// 사용자 삭제 전 작업 수행
			},
			afterDelete: async (user) => {
				// 사용자 삭제 후 정리 작업 수행
			}
		}
	},
})
  • modelName: 사용자의 모델 이름 (기본값: "user")
  • fields: 필드를 다른 컬럼 이름으로 매핑
  • additionalFields: 사용자 테이블의 추가 필드
  • changeEmail: 이메일 변경 구성
  • deleteUser: 사용자 삭제 구성

session

세션 구성 옵션입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	session: {
		modelName: "sessions",
		fields: {
			userId: "user_id"
		},
		expiresIn: 604800, // 7일
		updateAge: 86400, // 1일
		disableSessionRefresh: true, // `updateAge` 옵션에 관계없이 세션이 업데이트되지 않도록 세션 갱신을 비활성화합니다. (기본값: `false`)
		additionalFields: { // 세션 테이블의 추가 필드
			customField: {
				type: "string",
			}
		},
		storeSessionInDatabase: true, // 보조 스토리지가 제공될 때 데이터베이스에 세션 저장 (기본값: `false`)
		preserveSessionInDatabase: false, // 보조 스토리지에서 삭제될 때 데이터베이스에 세션 레코드 보존 (기본값: `false`)
		cookieCache: {
			enabled: true, // 쿠키에 세션 캐싱 활성화 (기본값: `false`)
			maxAge: 300 // 5분
		}
	},
})
  • modelName: 세션의 모델 이름 (기본값: "session")
  • fields: 필드를 다른 컬럼 이름으로 매핑
  • expiresIn: 세션 토큰 만료 시간(초) (기본값: 604800 - 7일)
  • updateAge: 세션을 갱신해야 하는 빈도(초) (기본값: 86400 - 1일)
  • additionalFields: 세션 테이블의 추가 필드
  • storeSessionInDatabase: 보조 스토리지가 제공될 때 데이터베이스에 세션 저장 (기본값: false)
  • preserveSessionInDatabase: 보조 스토리지에서 삭제될 때 데이터베이스에 세션 레코드 보존 (기본값: false)
  • cookieCache: 쿠키에 세션 캐싱 활성화

account

계정 구성 옵션입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	account: {
		modelName: "accounts",
		fields: {
			userId: "user_id"
		},
		encryptOAuthTokens: true, // 데이터베이스에 저장하기 전에 OAuth 토큰 암호화
		accountLinking: {
			enabled: true,
			trustedProviders: ["google", "github", "email-password"],
			allowDifferentEmails: false
		}
	},
})
  • modelName: 계정의 모델 이름
  • fields: 필드를 다른 컬럼 이름으로 매핑

encryptOAuthTokens

데이터베이스에 저장하기 전에 OAuth 토큰을 암호화합니다. 기본값: false.

updateAccountOnSignIn

활성화된 경우(true), 사용자 계정 데이터(accessToken, idToken, refreshToken 등)가 로그인 시 provider의 최신 데이터로 업데이트됩니다.

accountLinking

계정 연결 구성입니다.

  • enabled: 계정 연결 활성화 (기본값: false)
  • trustedProviders: 신뢰할 수 있는 provider 목록
  • allowDifferentEmails: 사용자가 다른 이메일 주소를 가진 계정을 연결할 수 있도록 허용
  • allowUnlinkingAll: 사용자가 모든 계정 연결을 해제할 수 있도록 허용

verification

인증 구성 옵션입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	verification: {
		modelName: "verifications",
		fields: {
			userId: "user_id"
		},
		disableCleanup: false
	},
})
  • modelName: 인증 테이블의 모델 이름
  • fields: 필드를 다른 컬럼 이름으로 매핑
  • disableCleanup: 인증 값을 가져올 때 만료된 값 정리 비활성화

rateLimit

Rate limiting 구성입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	rateLimit: {
		enabled: true,
		window: 10,
		max: 100,
		customRules: {
			"/example/path": {
				window: 10,
				max: 100
			}
		},
		storage: "memory",
		modelName: "rateLimit"
	}
})
  • enabled: Rate limiting 활성화 (기본값: 프로덕션에서 true, 개발 환경에서 false)
  • window: Rate limiting에 사용할 시간 윈도우. 값은 초 단위여야 합니다. (기본값: 10)
  • max: 윈도우 내에서 허용되는 기본 최대 요청 수. (기본값: 100)
  • customRules: 특정 경로에 적용할 커스텀 rate limit 규칙.
  • storage: 스토리지 구성. 보조 스토리지를 전달한 경우, rate limiting은 보조 스토리지에 저장됩니다. (옵션: "memory", "database", "secondary-storage", 기본값: "memory")
  • modelName: 데이터베이스를 스토리지로 사용하는 경우 rate limiting에 사용할 테이블 이름. (기본값: "rateLimit")

advanced

고급 구성 옵션입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	advanced: {
		ipAddress: {
			ipAddressHeaders: ["x-client-ip", "x-forwarded-for"],
			disableIpTracking: false
		},
		useSecureCookies: true,
		disableCSRFCheck: false,
		crossSubDomainCookies: {
			enabled: true,
			additionalCookies: ["custom_cookie"],
			domain: "example.com"
		},
		cookies: {
			session_token: {
				name: "custom_session_token",
				attributes: {
					httpOnly: true,
					secure: true
				}
			}
		},
		defaultCookieAttributes: {
			httpOnly: true,
			secure: true
		},
		cookiePrefix: "myapp",
		database: {
			// DB가 자동 증가 ID를 사용하는 경우, 이 값을 true로 설정하세요.
			useNumberId: false,
			// 자신만의 커스텀 ID 생성기를 사용하거나, ID 생성을 완전히 비활성화하세요.
			generateId: (((options: {
				model: LiteralUnion<Models, string>;
				size?: number;
			}) => {
				return "my-super-unique-id";
			})) | false,
			defaultFindManyLimit: 100,
		}
	},
})
  • ipAddress: Rate limiting 및 세션 추적을 위한 IP 주소 구성
  • useSecureCookies: 보안 쿠키 사용 (기본값: false)
  • disableCSRFCheck: 신뢰할 수 있는 origin 확인 비활성화 (⚠️ 보안 위험)
  • crossSubDomainCookies: 서브도메인 간 쿠키 공유 구성
  • cookies: 쿠키 이름 및 속성 커스터마이징
  • defaultCookieAttributes: 모든 쿠키의 기본 속성
  • cookiePrefix: 쿠키의 접두사
  • generateId: 모델의 고유 ID를 생성하는 함수

logger

Better Auth의 로거 구성입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	logger: {
		disabled: false,
		disableColors: false,
		level: "error",
		log: (level, message, ...args) => {
			// 커스텀 로깅 구현
			console.log(`[${level}] ${message}`, ...args);
		}
	}
})

로거 구성을 통해 Better Auth가 로깅을 처리하는 방식을 커스터마이징할 수 있습니다. 다음 옵션을 지원합니다:

  • disabled: true로 설정하면 모든 로깅 비활성화 (기본값: false)
  • disableColors: 기본 로거 구현에서 색상 비활성화 (기본값: 터미널의 색상 지원에 따라 결정됨)
  • level: 표시할 최소 로그 레벨 설정. 사용 가능한 레벨은:
    • "info": 모든 로그 표시
    • "warn": 경고 및 오류 표시
    • "error": 오류만 표시
    • "debug": 디버그 정보를 포함한 모든 로그 표시
  • log: 다음을 수신하는 커스텀 로깅 함수:
    • level: 로그 레벨 ("info", "warn", "error", 또는 "debug")
    • message: 로그 메시지
    • ...args: 로거에 전달된 추가 인수

커스텀 로깅을 사용하는 예제:

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	logger: {
		level: "info",
		log: (level, message, ...args) => {
			// 커스텀 로깅 서비스에 로그 전송
			myLoggingService.log({
				level,
				message,
				metadata: args,
				timestamp: new Date().toISOString()
			});
		}
	}
})

databaseHooks

핵심 작업을 위한 데이터베이스 라이프사이클 hook입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	databaseHooks: {
		user: {
			create: {
				before: async (user) => {
					// 생성 전 사용자 데이터 수정
					return { data: { ...user, customField: "value" } };
				},
				after: async (user) => {
					// 사용자 생성 후 작업 수행
				}
			},
			update: {
				before: async (userData) => {
					// 업데이트 전 사용자 데이터 수정
					return { data: { ...userData, updatedAt: new Date() } };
				},
				after: async (user) => {
					// 사용자 업데이트 후 작업 수행
				}
			}
		},
		session: {
			// 세션 hook
		},
		account: {
			// 계정 hook
		},
		verification: {
			// 인증 hook
		}
	},
})

onAPIError

API 오류 처리 구성입니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	onAPIError: {
		throw: true,
		onError: (error, ctx) => {
			// 커스텀 오류 처리
			console.error("Auth error:", error);
		},
		errorURL: "/auth/error"
	},
})
  • throw: API 오류 발생 시 오류를 throw (기본값: false)
  • onError: 커스텀 오류 핸들러
  • errorURL: 오류 발생 시 리디렉션할 URL (기본값: /api/auth/error)

hooks

요청 라이프사이클 hook입니다.

import { betterAuth } from "better-auth";
import { createAuthMiddleware } from "better-auth/api";

export const auth = betterAuth({
	hooks: {
		before: createAuthMiddleware(async (ctx) => {
			// 요청 처리 전 실행
			console.log("Request path:", ctx.path);
		}),
		after: createAuthMiddleware(async (ctx) => {
			// 요청 처리 후 실행
			console.log("Response:", ctx.context.returned);
		})
	},
})

자세한 내용과 예제는 Hooks 문서를 참조하세요.

disabledPaths

특정 auth 경로를 비활성화합니다.

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	disabledPaths: ["/sign-up/email", "/sign-in/email"],
})

telemetry

Better Auth의 원격 측정 데이터 수집을 활성화 또는 비활성화합니다. (기본값: false)

import { betterAuth } from "better-auth";
export const auth = betterAuth({
  telemetry: {
    enabled: false,
  }
})