이메일 & 비밀번호

이메일 및 비밀번호 인증은 많은 애플리케이션에서 사용되는 일반적인 방법입니다. Better Auth는 프로젝트에 쉽게 통합할 수 있는 내장 이메일 및 비밀번호 인증 기능을 제공합니다.

이메일 및 비밀번호 활성화

이메일 및 비밀번호 인증을 활성화하려면 auth 구성에서 emailAndPassword.enabled 옵션을 true로 설정해야 합니다.

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  emailAndPassword: { 
    enabled: true, 
  }, 
});

사용법

회원가입

사용자를 가입시키려면 클라이언트에서 제공하는 signUp.email 함수를 사용할 수 있습니다.

const { data, error } = await authClient.signUp.email({    name: "John Doe", // required    email: "john.doe@example.com", // required    password: "password1234", // required    image: "https://example.com/image.png",    callbackURL: "https://example.com/callback",});

const data = await auth.api.signUpEmail({    body: {        name: "John Doe", // required        email: "john.doe@example.com", // required        password: "password1234", // required        image: "https://example.com/image.png",        callbackURL: "https://example.com/callback",    },});

로그인

사용자를 로그인시키려면 클라이언트에서 제공하는 signIn.email 함수를 사용할 수 있습니다.

const { data, error } = await authClient.signIn.email({    email: "john.doe@example.com", // required    password: "password1234", // required    rememberMe: true,    callbackURL: "https://example.com/callback",});

const data = await auth.api.signInEmail({    body: {        email: "john.doe@example.com", // required        password: "password1234", // required        rememberMe: true,        callbackURL: "https://example.com/callback",    },    // This endpoint requires session cookies.    headers: await headers(),});

로그아웃

사용자를 로그아웃시키려면 클라이언트에서 제공하는 signOut 함수를 사용할 수 있습니다.

await authClient.signOut();

await auth.api.signOut({    // This endpoint requires session cookies.    headers: await headers(),});

성공 시 리디렉션하려면 fetchOptions를 전달할 수 있습니다

await authClient.signOut({
  fetchOptions: {
    onSuccess: () => {
      router.push("/login"); // 로그인 페이지로 리디렉션
    },
  },
});

이메일 인증

이메일 인증을 활성화하려면 링크가 포함된 인증 이메일을 전송하는 함수를 전달해야 합니다. sendVerificationEmail 함수는 다음 속성을 가진 데이터 객체를 받습니다:

• user: 사용자 객체.
• url: 토큰이 포함된 사용자에게 보낼 URL.
• token: 이메일 인증을 완료하는 데 사용되는 인증 토큰.

그리고 두 번째 매개변수로 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}`,
      });
    },
  },
});

클라이언트 측에서는 sendVerificationEmail 함수를 사용하여 사용자에게 인증 링크를 보낼 수 있습니다. 이렇게 하면 auth 구성에서 제공한 sendVerificationEmail 함수가 트리거됩니다.

사용자가 이메일의 링크를 클릭하면 토큰이 유효한 경우 callbackURL 매개변수에 제공된 URL로 리디렉션됩니다. 토큰이 유효하지 않으면 쿼리 문자열에 오류 메시지 ?error=invalid_token와 함께 callbackURL 매개변수에 제공된 URL로 리디렉션됩니다.

이메일 인증 필수

이메일 인증을 필수로 활성화하면 사용자가 로그인하기 전에 이메일을 인증해야 합니다. 그리고 사용자가 로그인을 시도할 때마다 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);
    },
  }
);

수동으로 이메일 인증 트리거하기

sendVerificationEmail 함수를 호출하여 이메일 인증을 수동으로 트리거할 수 있습니다.

await authClient.sendVerificationEmail({
  email: "user@email.com",
  callbackURL: "/", // 인증 후 리디렉션 URL
});

비밀번호 재설정 요청

사용자가 비밀번호를 재설정할 수 있도록 먼저 이메일 및 비밀번호 인증 기능에 sendResetPassword 함수를 제공해야 합니다. sendResetPassword 함수는 다음 속성을 가진 데이터 객체를 받습니다:

• user: 사용자 객체.
• url: 토큰이 포함된 사용자에게 보낼 URL.
• token: 비밀번호 재설정을 완료하는 데 사용되는 인증 토큰.

그리고 두 번째 매개변수로 request 객체를 받습니다.

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}`,
      });
    },
    onPasswordReset: async ({ user }, request) => {
      // 여기에 로직 추가
      console.log(`사용자 ${user.email}의 비밀번호가 재설정되었습니다.`);
    },
  },
});

또한 비밀번호가 성공적으로 재설정된 후 실행할 로직을 위해 onPasswordReset 콜백을 제공할 수 있습니다.

서버를 구성한 후 requestPasswordReset 함수를 호출하여 사용자에게 비밀번호 재설정 링크를 보낼 수 있습니다. 사용자가 존재하면 auth 구성에서 제공한 sendResetPassword 함수가 트리거됩니다.

const { data, error } = await authClient.requestPasswordReset({    email: "john.doe@example.com", // required    redirectTo: "https://example.com/reset-password",});

const data = await auth.api.requestPasswordReset({    body: {        email: "john.doe@example.com", // required        redirectTo: "https://example.com/reset-password",    },});

사용자가 이메일의 링크를 클릭하면 비밀번호 재설정 페이지로 리디렉션됩니다. 앱에 비밀번호 재설정 페이지를 추가할 수 있습니다. 그런 다음 resetPassword 함수를 사용하여 비밀번호를 재설정할 수 있습니다. 다음 속성을 가진 객체를 받습니다:

• newPassword: 사용자의 새 비밀번호.

const { data, error } = await authClient.resetPassword({
  newPassword: "password1234",
  token,
});

const token = new URLSearchParams(window.location.search).get("token");if (!token) {  // 오류 처리}const { data, error } = await authClient.resetPassword({    newPassword: "password1234", // required    token, // required});

const token = new URLSearchParams(window.location.search).get("token");if (!token) {  // 오류 처리}const data = await auth.api.resetPassword({    body: {        newPassword: "password1234", // required        token, // required    },});

비밀번호 업데이트

사용자의 비밀번호는 user 테이블에 저장되지 않습니다. 대신 account 테이블에 저장됩니다. 사용자의 비밀번호를 변경하려면 다음 방법 중 하나를 사용할 수 있습니다:

const { data, error } = await authClient.changePassword({    newPassword: "newpassword1234", // required    currentPassword: "oldpassword1234", // required    revokeOtherSessions: true,});

const data = await auth.api.changePassword({    body: {        newPassword: "newpassword1234", // required        currentPassword: "oldpassword1234", // required        revokeOtherSessions: true,    },    // This endpoint requires session cookies.    headers: await headers(),});

구성

비밀번호

Better Auth는 비밀번호를 providerId가 credential로 설정된 account 테이블에 저장합니다.

비밀번호 해싱: Better Auth는 scrypt를 사용하여 비밀번호를 해싱합니다. scrypt 알고리즘은 공격자가 비밀번호를 무차별 대입하기 어렵도록 느리고 메모리 집약적으로 설계되었습니다. OWASP는 argon2id를 사용할 수 없는 경우 scrypt 사용을 권장합니다. Node.js에서 기본적으로 지원하기 때문에 scrypt를 사용하기로 결정했습니다.

auth 구성에서 passwordHasher 옵션을 설정하여 사용자 정의 비밀번호 해싱 알고리즘을 전달할 수 있습니다.

import { betterAuth } from "better-auth"
import { scrypt } from "scrypt"

export const auth = betterAuth({
    //...나머지 옵션
    emailAndPassword: {
        password: {
            hash: // 사용자 정의 비밀번호 해싱 함수
            verify: // 사용자 정의 비밀번호 검증 함수
        }
    }
})