LukeParke/better-auth
1
0
Fork 0
mirror of https://github.com/LukeHagar/better-auth.git synced 2025-12-10 12:27:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: email and password integration docs improved clarity and added new examples (#269)

Browse Source
This commit is contained in:
Gregor Wedlich
2024-10-20 19:38:53 +02:00
committed by GitHub
parent 23b610dffd
commit 4a454bb6fe
1 changed files with 134 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

206
docs/content/docs/authentication/email-password.mdx
View File

@@ -6,7 +6,9 @@ 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.
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
@@ -14,20 +16,21 @@ Email and password authentication is a common method used by many applications.
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"
import { betterAuth } from "better-auth";
export const auth = betterAuth({
emailAndPassword: { // [!code highlight]
enabled: true // [!code highlight]
} // [!code highlight]
})
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.
If it's not enabled, it'll not allow you to sign in or sign up with email and
password.
</Callout>
## Usage
### Signup
@@ -43,12 +46,12 @@ To signup a user, you can use the `signUp.email` function provided by the client
```ts title="client.ts"
const { data, error } = await authClient.signUp.email({
email: "test@example.com",
password: "password1234",
name: "test",
image: "https://example.com/image.png",
callbackURL: "/"
})
email: "test@example.com",
password: "password1234",
name: "test",
image: "https://example.com/image.png",
callbackURL: "/",
});
```
### Signin
@@ -62,10 +65,10 @@ To signin a user, you can use the `signIn.email` function provided by the client
```ts title="client.ts"
const { data, error } = await authClient.signIn.email({
email: "test@example.com",
password: "password1234",
callbackURL: "/"
})
email: "test@example.com",
password: "password1234",
callbackURL: "/",
});
```
### Signout
@@ -73,56 +76,114 @@ const { data, error } = await authClient.signIn.email({
To signout a user, you can use the `signOut` function provided by the client.
```ts title="client.ts"
await client.signOut()
await client.signOut();
```
### Email Verification
To enable email verification, you need to provide `sendVerificationEmail` function to the email and password authenticator. The `sendVerificationEmail` function takes an object with the following properties:
To enable email verification, you need to pass a function that sends a verification email with a link. The `sendVerificationEmail` function takes an 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.
```ts title="auth.ts"
import { betterAuth } from "better-auth"
import { betterAuth } from "better-auth";
import { sendEmail } from "./email"; // your email sending function
export const auth = betterAuth({
emailAndPassword: {
enabled: true,
async sendVerificationEmail(url, user){
// send email to user.
}
}
})
emailVerification: {
sendVerificationEmail: async (user, url, token) => {
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.
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="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 an object with the following properties:
To allow users to reset a password first you need to provide `sendResetPassword` function to the email and password authenticator. The `sendResetPassword` function takes an 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.
```ts title="auth.ts"
import { betterAuth } from "better-auth"
import { betterAuth } from "better-auth";
import { sendEmail } from "./email"; // your email sending function
export const auth = betterAuth({
emailAndPassword: { // [!code highlight]
enabled: true, // [!code highlight]
async sendResetPassword(url, user) { // [!code highlight]
// send email to user // [!code highlight]
await sendResetEmail(user.email, url) //your function to send email to user // [!code highlight]
}, // [!code highlight]
} // [!code highlight]
})
emailAndPassword: {
enabled: true,
sendResetPassword: async (user, url, token) => {
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` configuration.
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` configuration.
It takes an object with the following properties:
@@ -131,9 +192,9 @@ It takes an object with the following properties:
```ts title="client.ts"
const { data, error } = await client.forgetPassword({
email: "test@example.com",
redirectTo: "/reset-password"
})
email: "test@example.com",
redirectTo: "/reset-password",
});
```
When user click on the link in the email he 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:
@@ -142,8 +203,8 @@ When user click on the link in the email he will be redirected to the reset pass
```ts title="client.ts"
const { data, error } = await client.resetPassword({
newPassword: "password1234",
})
newPassword: "password1234",
});
```
### Configuration
@@ -152,7 +213,7 @@ const { data, error } = await client.resetPassword({
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. OWSAP recommends using `scrypt` if `argon2id` is not available. We decided to use `scrypt` because it's natively supported by Node.js.
**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. OWSAP 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 algothim by setting `passwordHasher` option in the `auth` configuration.
@@ -174,42 +235,43 @@ export const auth = betterAuth({
<TypeTable
type={{
enabled: {
description:
'Enable email and password authentication',
type: 'boolean',
description: "Enable email and password authentication",
type: "boolean",
default: false,
},
minPasswordLength: {
description: 'The minimum length of the password.',
type: 'number',
default: 8,
description: "The minimum length of the password.",
type: "number",
default: 8,
},
maxPasswordLength: {
description: 'The maximum length of the password.',
type: 'number',
default: 32,
description: "The maximum length of the password.",
type: "number",
default: 32,
},
sendResetPassword: {
description: 'send reset password email. It takes a functions that takes two parameters: token and user.',
type: 'function',
description:
"send reset password email. It takes a functions that takes two parameters: token and user.",
type: "function",
},
sendVerificationEmail: {
description: 'send verification email. It takes a functions that takes two parameters: email and url.',
type: 'function',
description:
"send verification email. It takes a functions that takes two parameters: email and url.",
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',
}
}
}
description: "password configuration",
type: "object",
properties: {
hash: {
description: "custom password hashing function",
type: "function",
},
verify: {
description: "custom password verification function",
type: "function",
},
},
},
}}
/>