From bc43268b1df1159015d974db28afdbcac016c844 Mon Sep 17 00:00:00 2001 From: Jordi Enric Date: Mon, 3 Jun 2024 12:49:17 +0200 Subject: [PATCH] Revert "docs: update auth docs" This reverts commit 39bb6c24a923af9ce5cf8d6d8b4842aa1d60c541. --- .../MessageBirdConfig.mdx | 6 - apps/docs/components/MDX/auth_rate_limits.mdx | 22 +-- .../guides/auth/phone-login/messagebird.mdx | 69 ++++++++ .../guides/auth/phone-login/textlocal.mdx | 63 ++++++++ .../guides/auth/phone-login/twilio.mdx | 151 ++++++++++++++++++ .../guides/auth/phone-login/vonage.mdx | 66 ++++++++ .../guides/auth/social-login/auth-google.mdx | 2 +- 7 files changed, 361 insertions(+), 18 deletions(-) create mode 100644 apps/docs/content/guides/auth/phone-login/messagebird.mdx create mode 100644 apps/docs/content/guides/auth/phone-login/textlocal.mdx create mode 100644 apps/docs/content/guides/auth/phone-login/twilio.mdx create mode 100644 apps/docs/content/guides/auth/phone-login/vonage.mdx diff --git a/apps/docs/components/AuthSmsProviderConfig/MessageBirdConfig.mdx b/apps/docs/components/AuthSmsProviderConfig/MessageBirdConfig.mdx index 5ab76264c4c..b875124ca4d 100644 --- a/apps/docs/components/AuthSmsProviderConfig/MessageBirdConfig.mdx +++ b/apps/docs/components/AuthSmsProviderConfig/MessageBirdConfig.mdx @@ -1,11 +1,5 @@ import { CostWarning } from './AuthSmsProviderConfig.Warnings' - - -The MessageBird provider only works with the APIs before the [transition to Bird](https://bird.com/blog/messagebird-is-now-bird). If you are using a new Bird account, this provider will not work properly since it relies on using the old set of [MessageBird APIs](https://developers.messagebird.com/api/sms-messaging/). - - - ## Prerequisites You'll need: diff --git a/apps/docs/components/MDX/auth_rate_limits.mdx b/apps/docs/components/MDX/auth_rate_limits.mdx index 132d0420a17..f5ac2fb1490 100644 --- a/apps/docs/components/MDX/auth_rate_limits.mdx +++ b/apps/docs/components/MDX/auth_rate_limits.mdx @@ -1,14 +1,14 @@ -| 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 4 emails per hour as of 14th July 2023. As of 21 Oct 2023, this has been updated to auth.rate_limits.email.inbuilt_smtp_per_hour emails per hour. You can only change this with your own custom SMTP setup. | -| All endpoints that send One-Time-Passwords (OTP) | `/auth/v1/otp` | Sum of combined requests | Defaults to auth.rate_limits.otp.requests_per_hour OTPs per hour. Is customizable. | -| Send OTPs or magiclinks | `/auth/v1/otp` | Last request | Defaults to auth.rate_limits.otp.period window before a new request is allowed. Is customizable. | -| Signup confirmation request | `/auth/v1/signup` | Last request | Defaults to auth.rate_limits.signup_confirmation.period window before a new request is allowed. Is customizable. | -| Password Reset Request | `/auth/v1/recover` | Last request | Defaults to auth.rate_limits.password_reset.period window before a new request is allowed. Is customizable. | -| Verification requests | `/auth/v1/verify` | IP Address | auth.rate_limits.verification.requests_per_hour requests per hour (with bursts up to auth.rate_limits.verification.requests_burst requests) | -| Token refresh requests | `/auth/v1/token` | IP Address | auth.rate_limits.token_refresh.requests_per_hour requests per hour (with bursts up to auth.rate_limits.token_refresh.requests_burst requests) | -| Create or Verify an MFA challenge | `/auth/v1/factors/:id/challenge` `/auth/v1/factors/:id/verify` | IP Address | auth.rate_limits.mfa.requests_per_hour requests per hour (with bursts up to auth.rate_limits.verification.mfa requests) | -| Anonymous sign-ins | `/auth/v1/signup`[^2] | IP Address | auth.rate_limits.anonymous_signin.requests_per_hour requests per hour (with bursts up to auth.rate_limits.anonymous_signin.requests_burst requests) | +| 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. As of 14th July 2023, this has been updated to 4 emails per hour. As of 21 Oct 2023, this has been updated to auth.rate_limits.email.inbuilt_smtp_per_hour emails per hour. You can only change this with your own custom SMTP setup. | +| All endpoints that send One-Time-Passwords (OTP) | `/auth/v1/otp` | Sum of combined requests | Defaults to auth.rate_limits.otp.requests_per_hour OTPs per hour. Is customizable. | +| Send OTPs or magiclinks | `/auth/v1/otp` | Last request | Defaults to auth.rate_limits.otp.period window before a new request is allowed. Is customizable. | +| Signup confirmation request | `/auth/v1/signup` | Last request | Defaults to auth.rate_limits.signup_confirmation.period window before a new request is allowed. Is customizable. | +| Password Reset Request | `/auth/v1/recover` | Last request | Defaults to auth.rate_limits.password_reset.period window before a new request is allowed. Is customizable. | +| Verification requests | `/auth/v1/verify` | IP Address | auth.rate_limits.verification.requests_per_hour requests per hour (with bursts up to auth.rate_limits.verification.requests_burst requests) | +| Token refresh requests | `/auth/v1/token` | IP Address | auth.rate_limits.token_refresh.requests_per_hour requests per hour (with bursts up to auth.rate_limits.token_refresh.requests_burst requests) | +| Create or Verify an MFA challenge | `/auth/v1/factors/:id/challenge` `/auth/v1/factors/:id/verify` | IP Address | auth.rate_limits.mfa.requests_per_hour requests per hour (with bursts up to auth.rate_limits.verification.mfa requests) | +| Anonymous sign-ins | `/auth/v1/signup`[^2] | IP Address | auth.rate_limits.anonymous_signin.requests_per_hour requests per hour (with bursts up to auth.rate_limits.anonymous_signin.requests_burst requests) | [^1]: The rate limit is only applied on `/auth/v1/user` if this endpoint is called to update the user's email address. [^2]: The rate limit is only applied on `/auth/v1/signup` if this endpoint is called without passing in an email or phone number in the request body. diff --git a/apps/docs/content/guides/auth/phone-login/messagebird.mdx b/apps/docs/content/guides/auth/phone-login/messagebird.mdx new file mode 100644 index 00000000000..27d882780ef --- /dev/null +++ b/apps/docs/content/guides/auth/phone-login/messagebird.mdx @@ -0,0 +1,69 @@ +--- +id: 'auth-messagebird' +title: 'Phone Auth with MessageBird' +description: 'How to set up and use Mobile OTP with MessageBird and Supabase.' +--- + + + +Authenticating users via SMS can become expensive. Adjust your project's rate limits and [configure CAPTCHA](/docs/guides/auth/auth-captcha) to control the bill. Read more about this in the [Production Checklist](/docs/guides/platform/going-into-prod). + + + +## Prerequisites + +You'll need: + +- A MessageBird account (sign up [here](https://dashboard.messagebird.com/en/sign-up)) +- A Supabase project (create one [here](https://supabase.com/dashboard)) +- A mobile phone capable of receiving SMS + +## Set up MessageBird as your SMS provider + +Start by logging into your MessageBird account and verify the mobile number you'll be using to test with [here](https://dashboard.messagebird.com/en/getting-started/sms). This is the number that will be receiving the SMS OTPs. + +![Verify your own phone number](/docs/img/guides/auth-messagebird/1.png) + +![Get your API Keys](/docs/img/guides/auth-messagebird/2.png) + +Navigate to the [dashboard settings](https://dashboard.messagebird.com/en/settings/sms) to set the default originator. The messagebird originator is the name or number from which the message is sent. For more information, you can refer to the messagebird article on choosing an originator [here](https://support.messagebird.com/hc/en-us/articles/115002628665-Choosing-an-originator) + +![Set the default originator](/docs/img/guides/auth-messagebird/3.png) + +You will need the following values to get started: + +- Live API Key / Test API Key +- MessageBird originator + +Now go to the [Auth > Providers](https://supabase.com/dashboard/project/_/auth/providers) page in the Supabase dashboard and select "Phone" from the Auth Providers list. + +You should see an option to enable the Phone provider. + +Toggle it on, and copy the 2 values over from the Messagebird dashboard. Click save. + + + +If you use the Test API Key, the OTP will not be delivered to the mobile number specified but messagebird will log the response in the dashboard. If the Live API Key is used instead, the OTP will be delivered and there will be a deduction in your free credits. + + + +Plugin MessageBird credentials + +Now the backend should be setup, we can proceed to add our client-side code! + +#### SMS custom template + +The SMS message sent to a phone containing an OTP code can be customized. This is useful if you need to mention a brand name or display a website address. + +Go to [Auth > Templates](https://supabase.com/dashboard/project/_/auth/templates) page in the Supabase dashboard. + +Use the variable `.Code` in the template to display the code. + +## Next steps + +To implement Phone Login, see the docs on [using Phone Login](/docs/guides/auth/phone-login#using-phone-login). + +## Resources + +- [MessageBird Signup](https://dashboard.messagebird.com/en/sign-up) +- [Supabase Dashboard](https://supabase.com/dashboard) diff --git a/apps/docs/content/guides/auth/phone-login/textlocal.mdx b/apps/docs/content/guides/auth/phone-login/textlocal.mdx new file mode 100644 index 00000000000..9a717bfca17 --- /dev/null +++ b/apps/docs/content/guides/auth/phone-login/textlocal.mdx @@ -0,0 +1,63 @@ +--- +id: 'auth-textlocal' +title: 'Phone Auth with Textlocal' +subtitle: 'How to set up and use Mobile OTP with Textlocal and Supabase.' +description: 'How to set up and use Mobile OTP with Textlocal and Supabase.' +--- + + + +To manage costs related to SMS authentication, consider setting project rate limits and configuring CAPTCHA. For additional cost-control strategies, visit the Production Checklist. + +Also check country-specific regulations around sending SMS messages, for example, India's TRAI DLT +regulations. + + + +## Prerequisites + +Before you begin, ensure you have the following: + +- **A Textlocal account**: Sign up for [TextLocal](https://www.textlocal.com/signup) to start sending SMS messages. +- **A Supabase project**: Necessary for SMS authentication integration. Create your project in the [Supabase Dashboard](https://supabase.com/dashboard). +- **A mobile phone**: To receive SMS messages and test your setup. + +## Setting up Textlocal as your SMS provider + +To integrate Textlocal with Supabase: + +1. [Get a Textlocal API key](#get-a-textlocal-api-key) +2. [Customize your sender name](#customize-your-sender-name-optional) +3. [Configure your Supabase project](#configure-supabase) + +### Get a Textlocal API key + +1. Log into your Textlocal account and go to `Settings` > `API Keys`. +2. Generate a new API Key. Save your new API key in a safe location. + +### Customize your sender name (Optional) + +Textlocal defaults to `TXTLCL` as the sender name for all messages. You can customize this to better reflect your brand: + +1. In your Textlocal dashboard, go to `Settings` > `All Settings` > `Sender Names`. +2. Change your sender name. + +### Configure Supabase + +To set up Textlocal as your SMS provider in Supabase, follow these steps: + +1. In your Supabase Dashboard, go to the [Auth Providers section](https://supabase.com/dashboard/project/_/auth/providers). +2. From the list of available authentication providers, select `Phone`. +3. Toggle `Enable Phone Provider`. +4. Under `SMS Provider`, select `Textlocal.` +5. Enter your Textlocal API Key and Sender Name. +6. Customize your SMS Message (optional). + +## Next steps + +To implement Phone Login, see the docs on [using Phone Login](/docs/guides/auth/phone-login#using-phone-login). + +## Resources + +- [Textlocal Signup](https://www.textlocal.com/sign-up) +- [Supabase Dashboard](https://supabase.com/dashboard) diff --git a/apps/docs/content/guides/auth/phone-login/twilio.mdx b/apps/docs/content/guides/auth/phone-login/twilio.mdx new file mode 100644 index 00000000000..179002d8ae4 --- /dev/null +++ b/apps/docs/content/guides/auth/phone-login/twilio.mdx @@ -0,0 +1,151 @@ +--- +id: 'auth-twilio' +title: 'Phone Auth with Twilio' +description: 'How to set up and use Mobile OTP with Twilio and Supabase.' +video: 'https://www.youtube.com/v/akScoPO01bc' +--- + + + +Authenticating users via SMS can become expensive. Adjust your project's rate limits and [configure CAPTCHA](/docs/guides/auth/auth-captcha) to control the bill. Read more about this in the [Production Checklist](/docs/guides/platform/going-into-prod). + + + +## Prerequisites + +You'll need: + +- Twilio account ([sign up](https://www.twilio.com/try-twilio)) +- Supabase project (create one [here](https://supabase.com/dashboard)) +- Mobile phone capable of receiving SMS + +SMS Authentication can be done with either Twilio Verify or Twilio Programmable Messaging. [Twilio Verify](https://www.twilio.com/en-us/trusted-activation/verify) is a specialized OTP solution and is recommended for most developers that need over-the-phone authentication. Alternatively you can use [Twilio Programmable Messaging](https://www.twilio.com/docs/messaging) which offers generic SMS sending support. + +## Twilio Verify + +To set up Twilio Verify, you will need to: + +1. Create a new [verification service](https://support.twilio.com/hc/en-us/articles/360033309133-Getting-Started-with-Twilio-Verify-V2) in the Twilio dashboard. +2. [Switch Phone Provider to Twilio Verify](https://supabase.com/dashboard/project/_/auth/providers) +3. Configure the Twilio Verify Service ID field using the Verification Service ID obtained in 1. + +When using Twilio Verify, OTPs are generated by Twilio. This means that: + +- Unlike other providers, the OTP expiry duration and message content fields are not configurable via the Supabase dashboard. Please head to Twilio Verify to configure these settings. +- The token remains the same during its validity period until the verification is successful. This means if your user makes another request within that period, they will receive the same token. +- Twilio Verify has a separate set of rate limits that apply. Visit Twilio's [Rate Limit and Timeouts page](https://www.twilio.com/docs/verify/api/rate-limits-and-timeouts) to find out more. + + + +At this time, Twilio Verify is only supported on the `whatsapp` and `sms` channels. + + + +## Twilio (Programmable Messaging) + +In this section, you'll set up Twilio as an SMS provider: + +What you'll need: + +- A Twilio account (sign up here: https://www.twilio.com/try-twilio) +- A Supabase project (create one here: https://supabase.com/dashboard) +- A mobile phone capable of receiving SMS + +
+ +
+ +### Setting up your Twilio credentials + +Start by logging into your Twilio account and starting a new project: https://www.twilio.com/console/projects/create + +Give your project a name and verify the mobile number you'll be using to test with. This is the number that will be receiving the SMS OTPs. + +![Name your twilio project](/docs/img/guides/auth-twilio/1.png) +![verify your own phone number](/docs/img/guides/auth-twilio/2.png) + +Select 'SMS', 'Identity & Verification', and 'With code' as options on the welcome form. + +![Form Fields](/docs/img/guides/auth-twilio/3.png) + +When you're back on the [Twilio console screen](https://www.twilio.com/console), you need to scroll down and click 'Get a trial phone number' - this is the number that you'll be sending SMSs from. + +![Get a trial phone number](/docs/img/guides/auth-twilio/4.png) + +![Successful phone number](/docs/img/guides/auth-twilio/5.png) + +You should now be able to see all three values you'll need to get started: + +- Account SID +- Auth Token +- Sender Phone Number + +![All the credentials you'll need](/docs/img/guides/auth-twilio/6.png) + +Now go to the [Auth > Providers](https://supabase.com/dashboard/project/_/auth/providers) page in the Supabase dashboard and select "Phone" from the Auth Providers list. + +You should see an option to enable the Phone provider. + +Toggle it on, and copy the 3 values over from the Twilio dashboard. Click save. + +Note: for "Twilio Message Service SID" you can use the Sender Phone Number generated above. + +![Plug in Twilio credentials](/docs/img/guides/auth-twilio/8.png) + +Now the backend should be setup, we can proceed to add our client-side code! + + + The `Twilio Content SID` field is specific to Twilio Programmable Messaging (WhatsApp) senders. + Disregard this field if you are only sending SMS messages. Refer to the section on WhatsApp OTP + Logins for further details. + + +#### SMS custom template + +The SMS message sent to a phone containing an OTP code can be customized. This is useful if you need to mention a brand name or display a website address. + +Go to the [Auth > Providers](https://supabase.com/dashboard/project/_/auth/providers) page in the Supabase dashboard and select "Phone" from the Auth Providers list. Scroll to the very bottom of the "Phone" section to the "SMS Message" input - you can customize the SMS message here. + +Use the variable `.Code` in the template to display the OTP code. Here's an example in the SMS template. + +![example in the SMS template](/docs/img/guides/auth-twilio/9.png) + +## WhatsApp OTP logins + +In some cases, you may wish to use WhatsApp as a delivery channel instead. Here are some examples our users have cited: + +- You want higher deliverability +- You wish for a secure channel +- Your users mostly use WhatsApp as a messaging platform + +Twilio Verify can be used with WhatsApp OTPs with no additional configuration. + +Complete the following steps to use WhatsApp OTP with Twilio Programmable Messaging: + +1. Go through the [Twilio self sign up guide for WhatsApp](https://www.twilio.com/docs/whatsapp/self-sign-up). +2. Register a Twilio Content Template via the [API](https://www.twilio.com/docs/content/whatsappauthentication) and note the corresponding Twilio Content SID. You can also use the Template Builder on the Twilio dashboard to create a Content Template + ![Twilio Content SID Image](/docs/img/guides/auth-twilio/twilio_content_sid.png) +3. Register the Twilio Content SID on the Supabase dashboard under Authentication > Providers > Phone > Twilio Content SID. Ensure you have Twilio selected as your phone provider. + + + +You may only use one Twilio Content SID at a time. Supabase Auth will use the Content Template over the `SMS Message` field when sending WhatsApp messages. Use Twilio Verify if you need to use more than one message template. + + + +## Next steps + +To implement Phone Login, see the docs on [using Phone Login](/docs/guides/auth/phone-login#using-phone-login). + +## Resources + +- [Reasons to use Twilio Verify](https://www.twilio.com/blog/9-reasons-to-use-the-verify-api) +- [Twilio Verify Documentation](https://www.twilio.com/docs/verify) +- [Twilio Signup](https://www.twilio.com/try-twilio) +- [Supabase Dashboard](https://supabase.com/dashboard) +- [Supabase Row Level Security](/docs/guides/auth#row-level-security) diff --git a/apps/docs/content/guides/auth/phone-login/vonage.mdx b/apps/docs/content/guides/auth/phone-login/vonage.mdx new file mode 100644 index 00000000000..046f0b85d2a --- /dev/null +++ b/apps/docs/content/guides/auth/phone-login/vonage.mdx @@ -0,0 +1,66 @@ +--- +id: 'auth-vonage' +title: 'Phone Auth with Vonage' +description: 'How to set up and use Mobile OTP with Vonage and Supabase.' +--- + + + +Authenticating users via SMS can become expensive. Adjust your project's rate limits and [configure CAPTCHA](/docs/guides/auth/auth-captcha) to control the bill. Read more about this in the [Production Checklist](/docs/guides/platform/going-into-prod). + + + +## Prerequisites + +You'll need: + +- A Vonage account (sign up here: https://dashboard.nexmo.com/sign-up) +- A Supabase project (create one here: https://supabase.com/dashboard) +- A mobile phone capable of receiving SMS + +## Set up Vonage as an SMS provider + +### Getting your Vonage credentials + +Start by logging into your Vonage Dashboard at https://dashboard.nexmo.com/ + +You will see you API Key and API Secret here, which is actually all you need to get started. + +In most countries, a phone number is actually optional and you can also use any Alphanumeric Sender ID of up to 11 characters length (8 for India) as a Sender ID (from). This means you do not need a number to test with in most cases. + +To find out more about supported countries for Alphanumeric Sender ID, check this overview: https://help.nexmo.com/hc/en-us/articles/115011781468-SMS-Features-Overview-Outbound-only- + +Hint: Some countries might need a Sender ID Registration to allow sending with an Alphanumeric Sender ID. You can find this information in the help article as well. If Alpha Sender IDs are not supported, you will need to buy a phone number. + +### Getting a phone number (optional) + +If you want a phone number to send SMS from, you can buy one from the Vonage Dashboard under Numbers > Buy Numbers (https://dashboard.nexmo.com/buy-numbers). + +Select the country you want a number for. You will need a mobile phone number with SMS or SMS+Voice capability. After you have bought the number, you will be able to send SMS from it. + +### Configure Supabase + +Now go to the [Auth > Providers](https://supabase.com/dashboard/project/_/auth/providers) page in the Supabase dashboard and select "Phone" from the Auth Providers list. + +You should see an option to enable the Phone provider. + +Toggle it on, and copy the API key, API secret and phone number values over from the Vonage dashboard. Click save. + +Now the backend should be setup, we can proceed to add our client-side code! + +#### SMS custom template + +The SMS message sent to a phone containing an OTP code can be customized. This is useful if you need to mention a brand name or display a website address. + +Go to [Auth > Templates](https://supabase.com/dashboard/project/_/auth/templates) page in the Supabase dashboard. + +Use the variable `.Code` in the template to display the code. + +## Next steps + +To implement Phone Login, see the docs on [using Phone Login](/docs/guides/auth/phone-login#using-phone-login). + +## Resources + +- [Vonage Signup](https://dashboard.nexmo.com/sign-up) +- [Supabase Dashboard](https://supabase.com/dashboard) diff --git a/apps/docs/content/guides/auth/social-login/auth-google.mdx b/apps/docs/content/guides/auth/social-login/auth-google.mdx index 1e7669418a0..daedf976d98 100644 --- a/apps/docs/content/guides/auth/social-login/auth-google.mdx +++ b/apps/docs/content/guides/auth/social-login/auth-google.mdx @@ -256,7 +256,7 @@ For an implicit flow, that's all you need to do. The user will be taken to Googl After a successful code exchange, the user's session will be saved to cookies. -### Saving Google tokens +#### Saving Google tokens The tokens saved by your application are the Supabase Auth tokens. Your app might additionally need the Google OAuth 2.0 tokens to access Google services on the user's behalf.