邮箱一次性密码

Email OTP 插件允许用户通过发送到其邮箱地址的一次性密码（OTP）进行登录、验证邮箱或重置密码。

安装

将插件添加到您的认证配置中

将 emailOTP 插件添加到您的认证配置中，并实现 sendVerificationOTP() 方法。

auth.ts

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

export const auth = betterAuth({
    // ... 其他配置选项
    plugins: [
        emailOTP({ 
            async sendVerificationOTP({ email, otp, type }) { 
                if (type === "sign-in") { 
                    // 发送用于登录的 OTP
                } else if (type === "email-verification") { 
                    // 发送用于邮箱验证的 OTP
                } else { 
                    // 发送用于密码重置的 OTP
                } 
            }, 
        }) 
    ]
})

添加客户端插件

auth-client.ts

import { createAuthClient } from "better-auth/client"
import { emailOTPClient } from "better-auth/client/plugins"

export const authClient = createAuthClient({
    plugins: [
        emailOTPClient()
    ]
})

使用方法

发送 OTP

使用 sendVerificationOtp() 方法向用户的邮箱地址发送一次性密码（OTP）。

POST

/email-otp/send-verification-otp

const { data, error } = await authClient.emailOtp.sendVerificationOtp({
    email: "user@example.com", // required
    type: "sign-in", // required
});

