Skip to content

Commit

Permalink
feat: new auth ia (#22812)
Browse files Browse the repository at this point in the history 
Co-authored-by: Kang Ming <kang.ming1996@gmail.com>
Co-authored-by: Joel Lee <lee.yi.jie.joel@gmail.com>
  • Loading branch information
@charislam @kangmingtay @J0
3 people authored May 7, 2024
1 parent 13d8514 commit ec86bbc
Show file tree
Hide file tree
Showing 113 changed files with 2,846 additions and 3,093 deletions.
19 changes: 19 additions & 0 deletions apps/docs/components/AuthSmsProviderConfig/AuthSmsProviderConfig.Warnings.tsx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
import Link from 'next/link'
import { Admonition } from 'ui'

const CostWarning = () => (
<Admonition type="warning">
<p>
To keep SMS sending costs under control, make sure you adjust your project&apos;s rate limits
and <Link href="/guides/auth/auth-captcha">configure CAPTCHA</Link>. See the{' '}
<Link href="/guides/platform/going-into-prod">Production Checklist</Link> to learn more.
</p>
<p>
Some countries have special regulations for services that send SMS messages to users, for
example, India&apos;s TRAI DLT regulations. Remember to look up and follow the regulations of
countries where you operate.
</p>
</Admonition>
)

export { CostWarning }
86 changes: 86 additions & 0 deletions apps/docs/components/AuthSmsProviderConfig/AuthSmsProviderConfig.tsx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
import { useEffect, useReducer, useRef } from 'react'
import { PhoneLoginsItems } from '../Navigation/NavigationMenu/NavigationMenu.constants'
import { IconPanel } from 'ui-patterns/IconPanel'
import { Dialog, DialogContent, DialogHeader, DialogSection, Heading } from 'ui'
import MessageBird from './MessageBirdConfig.mdx'
import Twilio from './TwilioConfig.mdx'
import Vonage from './VonageConfig.mdx'
import TextLocal from './TextLocalConfig.mdx'

const reducer = (_, action: (typeof PhoneLoginsItems)[number] | undefined) => {
const url = new URL(document.location.href)
if (action) {
url.searchParams.set('showSmsProvider', encodeURIComponent(action.name))
} else {
url.searchParams.delete('showSmsProvider')
}
window.history.replaceState(null, '', url)
return action
}

const AuthSmsProviderConfig = () => {
const [selectedProvider, setSelectedProvider] = useReducer(reducer, undefined)

useEffect(() => {
const providerName = new URLSearchParams(document.location.search ?? '').get('showSmsProvider')
if (!providerName) return

const provider = PhoneLoginsItems.find((item) => item.name === decodeURIComponent(providerName))
if (provider) setSelectedProvider(provider)
}, [])

const headingRef = useRef<HTMLHeadingElement>(null)

return (
<>
<section aria-labelledby="sms-provider-configuration">
<h3 className="sr-only" id="sms-provider-configuration">
Configuring SMS Providers
</h3>
<div className="grid grid-cols-6 gap-10 not-prose py-8">
{PhoneLoginsItems.map((provider) => (
<button
key={provider.name}
className="col-span-6 xl:col-span-3"
onClick={() => setSelectedProvider(provider)}
>
<IconPanel
title={provider.name}
icon={provider.icon}
hasLightIcon={provider.hasLightIcon}
/>
</button>
))}
</div>
</section>
<Dialog
open={!!selectedProvider}
onOpenChange={(open) => !open && setSelectedProvider(undefined)}
>
{selectedProvider && (
<DialogContent
className="!w-[min(90vw,80ch)] !max-w-[min(90vw,80ch)] !max-h-[90dvh] prose overflow-auto"
onOpenAutoFocus={(evt) => {
evt.preventDefault()
headingRef.current?.focus()
}}
>
<DialogHeader className="pb-0 [&>h3]:!m-0 [&>h3>a]:!hidden [&>h3:focus-visible]:outline-none">
<Heading tag="h3" ref={headingRef} tabIndex={-1}>
{selectedProvider.name}
</Heading>
</DialogHeader>
<DialogSection className="[&>:first-child]:mt-0">
{selectedProvider.name.toLowerCase().includes('messagebird') && <MessageBird />}
{selectedProvider.name.toLowerCase().includes('twilio') && <Twilio />}
{selectedProvider.name.toLowerCase().includes('vonage') && <Vonage />}
{selectedProvider.name.toLowerCase().includes('textlocal') && <TextLocal />}
</DialogSection>
</DialogContent>
)}
</Dialog>
</>
)
}

export default AuthSmsProviderConfig
48 changes: 48 additions & 0 deletions apps/docs/components/AuthSmsProviderConfig/MessageBirdConfig.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
import { CostWarning } from './AuthSmsProviderConfig.Warnings'

## 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

<CostWarning />

## 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.

<Admonition>

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.

</Admonition>

#### 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.
42 changes: 42 additions & 0 deletions apps/docs/components/AuthSmsProviderConfig/TextLocalConfig.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
import { CostWarning } from './AuthSmsProviderConfig.Warnings'

## 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.

<CostWarning />

## 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).
130 changes: 130 additions & 0 deletions apps/docs/components/AuthSmsProviderConfig/TwilioConfig.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
import { CostWarning } from './AuthSmsProviderConfig.Warnings'

## 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.

<CostWarning />

## 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.

<Admonition type="caution">

At this time, Twilio Verify is only supported on the `whatsapp` and `sms` channels.

</Admonition>

## 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

<div className="video-container">
<iframe
src="https://www.youtube-nocookie.com/embed/akScoPO01bc"
frameBorder="1"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
</div>

### 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!

<Admonition type="note">
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.
</Admonition>

#### 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.

<Admonition>

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.

</Admonition>
49 changes: 49 additions & 0 deletions apps/docs/components/AuthSmsProviderConfig/VonageConfig.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
import { CostWarning } from './AuthSmsProviderConfig.Warnings'

## 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

<CostWarning />

## 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.
7 changes: 7 additions & 0 deletions apps/docs/components/AuthSmsProviderConfig/index.tsx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
import dynamic from 'next/dynamic'

const LazyConfig = dynamic(() => import('./AuthSmsProviderConfig'))

const AuthSmsProviderConfig = () => <LazyConfig />

export { AuthSmsProviderConfig }
Loading

0 comments on commit ec86bbc

Please sign in to comment.