From d22e9c4e6f2c80afb9b87eac4f31c7caa2b11038 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thor=20=E9=9B=B7=E7=A5=9E=20Schaeff?= <5748289+thorwebdev@users.noreply.github.com> Date: Tue, 14 Nov 2023 12:46:30 +0800 Subject: [PATCH] docs: passwordless auth docs improvements. (#18872) * docs: passwordless auth docs improvements. * fix: typo. * Update apps/docs/pages/guides/auth/passwordless-login/auth-email-otp.mdx Co-authored-by: Charis <26616127+charislam@users.noreply.github.com> * Update apps/docs/pages/guides/auth/passwordless-login/auth-email-otp.mdx Co-authored-by: Charis <26616127+charislam@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Charis <26616127+charislam@users.noreply.github.com> --------- Co-authored-by: Tyler <18113850+dshukertjr@users.noreply.github.com> Co-authored-by: Charis <26616127+charislam@users.noreply.github.com> --- .../NavigationMenu.constants.ts | 10 +- .../pages/guides/auth/passwordless-login.mdx | 57 ++++++++ .../passwordless-login/auth-email-otp.mdx | 123 ++++++++++++++++++ .../auth-magic-link.mdx | 0 apps/www/lib/redirects.js | 5 + 5 files changed, 194 insertions(+), 1 deletion(-) create mode 100644 apps/docs/pages/guides/auth/passwordless-login.mdx create mode 100644 apps/docs/pages/guides/auth/passwordless-login/auth-email-otp.mdx rename apps/docs/pages/guides/auth/{ => passwordless-login}/auth-magic-link.mdx (100%) diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index e582635c20c..7feae10868d 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -497,7 +497,15 @@ export const auth = { url: undefined, items: [ { name: 'Email Login', url: '/guides/auth/auth-email' }, - { name: 'Magic Link Login', url: '/guides/auth/auth-magic-link' }, + { + name: 'Passwordless Login', + url: '/guides/auth/passwordless-login', + items: [ + { name: 'Email Magic Link', url: '/guides/auth/passwordless-login/auth-magic-link' }, + { name: 'Email OTP', url: '/guides/auth/passwordless-login/auth-email-otp' }, + { name: 'Phone OTP', url: '/guides/auth/phone-login' }, + ], + }, { name: 'Phone Login', url: '/guides/auth/phone-login', diff --git a/apps/docs/pages/guides/auth/passwordless-login.mdx b/apps/docs/pages/guides/auth/passwordless-login.mdx new file mode 100644 index 00000000000..cd8a76cd7f6 --- /dev/null +++ b/apps/docs/pages/guides/auth/passwordless-login.mdx @@ -0,0 +1,57 @@ +import Layout from '~/layouts/DefaultGuideLayout' +import { IconPanel, GlassPanel, IconMail } from 'ui' +import Link from 'next/link' +import { PhoneLoginsItems } from '~/components/Navigation/NavigationMenu/NavigationMenu.constants' + +export const meta = { + title: 'Passwordless Login', + description: 'Sign in your users without passwords via magic link email, or one-time passwords sent via email, SMS, or WhatsApp.', +} + +Supabase supports various forms of passwordless authentication: + +- [Email Magic Link](/docs/guides/auth/passwordless-login/auth-magic-link) +- [Email one-time password (OTP)](/docs/guides/auth/passwordless-login/auth-email-otp) +- [SMS & WhatsApp one-time password (OTP)](/docs/guides/auth/phone-login) + +## Benefits + +There are several reasons why you might want to add passwordless login to your applications: + +- **Improved user experience**: Eliminating the need for users to remember and enter complex passwords can make it easier and more convenient for users to log in to your application. This can improve the overall user experience and make it more enjoyable for users to interact with your application. + +- **Increased security**: Passwordless login can improve the security of your application by reducing the risk of password-related security breaches, such as password reuse and weak passwords. By using alternative forms of authentication, such as one-time codes or biometric factors, you can make it more difficult for unauthorized users to access your application. + +- **Reduced support burden**: Passwordless login can also help reduce the support burden for your team by eliminating the need to handle password recovery flows or deal with other password-related issues. This can free up your team to focus on other important tasks and improve the efficiency of your operation. + +## Passwordless login options with Supabase Auth + +### Email based + +- [Email Magic Link](/docs/guides/auth/passwordless-login/auth-magic-link) +- [Email one-time password (OTP)](/docs/guides/auth/passwordless-login/auth-email-otp) + +## Phone based + +Supabase supports [Phone Login](/docs/guides/auth/phone-login) (SMS & WhatsApp) with several communications platforms. Follow the guides below to set up a provider with Supabase Auth. + +
+ {PhoneLoginsItems.map((item) => ( + + + {item.linkDescription} + + +))} + +
+ +export const Page = ({ children }) => + +export default Page diff --git a/apps/docs/pages/guides/auth/passwordless-login/auth-email-otp.mdx b/apps/docs/pages/guides/auth/passwordless-login/auth-email-otp.mdx new file mode 100644 index 00000000000..68afb7ef4d0 --- /dev/null +++ b/apps/docs/pages/guides/auth/passwordless-login/auth-email-otp.mdx @@ -0,0 +1,123 @@ +import Layout from '~/layouts/DefaultGuideLayout' + +export const meta = { + id: 'auth-email-otp', + title: 'Login With Email OTP', + description: 'Use Supabase to authenticate your users using one-time password emails.', +} + +Email one-time passwords (OTP) are a form of passwordless login where users key in a six digit code sent to their email address to log in to their accounts. By default, a user can only request an OTP once every 60 seconds and they expire after 24 hours. + +## Setting up Email OTP + +To set up email OTP for your Supabase app: + +- Enable the email provider in your [Supabase Project](/dashboard/project/_/auth/providers) +- The Site URL represents the default URL that the user will be redirected to after clicking on the email signup confirmation link. +- If a user has not signed up yet, signing in with an OTP will automatically sign up the user. To prevent users from signing up this way, you can set the `shouldCreateUser` option to `false`. +- Navigate to the [email template settings](/dashboard/project/_/auth/templates) and modify the template to include the `{{ .Token }}` variable, for example: + +```html +

One time login code

+ +

Please enter this code: {{ .Token }}

+``` + +## Signing in a user with email OTP + + + +When your user signs in, call [signInWithOtp()](/docs/reference/javascript/auth-signinwithotp) with their email address: + +```js +const { data, error } = await supabase.auth.signInWithOtp({ + email: 'example@email.com', + options: { + // set this to false if you do not want the user to be automatically signed up + shouldCreateUser: false, + }, +}) +``` + + + + +When your user signs in, call [signInWithOtp()](/docs/reference/dart/auth-signinwithotp) with their email address: + +```dart +Future signInWithEmailOtp() async { + final AuthResponse res = await supabase.auth.signInWithOtp(email: 'example@email.com'); +} +``` + + + + +When your user signs in, call [sendOtpTo()](/docs/reference/kotlin/auth-signinwithotp) with their email address: + +```kotlin +suspend fun signInWithEmailOtp() { + supabase.gotrue.sendOtpTo(Email) { + email = "example@email.com" + } +} +``` + + + + +If the request was successful, you receive a response with `error: null` and a `data` object where both `user` and `session` are null. In this case you can let the user know to check their email inbox. + +```json +{ + "data": { + "user": null, + "session": null + }, + "error": null +} +``` + +## Verify OTP to create session + +Provide an input field for the user to key in the one-time code. To verify the code and complete the user's sign in, call [verifyOtp()](/docs/reference/javascript/auth-verifyotp) with their email address, the code, and `type: "email"`: + +```js +const { + data: { session }, + error, +} = await supabase.auth.verifyOtp({ + email, + token: '123456', + type: 'email', +}) +``` + +If successful the user will now be logged in and you should receive a valid session like: + +```json +{ + "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJhdXRoZW50aWNhdGVkIiwiZXhwIjoxNjI3MjkxNTc3LCJzdWIiOiJmYTA2NTQ1Zi1kYmI1LTQxY2EtYjk1NC1kOGUyOTg4YzcxOTEiLCJlbWFpbCI6IiIsInBob25lIjoiNjU4NzUyMjAyOSIsImFwcF9tZXRhZGF0YSI6eyJwcm92aWRlciI6InBob25lIn0sInVzZXJfbWV0YWRhdGEiOnt9LCJyb2xlIjoiYXV0aGVudGljYXRlZCJ9.1BqRi0NbS_yr1f6hnr4q3s1ylMR3c1vkiJ4e_N55dhM", + "token_type": "bearer", + "expires_in": 3600, + "refresh_token": "LSp8LglPPvf0DxGMSj-vaQ", + "user": {...} +} +``` + +## Resources + +- [Supabase Account - Free Plan OK](https://supabase.com) +- [Phone SMS & WhatsApp OTP](/docs/guides/auth/phone-login) +- [Supabase JS Client](https://github.com/supabase/supabase-js) +- [Supabase Flutter Client](https://github.com/supabase/supabase-flutter) + +export const Page = ({ children }) => + +export default Page diff --git a/apps/docs/pages/guides/auth/auth-magic-link.mdx b/apps/docs/pages/guides/auth/passwordless-login/auth-magic-link.mdx similarity index 100% rename from apps/docs/pages/guides/auth/auth-magic-link.mdx rename to apps/docs/pages/guides/auth/passwordless-login/auth-magic-link.mdx diff --git a/apps/www/lib/redirects.js b/apps/www/lib/redirects.js index 9daf63e354f..f956e6ffa57 100644 --- a/apps/www/lib/redirects.js +++ b/apps/www/lib/redirects.js @@ -2338,4 +2338,9 @@ module.exports = [ source: '/docs/guides/functions/troubleshooting', destination: '/docs/guides/functions/debugging', }, + { + permanent: true, + source: '/docs/guides/auth/auth-magic-link', + destination: '/docs/guides/auth/passwordless-login/auth-magic-link', + }, ]