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_SECRETprocess.env.AUTH_SECRET
이러한 환경 변수가 설정되지 않으면, "better-auth-secret-123456789"로 기본 설정됩니다. 프로덕션 환경에서 설정되지 않으면 오류를 발생시킵니다.
다음 명령을 사용하여 안전한 시크릿을 생성할 수 있습니다:
openssl rand -base64 32database
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,
}
})