mirror of
https://github.com/LukeHagar/better-auth.git
synced 2025-12-08 20:37:44 +00:00
c4f89adbcd
* add(docs): demo code to set password on the server. * fix(docs): update password --------- Co-authored-by: Bereket Engida <bekacru@gmail.com>
307 lines
9.6 KiB
Plaintext
307 lines
9.6 KiB
Plaintext
---
|
|
title: Email & Password
|
|
description: Implementing email and password authentication with Better Auth.
|
|
---
|
|
|
|
Email and password authentication is a common method used by many applications. Better Auth provides a built-in email and password authenticator that you can easily integrate into your project.
|
|
|
|
<Callout type="info">
|
|
If you prefer username-based authentication, check out the{" "}
|
|
<Link href="/docs/plugins/username">username plugin</Link>. It extends the
|
|
email and password authenticator with username support.
|
|
</Callout>
|
|
|
|
## Enable Email and Password
|
|
|
|
To enable email and password authentication, you need to set the `emailAndPassword.enabled` option to `true` in the `auth` configuration.
|
|
|
|
```ts title="auth.ts"
|
|
import { betterAuth } from "better-auth";
|
|
|
|
export const auth = betterAuth({
|
|
emailAndPassword: { // [!code highlight]
|
|
enabled: true, // [!code highlight]
|
|
}, // [!code highlight]
|
|
});
|
|
```
|
|
|
|
<Callout type="info">
|
|
If it's not enabled, it'll not allow you to sign in or sign up with email and
|
|
password.
|
|
</Callout>
|
|
|
|
## Usage
|
|
|
|
### Sign Up
|
|
|
|
To sign a user up, you can use the `signUp.email` function provided by the client. The `signUp` function takes an object with the following properties:
|
|
|
|
- `email`: The email address of the user.
|
|
- `password`: The password of the user. It should be at least 8 characters long and max 32 by default.
|
|
- `name`: The name of the user.
|
|
- `image`: The image of the user. (optional)
|
|
|
|
```ts title="auth-client.ts"
|
|
const { data, error } = await authClient.signUp.email({
|
|
email: "test@example.com",
|
|
password: "password1234",
|
|
name: "test",
|
|
image: "https://example.com/image.png",
|
|
});
|
|
```
|
|
|
|
### Sign In
|
|
|
|
To sign a user in, you can use the `signIn.email` function provided by the client. The `signIn` function takes an object with the following properties:
|
|
|
|
- `email`: The email address of the user.
|
|
- `password`: The password of the user.
|
|
- `rememberMe`: If false, the user will be signed out when the browser is closed. (optional) (default: true)
|
|
- `callbackURL`: The URL to redirect to after the user signs in. (optional)
|
|
|
|
```ts title="auth-client.ts"
|
|
const { data, error } = await authClient.signIn.email({
|
|
email: "test@example.com",
|
|
password: "password1234",
|
|
});
|
|
```
|
|
|
|
### Sign Out
|
|
|
|
To sign a user out, you can use the `signOut` function provided by the client.
|
|
|
|
```ts title="auth-client.ts"
|
|
await authClient.signOut();
|
|
```
|
|
|
|
you can pass `fetchOptions` to redirect onSuccess
|
|
|
|
```ts title="auth-client.ts"
|
|
await authClient.signOut({
|
|
fetchOptions: {
|
|
onSuccess: () => {
|
|
router.push("/login"); // redirect to login page
|
|
},
|
|
},
|
|
});
|
|
```
|
|
|
|
### Email Verification
|
|
|
|
To enable email verification, you need to pass a function that sends a verification email with a link. The `sendVerificationEmail` function takes a data object with the following properties:
|
|
|
|
- `user`: The user object.
|
|
- `url`: The url to send to the user which contains the token.
|
|
- `token`: A verification token used to complete the email verification.
|
|
|
|
and a `request` object as the second parameter.
|
|
|
|
```ts title="auth.ts"
|
|
import { betterAuth } from "better-auth";
|
|
import { sendEmail } from "./email"; // your email sending function
|
|
|
|
export const auth = betterAuth({
|
|
emailVerification: {
|
|
sendVerificationEmail: async ( { user, url, token }, request) => {
|
|
await sendEmail({
|
|
to: user.email,
|
|
subject: "Verify your email address",
|
|
text: `Click the link to verify your email: ${url}`,
|
|
});
|
|
},
|
|
},
|
|
});
|
|
```
|
|
|
|
On the client side you can use `sendVerificationEmail` function to send verification link to user. This will trigger the `sendVerificationEmail` function you provided in the `auth` configuration.
|
|
|
|
Once the user clicks on the link in the email, if the token is valid, the user will be redirected to the URL provided in the `callbackURL` parameter. If the token is invalid, the user will be redirected to the URL provided in the `callbackURL` parameter with an error message in the query string `?error=invalid_token`.
|
|
|
|
#### Require Email Verification
|
|
|
|
If you enable require email verification, users must verify their email before they can log in. And every time a user tries to sign in, sendVerificationEmail is called.
|
|
|
|
<Callout>
|
|
This only works if you have sendVerificationEmail implemented and if the user
|
|
is trying to sign in with email and password.
|
|
</Callout>
|
|
|
|
```ts title="auth.ts"
|
|
export const auth = betterAuth({
|
|
emailAndPassword: {
|
|
requireEmailVerification: true,
|
|
},
|
|
});
|
|
```
|
|
|
|
If a user tries to sign in without verifying their email, you can handle the error and show a message to the user.
|
|
|
|
```ts title="auth-client.ts"
|
|
await authClient.signIn.emailAndPassword(
|
|
{
|
|
email: "email@example.com",
|
|
password: "password",
|
|
},
|
|
{
|
|
onError: (ctx) => {
|
|
// Handle the error
|
|
if (ctx.error.status === 403) {
|
|
alert("Please verify your email address");
|
|
}
|
|
//you can also show the original error message
|
|
alert(ctx.error.message);
|
|
},
|
|
}
|
|
);
|
|
```
|
|
|
|
#### Triggering manually Email Verification
|
|
|
|
You can trigger the email verification manually by calling the `sendVerificationEmail` function.
|
|
|
|
```ts
|
|
await authClient.sendVerificationEmail({
|
|
email: "user@email.com",
|
|
callbackURL: "/", // The redirect URL after verification
|
|
});
|
|
```
|
|
|
|
### Forget Password
|
|
|
|
To allow users to reset a password first you need to provide `sendResetPassword` function to the email and password authenticator. The `sendResetPassword` function takes a data object with the following properties:
|
|
|
|
- `user`: The user object.
|
|
- `url`: The url to send to the user which contains the token.
|
|
- `token`: A verification token used to complete the password reset.
|
|
|
|
and a `request` object as the second parameter.
|
|
|
|
```ts title="auth.ts"
|
|
import { betterAuth } from "better-auth";
|
|
import { sendEmail } from "./email"; // your email sending function
|
|
|
|
export const auth = betterAuth({
|
|
emailAndPassword: {
|
|
enabled: true,
|
|
sendResetPassword: async ({user, url, token}, request) => {
|
|
await sendEmail({
|
|
to: user.email,
|
|
subject: "Reset your password",
|
|
text: `Click the link to reset your password: ${url}`,
|
|
});
|
|
},
|
|
},
|
|
});
|
|
```
|
|
|
|
Once you configured your server you can call `forgetPassword` function to send reset password link to user. If the user exists, it will trigger the `sendResetPassword` function you provided in the auth config.
|
|
|
|
It takes an object with the following properties:
|
|
|
|
- `email`: The email address of the user.
|
|
- `redirectTo`: The URL to redirect to after the user clicks on the link in the email. If the token is valid, the user will be redirected to this URL with the token in the query string. If the token is invalid, the user will be redirected to this URL with an error message in the query string `?error=invalid_token`.
|
|
|
|
```ts title="auth-client.ts"
|
|
const { data, error } = await authClient.forgetPassword({
|
|
email: "test@example.com",
|
|
redirectTo: "/reset-password",
|
|
});
|
|
```
|
|
|
|
When a user clicks on the link in the email, they will be redirected to the reset password page. You can add the reset password page to your app. Then you can use `resetPassword` function to reset the password. It takes an object with the following properties:
|
|
|
|
- `newPassword`: The new password of the user.
|
|
|
|
```ts title="auth-client.ts"
|
|
const token = new URLSearchParams(window.location.search).get("token");
|
|
if (!token) {
|
|
// Handle the error
|
|
}
|
|
const { data, error } = await authClient.resetPassword({
|
|
newPassword: "password1234",
|
|
token,
|
|
});
|
|
```
|
|
|
|
### Update password
|
|
|
|
<Callout type="warn">
|
|
This only works on server-side, and the following code may change over time.
|
|
</Callout>
|
|
|
|
To set a password, you must hash it first:
|
|
|
|
```ts
|
|
const ctx = await auth.$context;
|
|
const hash = await ctx.password.hash("your-new-password");
|
|
```
|
|
|
|
Then, to set the password:
|
|
```ts
|
|
await ctx.internalAdapter.updatePassword("userId", hash) //(you can also use your orm directly)
|
|
```
|
|
|
|
### Configuration
|
|
|
|
**Password**
|
|
|
|
Better Auth stores passwords inside the `account` table with `providerId` set to `credential`.
|
|
|
|
**Password Hashing**: Better Auth uses `scrypt` to hash passwords. The `scrypt` algorithm is designed to be slow and memory-intensive to make it difficult for attackers to brute force passwords. OWASP recommends using `scrypt` if `argon2id` is not available. We decided to use `scrypt` because it's natively supported by Node.js.
|
|
|
|
You can pass custom password hashing algorithm by setting `passwordHasher` option in the `auth` configuration.
|
|
|
|
```ts title="auth.ts"
|
|
import { betterAuth } from "better-auth"
|
|
import { scrypt } from "scrypt"
|
|
|
|
export const auth = betterAuth({
|
|
//...rest of the options
|
|
emailAndPassword: {
|
|
password: {
|
|
hash: // your custom password hashing function
|
|
verify: // your custom password verification function
|
|
}
|
|
}
|
|
})
|
|
```
|
|
|
|
<TypeTable
|
|
type={{
|
|
enabled: {
|
|
description: "Enable email and password authentication.",
|
|
type: "boolean",
|
|
default: "false",
|
|
},
|
|
minPasswordLength: {
|
|
description: "The minimum length of a password.",
|
|
type: "number",
|
|
default: 8,
|
|
},
|
|
maxPasswordLength: {
|
|
description: "The maximum length of a password.",
|
|
type: "number",
|
|
default: 128,
|
|
},
|
|
sendResetPassword: {
|
|
description:
|
|
"Sends a password reset email. It takes a function that takes two parameters: token and user.",
|
|
type: "function",
|
|
},
|
|
password: {
|
|
description: "Password configuration.",
|
|
type: "object",
|
|
properties: {
|
|
hash: {
|
|
description: "custom password hashing function",
|
|
type: "function",
|
|
},
|
|
verify: {
|
|
description: "custom password verification function",
|
|
type: "function",
|
|
},
|
|
},
|
|
},
|
|
}}
|
|
/>
|