From 84119b0429f0f23955dd6b5e70b6bcec49b6a62f Mon Sep 17 00:00:00 2001 From: Kang Ming Date: Thu, 15 Dec 2022 21:50:30 -0800 Subject: [PATCH] fix: update going-to-prod docs & add email template guide (#10992) * update redirectTo description in resetPasswordForEmail * update redirectTo description across v1 & v2 * add rate limit info * add email templating guide * Update apps/docs/pages/guides/platform/going-into-prod.mdx Co-authored-by: Stojan Dimitrovski * update email template guide * Update apps/docs/pages/guides/auth/auth-email-templates.mdx Co-authored-by: dng * Update apps/docs/pages/guides/auth/auth-email-templates.mdx Co-authored-by: dng * Update apps/docs/pages/guides/auth/auth-email-templates.mdx Co-authored-by: dng * Update apps/docs/pages/guides/auth/auth-email-templates.mdx Co-authored-by: dng * Update apps/docs/pages/guides/auth/auth-email-templates.mdx Co-authored-by: dng * Update spec/supabase_js_v1.yml Co-authored-by: dng * Update spec/supabase_js_v1.yml Co-authored-by: dng * Update spec/supabase_js_v2.yml Co-authored-by: dng * Update spec/supabase_js_v2.yml Co-authored-by: dng * Update spec/supabase_js_v2.yml Co-authored-by: dng Co-authored-by: Stojan Dimitrovski Co-authored-by: dng --- .../NavigationMenu.constants.ts | 1 + .../guides/auth/auth-email-templates.mdx | 50 +++++++++++++++++++ .../pages/guides/platform/going-into-prod.mdx | 21 ++++++++ spec/supabase_js_v1.yml | 16 ++++-- spec/supabase_js_v2.yml | 11 ++-- 5 files changed, 90 insertions(+), 9 deletions(-) create mode 100644 apps/docs/pages/guides/auth/auth-email-templates.mdx diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index de9d0348065..c5f57524b8f 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -298,6 +298,7 @@ export const auth = { url: '/guides/auth/social-login', items: [...SocialLoginItems], }, + { name: 'Email Templates', url: '/guides/auth/auth-email-templates', items: [] }, ], }, { diff --git a/apps/docs/pages/guides/auth/auth-email-templates.mdx b/apps/docs/pages/guides/auth/auth-email-templates.mdx new file mode 100644 index 00000000000..a82c244000b --- /dev/null +++ b/apps/docs/pages/guides/auth/auth-email-templates.mdx @@ -0,0 +1,50 @@ +import Layout from '~/layouts/DefaultGuideLayout' + +export const meta = { + title: 'Email Templates', + description: 'Learn how to configure the email templates on Supabase.', +} + +You can customize the email messages used for the authentication flows. You can edit the following email templates: + +- Confirm signup +- Invite user +- Magic Link +- Change Email Address +- Reset Password + +## Terminology + +The templating system provides the following variables for use: + +| Name | Description | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `{{ .ConfirmationURL }}` | Contains the confirmation URL. For example, a signup confirmation URL would look like: `https://project-ref.supabase.co/auth/v1/verify?token={{ .TokenHash }}&type=signup&redirect_to=https://example.com/path` . | +| `{{ .Token }}` | Contains a 6-digit One-Time-Password (OTP) that can be used instead of the `{{. ConfirmationURL }}` . | +| `{{ .TokenHash }}` | Contains a hashed version of the `{{ .Token }}`. This is useful for constructing your own email link in the email template. | +| `{{ .SiteURL }}` | Contains your application's Site URL. This can be configured in your project's [authentication settings](https://app.supabase.com/project/_/auth/url-configuration). | + +## Limitations + +### Email Prefetching + +Certain email providers may have spam detection or other security features that prefetch URL links from incoming emails. +In this scenario, the `{{ .ConfirmationURL }}` sent will be consumed instantly which leads to a "Token has expired or is invalid" error. +To guard against this: + +- Use an email OTP instead by including `{{ .Token }}` in the email template. +- Create your own custom email link to redirect the user to a page where they can click on a button to confirm the action. + For example, you can include the following in your email template: + + ```html + Confirm your signup + + ``` + + The user should be brought to a page on your site where they can confirm the action by clicking a button. + The button should contain the actual confirmation link which can be obtained from parsing the `confirmation_url={{ .ConfirmationURL }}` query parameter in the URL. + +export const Page = ({ children }) => + +export default Page diff --git a/apps/docs/pages/guides/platform/going-into-prod.mdx b/apps/docs/pages/guides/platform/going-into-prod.mdx index cfb579ce518..73c25d0a1c5 100644 --- a/apps/docs/pages/guides/platform/going-into-prod.mdx +++ b/apps/docs/pages/guides/platform/going-into-prod.mdx @@ -54,10 +54,31 @@ After developing your project and deciding it's Production Ready, you should run - Supabase employs a number of safeguards against bursts of incoming traffic to prevent abuse and help maximize stability across the platform - If you're expecting high load events including production launches or heavy load testing, or prolonged high resource usage please give us at least 2 weeks notice. You can do this by opening a ticket via the [support form](https://app.supabase.com/support/new). +### Rate Limits + +- The table below shows the rate limit quotas on the following authentication endpoints: + +| Endpoint | Path | Limited By | Rate Limit | +| ------------------------------------------------ | -------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------- | +| All endpoints that send emails | `/auth/v1/signup` `/auth/v1/recover` `/auth/v1/user`[^1] | Sum of combined requests | Defaults to 30 emails per hour. Is customizable with custom SMTP set up. | +| All endpoints that send One-Time-Passwords (OTP) | `/auth/v1/otp` | Sum of combined requests | Defaults to 30 OTPs per hour. Is customizable. | +| Send OTPs or magiclinks | `/auth/v1/otp` | Last request | Defaults to 60 seconds window before a new request is allowed. Is customizable. | +| Signup confirmation request | `/auth/v1/signup` | Last request | Defaults to 60 seconds window before a new request is allowed. Is customizable. | +| Password Reset Request | `/auth/v1/recover` | Last request | Defaults to 60 seconds window before a new request is allowed. Is customizable. | +| Verification requests | `/auth/v1/verify` | IP Address | 360 requests per hour (with bursts up to 30 requests) | +| Token refresh requests | `/auth/v1/token` | IP Address | 360 requests per hour (with bursts up to 30 requests) | +| Create or Verify an MFA challenge | `/auth/v1/factors/:id/challenge` `/auth/v1/factors/:id/verify` | IP Address | 15 requests per minute (with bursts up to 30 requests) | + +### Abuse Prevention + +- Supabase provides CAPTCHA protection on the signup, sign-in and password reset endpoints. Please refer to [our guide](/docs/guides/auth/auth-captcha) on how to protect against abuse using this method. + ## Next steps This checklist is always growing so be sure to check back frequently, and also feel free to suggest additions and amendments by making a PR on [GitHub](https://github.com/supabase/supabase). +[^1]: The rate limit is only applied on `/auth/v1/user` if this endpoint is called to update the user's email address. + export const Page = ({ children }) => export default Page diff --git a/spec/supabase_js_v1.yml b/spec/supabase_js_v1.yml index c61976c9743..81b1d4ddb18 100644 --- a/spec/supabase_js_v1.yml +++ b/spec/supabase_js_v1.yml @@ -134,7 +134,9 @@ functions: the Auth server. If you are using email/phone logins you should set up your own redirects (within the email/sms template). Sometimes you want to control where the user is redirected to after they are logged in. Supabase supports this for - any URL path on your website (the URL must either be on the same domain as your Site URL [see Auth>Settings in dashboard], or must match one of the Additional Redirect URLs [also in Auth>Settings]). + any URL path on your website (the URL must either be on the same domain as your [Site URL](https://app.supabase.com/project/_/auth/url-configuration) or match one of the Redirect URLs). + + See [redirect URLs and wildcards](/docs/guides/auth/overview#redirect-urls-and-wildcards) to add additional redirect URLs to your project. code: | ```js const { user, session, error } = await supabase.auth.signIn({ @@ -502,8 +504,10 @@ functions: $ref: '@supabase/gotrue-js.GoTrueApi.resetPasswordForEmail' notes: | Sends a password reset request to an email address. - When the user clicks the reset link in the email they are redirected back to your application. - Prompt the user for a new password and call `auth.update()`: + - When the user clicks the reset link in the email they are redirected back to your application. + You can configure the URL that the user is redirected to via the `redirectTo` param. + See [redirect URLs and wildcards](/docs/guides/auth/overview#redirect-urls-and-wildcards) to add additional redirect URLs to your project. + - After the user has been redirected successfully, prompt them for a new password and call `updateUser()`: ```js const { data, error } = await supabase.auth.update({ password: new_password, @@ -516,7 +520,8 @@ functions: code: | ```js const { data, error } = await supabase.auth.api.resetPasswordForEmail( - 'user@email.com' + email, + { redirectTo: 'https://example.com/update-password' } ) ``` - id: reset-password-react @@ -529,7 +534,8 @@ functions: * This email contains a link which sends the user back to your application. */ const { data, error } = await supabase.auth.api.resetPasswordForEmail( - 'user@email.com' + email, + { redirectTo: 'https://example.com/update-password' } ) /** diff --git a/spec/supabase_js_v2.yml b/spec/supabase_js_v2.yml index ab735f6de09..685f250ff91 100644 --- a/spec/supabase_js_v2.yml +++ b/spec/supabase_js_v2.yml @@ -215,7 +215,8 @@ functions: - If the user doesn't exist, `signInWithOtp()` will signup the user instead. To restrict this behaviour, you can set `shouldCreateUser` in `SignInWithPasswordlessCredentials.options` to `false`. - If you're using an email, you can configure whether you want the user to receive a magiclink or a OTP. - If you're using phone, you can configure whether you want the user to receive a OTP. - - The magic link's destination URL is determined by the [`SITE_URL`](https://supabase.com/docs/reference/auth/config#site_url). You can modify the `SITE_URL` or add additional redirect urls in [your project](https://app.supabase.com/project/_/auth/settings). + - The magic link's destination URL is determined by the [`SITE_URL`](/docs/reference/auth/config#site_url). + - See [redirect URLs and wildcards](/docs/guides/auth/overview#redirect-urls-and-wildcards) to add additional redirect URLs to your project. examples: - id: sign-in-with-email name: Sign in with email @@ -260,8 +261,8 @@ functions: name: Sign in using a third-party provider with redirect isSpotlight: false description: | - When the third-party provider successfully authenticates the user, the provider will redirect the user to the URL specified in the `redirectTo` parameter. This parameter defaults to the [`SITE_URL`](https://supabase.com/docs/reference/auth/config#site_url). It does not redirect the user immediately after invoking this method. - You can modify the `SITE_URL` or add additional redirect urls in [your project](https://app.supabase.com/project/_/auth/settings). + - When the third-party provider successfully authenticates the user, the provider redirects the user to the URL specified in the `redirectTo` parameter. This parameter defaults to the [`SITE_URL`](/docs/reference/auth/config#site_url). It does not redirect the user immediately after invoking this method. + - See [redirect URLs and wildcards](/docs/guides/auth/overview#redirect-urls-and-wildcards) to add additional redirect URLs to your project. code: | ```js const { data, error } = await supabase.auth.signInWithOAuth({ @@ -734,7 +735,9 @@ functions: - A `SIGNED_IN` and `PASSWORD_RECOVERY` event will be emitted when the password recovery link is clicked. You can use [`onAuthStateChange()`](/docs/reference/javascript/auth-onauthstatechange) to listen and invoke a callback function on these events. - When the user clicks the reset link in the email they are redirected back to your application. - Prompt the user for a new password and call `updateUser()`: + You can configure the URL that the user is redirected to with the `redirectTo` parameter. + See [redirect URLs and wildcards](/docs/guides/auth/overview#redirect-urls-and-wildcards) to add additional redirect URLs to your project. + - After the user has been redirected successfully, prompt them for a new password and call `updateUser()`: ```js const { data, error } = await supabase.auth.updateUser({ password: new_password