이메일은 Better Auth의 핵심 부분으로, 인증 방법에 관계없이 모든 사용자에게 필요합니다. Better Auth는 이메일 및 비밀번호 인증을 기본으로 제공하며, 이메일 인증, 비밀번호 재설정 등을 관리하는 데 도움이 되는 많은 유틸리티를 제공합니다.
이메일 인증
이메일 인증은 사용자가 유효한 이메일 주소를 제공하도록 보장하는 보안 기능입니다. 이메일 주소가 사용자에게 속하는지 확인하여 스팸 및 악용을 방지하는 데 도움이 됩니다. 이 가이드에서는 앱에서 토큰 기반 이메일 인증을 구현하는 방법을 안내합니다. OTP 기반 이메일 인증을 사용하려면 OTP Verification 가이드를 확인하세요.
앱에 이메일 인증 추가하기
이메일 인증을 활성화하려면 링크가 포함된 인증 이메일을 보내는 함수를 전달해야 합니다.
- sendVerificationEmail: 이 함수는 이메일 인증이 시작될 때 트리거됩니다. 다음 속성을 가진 데이터 객체를 받습니다:
user: 이메일 주소가 포함된 사용자 객체url: 사용자가 이메일을 인증하기 위해 클릭해야 하는 인증 URLtoken: 사용자 정의 인증 URL을 구현할 때 사용할 이메일 인증을 완료하는 데 사용되는 인증 토큰
그리고 두 번째 매개변수로 request 객체를 받습니다.
import { betterAuth } from 'better-auth';
import { sendEmail } from './email'; // 이메일 발송 함수
export const auth = betterAuth({
emailVerification: {
sendVerificationEmail: async ({ user, url, token }, request) => {
await sendEmail({
to: user.email,
subject: '이메일 주소를 인증하세요',
text: `다음 링크를 클릭하여 이메일을 인증하세요: ${url}`
})
}
}
})이메일 인증 트리거하기
여러 가지 방법으로 이메일 인증을 시작할 수 있습니다:
1. 가입 시
가입 시 자동으로 인증 이메일을 보내려면 emailVerification.sendOnSignUp을 true로 설정합니다.
import { betterAuth } from 'better-auth';
export const auth = betterAuth({
emailVerification: {
sendOnSignUp: true
}
})이렇게 하면 사용자가 가입할 때 인증 이메일이 전송됩니다. 소셜 로그인의 경우 이메일 인증 상태는 SSO에서 읽습니다.
sendOnSignUp이 활성화된 경우 사용자가 이메일이 인증되지 않았다고 주장하는 SSO로 로그인하면 Better Auth가 인증 이메일을 발송하지만 requireEmailVerification이 활성화된 경우에도 로그인하는 데 인증이 필요하지 않습니다.
2. 이메일 인증 필수
이메일 인증을 필수로 활성화하면 사용자가 로그인하기 전에 이메일을 인증해야 합니다. 그리고 사용자가 로그인을 시도할 때마다 sendVerificationEmail이 호출됩니다.
이는 sendVerificationEmail이 구현되어 있고 사용자가 이메일 및 비밀번호로 로그인하려고 하는 경우에만 작동합니다.
export const auth = betterAuth({
emailAndPassword: {
requireEmailVerification: true
}
})사용자가 이메일을 인증하지 않고 로그인을 시도하면 에러를 처리하고 사용자에게 메시지를 표시할 수 있습니다.
await authClient.signIn.email({
email: "email@example.com",
password: "password"
}, {
onError: (ctx) => {
// 에러 처리
if(ctx.error.status === 403) {
alert("이메일 주소를 인증해주세요")
}
//원래 에러 메시지를 표시할 수도 있습니다
alert(ctx.error.message)
}
})3. 수동으로
sendVerificationEmail을 호출하여 수동으로 이메일 인증을 트리거할 수도 있습니다.
await authClient.sendVerificationEmail({
email: "user@email.com",
callbackURL: "/" // 인증 후 리디렉션 URL
})이메일 인증하기
사용자가 제공된 인증 URL을 클릭하면 이메일이 자동으로 인증되고 callbackURL로 리디렉션됩니다.
수동 인증의 경우 사용자에게 token이 포함된 사용자 정의 링크를 보내고 verifyEmail 함수를 호출할 수 있습니다.
await authClient.verifyEmail({
query: {
token: "" // 여기에 토큰 전달
}
})인증 후 자동 로그인
사용자가 이메일을 성공적으로 인증한 후 자동으로 로그인하려면 autoSignInAfterVerification 옵션을 true로 설정합니다:
const auth = betterAuth({
//...다른 옵션
emailVerification: {
autoSignInAfterVerification: true
}
})이메일 인증 성공 후 콜백
사용자가 이메일을 인증한 직후 afterEmailVerification 콜백을 사용하여 사용자 정의 코드를 실행할 수 있습니다. 이는 특별 기능에 대한 액세스 권한 부여나 이벤트 로깅과 같은 부작용을 트리거하는 데 유용합니다.
afterEmailVerification 함수는 사용자의 이메일이 확인되면 자동으로 실행되며 user 객체와 request 세부 정보를 받아 해당 특정 사용자에 대한 작업을 수행할 수 있습니다.
설정 방법은 다음과 같습니다:
import { betterAuth } from 'better-auth';
export const auth = betterAuth({
emailVerification: {
async afterEmailVerification(user, request) {
// 여기에 사용자 정의 로직, 예: 프리미엄 기능에 대한 액세스 권한 부여
console.log(`${user.email}이(가) 성공적으로 인증되었습니다!`);
}
}
})비밀번호 재설정 이메일
비밀번호 재설정을 사용하면 사용자가 비밀번호를 잊어버린 경우 재설정할 수 있습니다. Better Auth는 비밀번호 재설정 기능을 구현하는 간단한 방법을 제공합니다.
링크가 포함된 비밀번호 재설정 이메일을 보내는 함수를 전달하여 비밀번호 재설정을 활성화할 수 있습니다.
import { betterAuth } from 'better-auth';
import { sendEmail } from './email'; // 이메일 발송 함수
export const auth = betterAuth({
emailAndPassword: {
enabled: true,
sendResetPassword: async ({ user, url, token }, request) => {
await sendEmail({
to: user.email,
subject: '비밀번호를 재설정하세요',
text: `다음 링크를 클릭하여 비밀번호를 재설정하세요: ${url}`
})
}
}
})앱에서 비밀번호 재설정을 구현하는 방법에 대한 자세한 내용은 Email and Password 가이드를 확인하세요. 또한 앱에서 OTP를 사용하여 비밀번호 재설정을 구현하는 방법에 대해서는 Otp verification 가이드를 확인하세요.