web/versioned_docs/version-0.22/auth/email.md
import { Required } from '@site/src/components/Tag'; import MultipleIdentitiesWarning from './_multiple-identities-warning.md'; import ReadMoreAboutAuthEntities from './_read-more-about-auth-entities.md'; import UserSignupFieldsExplainer from './_user-signup-fields-explainer.md'; import UserFields from './_user-fields.md'; import EmailData from './entities/_email-data.md'; import AccessingUserDataNote from './_accessing-user-data-note.md'; import TailwindNote from './_tailwind-note.md';
Wasp supports e-mail authentication out of the box, along with email verification and "forgot your password?" flows. It provides you with the server-side implementation and email templates for all of these flows.
<MultipleIdentitiesWarning />We'll need to take the following steps to set up email authentication:
User entityStructure of the main.wasp file we will end up with:
// Configuring e-mail authentication
app myApp {
auth: { ... },
emailSender: { ... }
}
// Defining routes and pages
route SignupRoute { ... }
page SignupPage { ... }
// ...
main.waspLet's start with adding the following to our main.wasp file:
Read more about the email auth method options here.
The User entity can be as simple as including only the id field:
Next, we need to define the routes and pages for the authentication pages.
Add the following to the main.wasp file:
route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
component: import { Login } from "@src/pages/auth"
}
route SignupRoute { path: "/signup", to: SignupPage }
page SignupPage {
component: import { Signup } from "@src/pages/auth"
}
route RequestPasswordResetRoute { path: "/request-password-reset", to: RequestPasswordResetPage }
page RequestPasswordResetPage {
component: import { RequestPasswordReset } from "@src/pages/auth",
}
route PasswordResetRoute { path: "/password-reset", to: PasswordResetPage }
page PasswordResetPage {
component: import { PasswordReset } from "@src/pages/auth",
}
route EmailVerificationRoute { path: "/email-verification", to: EmailVerificationPage }
page EmailVerificationPage {
component: import { EmailVerification } from "@src/pages/auth",
}
```
route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
component: import { Login } from "@src/pages/auth"
}
route SignupRoute { path: "/signup", to: SignupPage }
page SignupPage {
component: import { Signup } from "@src/pages/auth"
}
route RequestPasswordResetRoute { path: "/request-password-reset", to: RequestPasswordResetPage }
page RequestPasswordResetPage {
component: import { RequestPasswordReset } from "@src/pages/auth",
}
route PasswordResetRoute { path: "/password-reset", to: PasswordResetPage }
page PasswordResetPage {
component: import { PasswordReset } from "@src/pages/auth",
}
route EmailVerificationRoute { path: "/email-verification", to: EmailVerificationPage }
page EmailVerificationPage {
component: import { EmailVerification } from "@src/pages/auth",
}
```
We'll define the React components for these pages in the src/pages/auth.{jsx,tsx} file below.
Let's create a auth.{jsx,tsx} file in the src/pages folder and add the following to it:
export function Login() {
return (
<Layout>
<LoginForm />
<span className="text-sm font-medium text-gray-900">
Don't have an account yet? <Link to="/signup">go to signup</Link>.
</span>
<span className="text-sm font-medium text-gray-900">
Forgot your password? <Link to="/request-password-reset">reset it</Link>.
</span>
</Layout>
)
}
export function Signup() {
return (
<Layout>
<SignupForm />
<span className="text-sm font-medium text-gray-900">
I already have an account (<Link to="/login">go to login</Link>).
</span>
</Layout>
)
}
export function EmailVerification() {
return (
<Layout>
<VerifyEmailForm />
<span className="text-sm font-medium text-gray-900">
If everything is okay, <Link to="/login">go to login</Link>
</span>
</Layout>
)
}
export function RequestPasswordReset() {
return (
<Layout>
<ForgotPasswordForm />
</Layout>
)
}
export function PasswordReset() {
return (
<Layout>
<ResetPasswordForm />
<span className="text-sm font-medium text-gray-900">
If everything is okay, <Link to="/login">go to login</Link>
</span>
</Layout>
)
}
// A layout component to center the content
export function Layout({ children }) {
return (
<div className="h-full w-full bg-white">
<div className="flex min-h-[75vh] min-w-full items-center justify-center">
<div className="h-full w-full max-w-sm bg-white p-5">
<div>{children}</div>
</div>
</div>
</div>
)
}
```
export function Login() {
return (
<Layout>
<LoginForm />
<span className="text-sm font-medium text-gray-900">
Don't have an account yet? <Link to="/signup">go to signup</Link>.
</span>
<span className="text-sm font-medium text-gray-900">
Forgot your password? <Link to="/request-password-reset">reset it</Link>.
</span>
</Layout>
)
}
export function Signup() {
return (
<Layout>
<SignupForm />
<span className="text-sm font-medium text-gray-900">
I already have an account (<Link to="/login">go to login</Link>).
</span>
</Layout>
)
}
export function EmailVerification() {
return (
<Layout>
<VerifyEmailForm />
<span className="text-sm font-medium text-gray-900">
If everything is okay, <Link to="/login">go to login</Link>
</span>
</Layout>
)
}
export function RequestPasswordReset() {
return (
<Layout>
<ForgotPasswordForm />
</Layout>
)
}
export function PasswordReset() {
return (
<Layout>
<ResetPasswordForm />
<span className="text-sm font-medium text-gray-900">
If everything is okay, <Link to="/login">go to login</Link>
</span>
</Layout>
)
}
// A layout component to center the content
export function Layout({ children }: { children: React.ReactNode }) {
return (
<div className="h-full w-full bg-white">
<div className="flex min-h-[75vh] min-w-full items-center justify-center">
<div className="h-full w-full max-w-sm bg-white p-5">
<div>{children}</div>
</div>
</div>
</div>
)
}
```
We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components here.
To support e-mail verification and password reset flows, we need an e-mail sender. Luckily, Wasp supports several email providers out of the box.
We'll use the Dummy provider to speed up the setup. It just logs the emails to the console instead of sending them. You can use any of the supported email providers.
To set up the Dummy provider to send emails, add the following to the main.wasp file:
That's it! We have set up email authentication in our app. 🎉
Running wasp db migrate-dev and then wasp start should give you a working app with email authentication. If you want to put some of the pages behind authentication, read the auth overview.
Some of the behavior you get out of the box:
We are limiting the rate of sign-up requests to 1 request per minute per email address. This is done to prevent spamming.
If somebody tries to signup with an email that already exists and it's verified, we pretend that the account was created instead of saying it's an existing account. This is done to prevent leaking the user's email address.
If a user tries to register with an existing but unverified email, we'll allow them to do that. This is done to prevent bad actors from locking out other users from registering with their email address.
Read more about the default password validation rules and how to override them in auth overview docs.
:::info Automatic email verification in development
In development mode, you can skip the email verification step by setting the SKIP_EMAIL_VERIFICATION_IN_DEV environment variable to true in your .env.server file:
SKIP_EMAIL_VERIFICATION_IN_DEV=true
This is useful when you are developing your app and don't want to go through the email verification flow every time you sign up. It can be also useful when you are writing automated tests for your app. :::
By default, Wasp requires the e-mail to be verified before allowing the user to log in. This is done by sending a verification email to the user's email address and requiring the user to click on a link in the email to verify their email address.
Our setup looks like this:
<Tabs groupId="js-ts"> <TabItem value="js" label="JavaScript"> ```wasp title="main.wasp" // ...emailVerification: {
clientRoute: EmailVerificationRoute,
}
```
emailVerification: {
clientRoute: EmailVerificationRoute,
}
```
When the user receives an e-mail, they receive a link that goes to the client route specified in the clientRoute field. In our case, this is the EmailVerificationRoute route we defined in the main.wasp file.
The content of the e-mail can be customized, read more about it here.
We defined our email verification page in the auth.{jsx,tsx} file.
Users can request a password and then they'll receive an e-mail with a link to reset their password.
Some of the behavior you get out of the box:
We are limiting the rate of sign-up requests to 1 request per minute per email address. This is done to prevent spamming.
If somebody requests a password reset with an unknown email address, we'll give back the same response as if the user requested a password reset successfully. This is done to prevent leaking information.
Our setup in main.wasp looks like this:
passwordReset: {
clientRoute: PasswordResetRoute,
}
```
passwordReset: {
clientRoute: PasswordResetRoute,
}
```
Users request their password to be reset by going to the /request-password-reset route. We defined our request password reset page in the auth.{jsx,tsx} file.
When the user receives an e-mail, they receive a link that goes to the client route specified in the clientRoute field. In our case, this is the PasswordResetRoute route we defined in the main.wasp file.
Users can enter their new password there.
The content of the e-mail can be customized, read more about it here.
ensurePasswordIsPresent(args)
Checks if the password is present and throws an error if it's not.
ensureValidPassword(args)
Checks if the password is valid and throws an error if it's not. Read more about the validation rules here.
To read more about how to set up the logout button and how to get access to the logged-in user in our client and server code, read the auth overview docs.
When you receive the user object on the client or the server, you'll be able to access the user's email and other information like this:
Let's go over the options we can specify when using email authentication.
userEntity fields auth: {
userEntity: User,
methods: {
email: {
// We'll explain these options below
},
},
onAuthFailedRedirectTo: "/someRoute"
},
// ...
}
```
```prisma title="schema.prisma"
model User {
id Int @id @default(autoincrement())
}
```
auth: {
userEntity: User,
methods: {
email: {
// We'll explain these options below
},
},
onAuthFailedRedirectTo: "/someRoute"
},
// ...
}
```
```prisma title="schema.prisma"
model User {
id Int @id @default(autoincrement())
}
```
email dict auth: {
userEntity: User,
methods: {
email: {
userSignupFields: import { userSignupFields } from "@src/auth",
fromField: {
name: "My App",
email: "[email protected]"
},
emailVerification: {
clientRoute: EmailVerificationRoute,
getEmailContentFn: import { getVerificationEmailContent } from "@src/auth/email",
},
passwordReset: {
clientRoute: PasswordResetRoute,
getEmailContentFn: import { getPasswordResetEmailContent } from "@src/auth/email",
},
},
},
onAuthFailedRedirectTo: "/someRoute"
},
// ...
}
```
auth: {
userEntity: User,
methods: {
email: {
userSignupFields: import { userSignupFields } from "@src/auth",
fromField: {
name: "My App",
email: "[email protected]"
},
emailVerification: {
clientRoute: EmailVerificationRoute,
getEmailContentFn: import { getVerificationEmailContent } from "@src/auth/email",
},
passwordReset: {
clientRoute: PasswordResetRoute,
getEmailContentFn: import { getPasswordResetEmailContent } from "@src/auth/email",
},
},
},
onAuthFailedRedirectTo: "/someRoute"
},
// ...
}
```
userSignupFields: ExtImportRead more about the userSignupFields function here.
fromField: EmailFromField <Required />fromField is a dict that specifies the name and e-mail address of the sender of the e-mails sent by your app.
It has the following fields:
name: name of the senderemail: e-mail address of the sender <Required />emailVerification: EmailVerificationConfig <Required />emailVerification is a dict that specifies the details of the e-mail verification process.
It has the following fields:
clientRoute: Route: a route that is used for the user to verify their e-mail address. <Required />
Client route should handle the process of taking a token from the URL and sending it to the server to verify the e-mail address. You can use our verifyEmail action for that.
:::note We used Auth UI above to avoid doing this work of sending the token to the server manually. :::
getEmailContentFn: ExtImport: a function that returns the content of the e-mail that is sent to the user.
Defining getEmailContentFn can be done by defining a file in the src directory.
export const getVerificationEmailContent: GetVerificationEmailContentFn = ({
verificationLink,
}) => ({
subject: 'Verify your email',
text: `Click the link below to verify your email: ${verificationLink}`,
html: `
<p>Click the link below to verify your email</p>
<a href="${verificationLink}">Verify email</a>
`,
})
```
<small>This is the default content of the e-mail, you can customize it to your liking.</small>
passwordReset: PasswordResetConfig <Required />passwordReset is a dict that specifies the password reset process.
It has the following fields:
clientRoute: Route: a route that is used for the user to reset their password. <Required />
Client route should handle the process of taking a token from the URL and a new password from the user and sending it to the server. You can use our requestPasswordReset and resetPassword actions to do that.
```js title="src/pages/PasswordResetPage.jsx"
import { resetPassword } from 'wasp/client/auth'
...
await resetPassword({ password, token })
```
```ts title="src/pages/PasswordResetPage.tsx"
import { resetPassword } from 'wasp/client/auth'
...
await resetPassword({ password, token })
```
:::note We used Auth UI above to avoid doing this work of sending the password request and the new password to the server manually. :::
getEmailContentFn: ExtImport: a function that returns the content of the e-mail that is sent to the user.
Defining getEmailContentFn is done by defining a function that looks like this:
export const getPasswordResetEmailContent: GetPasswordResetEmailContentFn = ({
passwordResetLink,
}) => ({
subject: 'Password reset',
text: `Click the link below to reset your password: ${passwordResetLink}`,
html: `
<p>Click the link below to reset your password</p>
<a href="${passwordResetLink}">Reset password</a>
`,
})
```
<small>This is the default content of the e-mail, you can customize it to your liking.</small>