const { data, error } = await authClient.emailOtp.sendVerificationOtp({    email: "user@example.com", // required    type: "sign-in", // required});

属性	描述	类型
`email`	用于发送 OTP 的邮箱地址。	`string`
`type`	OTP 类型。可选值为 `sign-in`（登录）、`email-verification`（邮箱验证）或 `forget-password`（忘记密码）。	`"email-verification" \| "sign-in" \| "forget-password"`

校验 OTP（可选）

使用 checkVerificationOtp() 方法验证 OTP 是否有效。

POST

/email-otp/check-verification-otp

const { data, error } = await authClient.emailOtp.checkVerificationOtp({
    email: "user@example.com", // required
    type: "sign-in", // required
    otp: "123456", // required
});

const { data, error } = await authClient.emailOtp.checkVerificationOtp({    email: "user@example.com", // required    type: "sign-in", // required    otp: "123456", // required});

属性	描述	类型
`email`	用于发送 OTP 的邮箱地址。	`string`
`type`	OTP 类型。可选值为 `sign-in`（登录）、`email-verification`（邮箱验证）或 `forget-password`（忘记密码）。	`"email-verification" \| "sign-in" \| "forget-password"`
`otp`	发送到邮箱的 OTP 验证码。	`string`

使用 OTP 登录

要通过 OTP 登录，请使用 sendVerificationOtp() 方法向用户的电子邮件地址发送一个“sign-in”（登录）类型的 OTP。

POST

/email-otp/send-verification-otp

const { data, error } = await authClient.emailOtp.sendVerificationOtp({
    email: "user@example.com", // required
    type: "sign-in", // required
});

const { data, error } = await authClient.emailOtp.sendVerificationOtp({    email: "user@example.com", // required    type: "sign-in", // required});

属性	描述	类型
`email`	要发送 OTP 的电子邮件地址。	`string`
`type`	OTP 的类型。	`"sign-in"`

当用户提供 OTP 后，您可以使用 signIn.emailOtp() 方法让用户登录。

POST

/sign-in/email-otp

const { data, error } = await authClient.signIn.emailOtp({
    email: "user@example.com", // required
    otp: "123456", // required
});

const { data, error } = await authClient.signIn.emailOtp({    email: "user@example.com", // required    otp: "123456", // required});

属性	描述	类型
`email`	用于登录的电子邮件地址。	`string`
`otp`	发送到电子邮件的 OTP。	`string`

如果用户尚未注册，系统将自动为其注册。如果您想阻止此行为，可以在 options 中将 disableSignUp 设置为 true。

使用 OTP 验证电子邮件

要通过 OTP 验证用户的电子邮件地址，请使用 sendVerificationOtp() 方法向用户的电子邮件地址发送一个“email-verification”（邮件验证）类型的 OTP。

POST

/email-otp/send-verification-otp

const { data, error } = await authClient.emailOtp.sendVerificationOtp({
    email: "user@example.com", // required
    type: "email-verification", // required
});

const { data, error } = await authClient.emailOtp.sendVerificationOtp({    email: "user@example.com", // required    type: "email-verification", // required});

属性	描述	类型
`email`	要发送 OTP 的电子邮件地址。	`string`
`type`	OTP 的类型。	`"email-verification"`

当用户提供 OTP 后，使用 verifyEmail() 方法完成电子邮件验证。

POST

/email-otp/verify-email

const { data, error } = await authClient.emailOtp.verifyEmail({
    email: "user@example.com", // required
    otp: "123456", // required
});

const { data, error } = await authClient.emailOtp.verifyEmail({    email: "user@example.com", // required    otp: "123456", // required});

属性	描述	类型
`email`	要验证的电子邮件地址。	`string`
`otp`	用于验证的 OTP。	`string`

使用 OTP 重置密码

要通过 OTP 重置用户密码，请使用 forgetPassword.emailOTP() 方法向用户的电子邮件地址发送“忘记密码”OTP。

POST

/forget-password/email-otp

const { data, error } = await authClient.forgetPassword.emailOtp({
    email: "user@example.com", // required
});

const { data, error } = await authClient.forgetPassword.emailOtp({    email: "user@example.com", // required});

属性	描述	类型
`email`	发送 OTP 的电子邮件地址。	`string`

当用户提供 OTP 后，可以使用 checkVerificationOtp() 方法验证其有效性（可选步骤）。

POST

/email-otp/check-verification-otp

const { data, error } = await authClient.emailOtp.checkVerificationOtp({
    email: "user@example.com", // required
    type: "forget-password", // required
    otp: "123456", // required
});

const { data, error } = await authClient.emailOtp.checkVerificationOtp({    email: "user@example.com", // required    type: "forget-password", // required    otp: "123456", // required});

属性	描述	类型
`email`	发送 OTP 的电子邮件地址。	`string`
`type`	OTP 类型。	`"forget-password"`
`otp`	发送至邮箱的 OTP。	`string`

随后，使用 resetPassword() 方法重置用户密码。

POST

/email-otp/reset-password

const { data, error } = await authClient.emailOtp.resetPassword({
    email: "user@example.com", // required
    otp: "123456", // required
    password: "new-secure-password", // required
});

const { data, error } = await authClient.emailOtp.resetPassword({    email: "user@example.com", // required    otp: "123456", // required    password: "new-secure-password", // required});

属性	描述	类型
`email`	需要重置密码的邮箱地址。	`string`
`otp`	发送至邮箱的 OTP。	`string`
`password`	新密码。	`string`

覆盖默认邮箱验证

要覆盖默认的邮箱验证功能，请在选项中传入 overrideDefaultEmailVerification: true。这将使系统在触发邮箱验证时使用邮箱 OTP（一次性密码）而非默认的验证链接。换句话说，用户将通过 OTP 来验证邮箱，而不是点击链接。

auth.ts

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  plugins: [
    emailOTP({
      overrideDefaultEmailVerification: true, 
      async sendVerificationOTP({ email, otp, type }) {
        // 实现 sendVerificationOTP 方法，将 OTP 发送到用户的邮箱地址
      },
    }),
  ],
});

选项

sendVerificationOTP: 用于向用户邮箱发送 OTP 的函数。该函数接收一个包含以下属性的对象：
- email: 用户的邮箱地址
- otp: 要发送的 OTP
- type: 要发送的 OTP 类型。可以是 "sign-in"（登录）、"email-verification"（邮箱验证）或 "forget-password"（忘记密码）
otpLength: OTP 的长度。默认为 6
expiresIn: OTP 的过期时间（单位：秒）。默认为 300 秒

auth.ts

import { betterAuth } from "better-auth"

export const auth = betterAuth({
    plugins: [
        emailOTP({
            otpLength: 8,
            expiresIn: 600
        })
    ]
})

sendVerificationOnSignUp: 布尔值，决定是否在用户注册时发送 OTP。默认为 false
disableSignUp: 布尔值，决定是否在用户未注册时阻止自动注册。默认为 false
generateOTP: 生成 OTP 的函数。默认为随机 6 位数字
allowedAttempts: 验证 OTP 允许的最大尝试次数。默认为 3。超过此限制后，OTP 将失效，用户需要重新请求新的 OTP

auth.ts

import { betterAuth } from "better-auth"

export const auth = betterAuth({
    plugins: [
        emailOTP({
            allowedAttempts: 5, // 允许 5 次尝试，之后 OTP 将失效
            expiresIn: 300
        })
    ]
})

当超过最大尝试次数时，verifyOTP、signIn.emailOtp、verifyEmail 和 resetPassword 方法将返回错误码 MAX_ATTEMPTS_EXCEEDED

storeOTP: 在数据库中存储 OTP 的方式，可以是 encrypted（加密）、hashed（哈希）或 plain（明文）。默认为 plain（明文）

注意：这不会影响发送给用户的 OTP，只会影响存储在数据库中的 OTP

或者，您可以传递自定义的加密器或哈希器来在数据库中存储 OTP

自定义加密器

auth.ts

emailOTP({
    storeOTP: {
        encrypt: async (otp) => {
            return myCustomEncryptor(otp);
        },
        decrypt: async (otp) => {
            return myCustomDecryptor(otp);
        },
    }
})

自定义哈希器

auth.ts

emailOTP({
    storeOTP: {
        hash: async (otp) => {
            return myCustomHasher(otp);
        },
    }
})

开始使用

概念

身份验证

数据库

集成

插件

指南

参考

On this page