Merge pull request #14111 from supabase/chore/auth-password-reset

Add password reset guide to the auth section

apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts

@@ -437,6 +437,7 @@ export const auth = {
             },
           ],
         },
+        { name: 'Password Reset', url: '/guides/auth/auth-password-reset' },
         { name: 'Email Templates', url: '/guides/auth/auth-email-templates' },
       ],
     },

apps/docs/pages/guides/auth/auth-password-reset.mdx

@@ -0,0 +1,109 @@
+import Layout from '~/layouts/DefaultGuideLayout'
+import { Accordion } from 'ui'
+
+export const meta = {
+  id: 'auth-password-reset',
+  title: 'Password Reset',
+  description: 'How to reset password with Supabase Auth',
+}
+
+- Send email for password reset using [`.resetPasswordForEmail`](/docs/reference/javascript/auth-resetpasswordforemail) while providing a `redirectTo` parameter
+- Email link will work as a magic link and log the user in then take them to the url specified in the `redirectTo` parameter
+- Create form to update the password and call the [`.updateUser`](/docs/reference/javascript/auth-updateuser) method with the new password
+
+## Single Page Application (SPA)
+
+### Sending password reset email
+Supabase provides a convenient method [`.resetPasswordForEmail`](/docs/reference/javascript/auth-resetpasswordforemail) 
+to reset a user password. This method takes a parameter of `redirectTo` which we will use to pass an absolute URL to 
+the update password page. This URL must be saved in your 
+allowed [Redirect URLs](https://app.supabase.com/project/_/auth/url-configuration) list found at 
+[Authentication > Redirect Configuration](https://app.supabase.com/project/_/auth/url-configuration) or it won't 
+redirect the user.
+
+```ts
+await supabase.auth.resetPasswordForEmail('hello@example.com', {
+  redirectTo: 'http://example.com/account/update-password',
+})
+```
+
+### Email link
+The email link you receive will work like a magic link. This way when you click the link you will be logged into 
+the website. Since we passed a redirect URL to the [`.resetPasswordForEmail`](https://supabase.com/docs/reference/javascript/auth-resetpasswordforemail) 
+method the user should be sent to the update password page.
+
+### Update Password
+To update the password we call the [`.updateUser`](/docs/reference/javascript/auth-updateuser) method and pass along the new password to this method.
+
+```ts
+await supabase.auth.updateUser({ password: new_password })
+```
+
+## Server-Side Rendering (SSR)
+
+### Sending password reset email
+Supabase provides a convenient method [`.resetPasswordForEmail`](/docs/reference/javascript/auth-resetpasswordforemail) 
+to reset a user password. This method takes a parameter of `redirectTo` which we will use to pass an absolute URL to 
+the callback page along with a query parameter to the update password page. This URL must be saved in your 
+allowed [Redirect URLs](https://app.supabase.com/project/_/auth/url-configuration) list found at 
+[Authentication > Redirect Configuration](https://app.supabase.com/project/_/auth/url-configuration) or it won't 
+redirect the user.
+
+```ts
+await supabase.auth.resetPasswordForEmail('hello@example.com', {
+  redirectTo: 'http://example.com/api/auth/callback?next=/account/update-password',
+})
+```
+
+<Admonition type="note">
+
+We are using `next` as our query parameter, but this can name whatever you like.
+
+</Admonition>
+
+### Email link
+The email link you receive will behave like a magic link. When the link is clicked you will be sent to the `redirectTo` URL you specified that points to the path with the exchange code.
+
+### Exchange authorization code
+After redirecting to the server page, we need to retrieve the code from the query parameter called `code` and pass it to the `.exchangeAuthCodeForSession` function.
+```ts
+// api/auth/callback.ts
+
+// The code is retrieved from the query parameter - use whichever mechanism is recommended
+// for your app/framework. This is just an example.
+const code = url.searchParams.get('code')
+
+// call the Supabase API to exchange the code for a session
+await supabase.auth.exchangeCodeForSession(code)
+```
+
+<Admonition type="note">
+
+The query parameter is always `code` for the authorization code returned from the Supabase API
+
+</Admonition>
+
+We will also need to check for the `next` query parameter to redirect the user to the update password page.
+```ts
+// api/auth/callback.ts
+
+// The password page path is retrieved from the query parameter - use whichever mechanism is recommended
+// for your app/framework. This is just an example.
+const next = url.searchParams.get('next')
+
+// using NextJS API response object in this example
+res.redirect(next)
+```
+
+### Update Password
+To update the password we call the [`.updateUser`](/docs/reference/javascript/auth-updateuser) method and 
+pass along the new password to this method.
+
+```ts
+await supabase.auth.updateUser({ password: new_password })
+```
+
+export const Page = ({ children }) => <Layout meta={meta} children={children} />
+
+export default Page
+