Auth - Adding Google, Facebook, and Apple

This page shows how to set up each provider for OAuth authentication with Supabase and GoTrue. We are going to use our website calmlykids.app or www.3dnames.co as examples in this document

How does this work?

Frontend-wise, we are now using a multi-auth box component to handle the authentication process. This component is designed to handle the following sign-in methods as an "all in one" solution:

• Register/Signin with Google
• Register/Signin with Facebook
• Register/Signin with Apple
• Register/Signin with Email & Password
• Register/Signin with Email via Magic Link
• Register/Signin with Email and 6-digit code
• Forgot Password via Email via Magic Link
• Forgot Password via Email and 6-digit code

It attempts to make Register and Sign in part of the same process flow, but if the user is not found, it will create a new user. For example, if you try to register but already exist, it will just sign you in. If you do not exist yet, it will create the account.

No more individual Login.tsx or Register.tsx components to manage, but instead a single MultiAuthBox component to handle all the authentication methods.

This document does not explain how to link up the Supabase Email & Password authentication to the MultiAuthBox component. Only the Google, Facebook, and Apple setup and configuration is covered here.

What you will already have

• A Supabase project already created, configured and running on your server
• Access to your Supabase stacks .env file and docker-compose.yml file
• A Frontend NextJS website using the MultiAuthBox component

Google OAuth Setup

🔎 🔎 🔎 Google is the easiest one of the three providers, and usually requires the least setup

First you need to navigate to: Google Cloud Console and create a new project.

Then in your project navigate to: APIs & Services -> OAuth Consent Screen and create your OAuth configuration.

For the client, create it as a Web Application and add the following details as per the image below, changing the 3dnames.co domain to your own domain.

Authorized JavaScript origins: Add your frontend website URLs, for example http://localhost:3000, http://localhost:3001, and https://calmlykids.app. You can remove old localhost entries later if you want, but keeping them for development is usually fine.

Authorized redirect URIs: Add your Supabase Auth callback URL, for example https://api-supabase.calmlykids.app/auth/v1/callback.

Once you have your Client ID and Client Secret, you can update your stacks .env file with the following values:

GOOGLE_CLIENT_ID=YOUR_CLIENT_ID
GOOGLE_CLIENT_SECRET=YOUR_CLIENT_SECRET

And in the stacks docker compose make sure you have these added under the services: auth: environment section:

services:
  auth:
    environment:
      # Google OAuth settings
      GOTRUE_EXTERNAL_GOOGLE_ENABLED: "true"
      GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}
      GOTRUE_EXTERNAL_GOOGLE_SECRET: ${GOOGLE_CLIENT_SECRET}
      GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI: ${API_EXTERNAL_URL}/auth/v1/callback

Restart your Docker Auth Service:

cd ~/Develop/ubuntu-home-server/stacks/11-supabase-stacks/calmlykids-stack
docker compose restart auth

Facebook OAuth Setup

👦🏻 📕 Facebook is probably the most awkward one to add. You may need to go through App Review, and Meta's dashboard can be a bit fiddly compared with Google.

1. Create a new App and choose "Authenticate and request data from users with Facebook Login" for the use case.

2. In App Settings -> Basic, add an icon and update the Privacy Policy and Terms of Service URLs to your own.
3. Copy the App ID and App Secret from the Basic settings page.

4. Click "+ Add Platform" and select Website.
5. Add your domain and also fill out the testing instructions explaining how the login can be tested.
6. Click Use Cases in the left menu, then under "Authenticate and request data from users with Facebook Login" click Customize.
7. Under Permissions & Features, we only want email and public_profile. You only need more if your app genuinely requires them.

8. In Facebook Login -> Settings, add your Supabase Auth callback URL, for example https://api-supabase.yourdomain.com/auth/v1/callback, as a Valid OAuth Redirect URI.

App Review Questions:

• Do you have data processors or service providers, including your own companies, that will have access to the Platform Data that you obtain from Meta? = No
• Who is the person or entity that will be responsible for all Platform Data Meta shares with you? = Vista Studios Ltd
• Select the country where this person or entity is located. = Brazil
• Have you provided the personal data or personal information of users to public authorities in response to national security requests in the past 12 months? = NO
• Which of the following policies or processes do you have in place regarding requests from public authorities for the personal data or personal information of users? Check all that apply. = Check the first 4 boxes

Now grab the App ID and App Secret from the App Settings -> Basic section, and update the Linux server .env file with:

FACEBOOK_CLIENT_ID="YOUR_APP_ID"
FACEBOOK_CLIENT_SECRET="YOUR_APP_SECRET"

And in the stacks docker compose make sure you have these added:

services:
  auth:
    environment:
      # Facebook OAuth settings
      GOTRUE_EXTERNAL_FACEBOOK_ENABLED : "true"
      GOTRUE_EXTERNAL_FACEBOOK_CLIENT_ID: ${FACEBOOK_CLIENT_ID}
      GOTRUE_EXTERNAL_FACEBOOK_SECRET: ${FACEBOOK_CLIENT_SECRET}
      GOTRUE_EXTERNAL_FACEBOOK_REDIRECT_URI: "${API_EXTERNAL_URL}/auth/v1/callback"

Restart your Docker Auth Service:

cd ~/Develop/ubuntu-home-server/stacks/11-supabase-stacks/calmlykids-stack
docker compose restart auth

Callback URL sanity check

Before moving on, it helps to understand the two different types of URLs involved in OAuth:

• Provider callback URL: This is the callback URL you register with Google / Facebook / Apple. For self-hosted Supabase, this should normally be your Supabase Auth callback URL, for example https://api-supabase.yourdomain.com/auth/v1/callback.
• Final app redirect URL: After Supabase finishes the OAuth exchange, it then redirects the user back to your website using your SITE_URL, your allowed redirect URLs, or a redirectTo value from your frontend code.

Getting these mixed up is one of the most common causes of OAuth setup bugs.

Apple OAuth Setup

🍎 🍎 🍎 Apple is also quite complex, but once all the moving parts are in place it works reliably

Essentially, you need to create 3 things in Apple Developer:

• an existing App ID for your iOS app (we already have this for Calmly Kids)
• a Services ID for web OAuth (Client ID)
• a Sign in with Apple Key (.p8)

Step-by-step for an existing app already in your Apple Connect account (Calmly Kids) using the existing App ID app.calmlykids

1. Go to Apple Developer -> Certificates, IDs & Profiles -> Identifiers.

2. Open your existing Calmly Kids App ID (for example app.calmlykids) and confirm Sign in with Apple is enabled. 1 There is no need to configure anything special here, just keep the defaults as below:

   • Keep "Enable as Primary App ID" checked 2
   • Leave "Server-to-Server Notification Endpoint" blank 2

3. Now we need to add a Services ID

   • Go to: Identifiers -> + -> Services IDs 4
   • Under "Register a New Service ID" select Services IDs then Continue 5
   • Identifier example: app.calmlykids.web (or whatever you like, just make sure it's unique) 6, Description: "Web OAuth for Calmly Kids" then press continue
   • Now open that Services ID -> Sign in with Apple -> Configure 7
   • Primary App ID: select your existing Calmly Kids App ID 8
   • Domains and Subdomains: calmlykids.app
   • Return URLs: https://api-supabase.calmlykids.app/auth/v1/callback
   • Press Next and then Save 9

4. And now a Key

   • Go to Keys and add a new key with + 10
   • Check Sign in with Apple and then click Configure 11
   • Associate it with the correct App ID / Services ID setup for this Sign in with Apple configuration 12
   • Press Save, then Register 13, then Download the .p8 file (shown once only) 14
   • Now note down your Key ID, Team ID, and Services ID

5. Okay, everything on Apple's side is done, so now we need to update our Supabase stack

   • GOTRUE_EXTERNAL_APPLE_CLIENT_ID: app.calmlykids.web (or whatever yours is)
   • GOTRUE_EXTERNAL_APPLE_SECRET: this is where we use a script to create the secret from the values noted above.

So, use the joemore.dev/scripts/apple-client-secret.mjs script and copy its output value for GOTRUE_EXTERNAL_APPLE_SECRET:

node scripts/apple-client-secret.mjs \
  --team-id YOUR_APPLE_TEAM_ID \
  --key-id YOUR_APPLE_KEY_ID \
  --client-id YOUR_APPLE_SERVICES_ID \
  --key-file /absolute/path/to/AuthKey_XXXXXXXXXX.p8

6. Now Update your stacks .env file with the following values:

GOTRUE_EXTERNAL_APPLE_CLIENT_ID=app.calmlykids.web
GOTRUE_EXTERNAL_APPLE_SECRET=YOUR_APPLE_CLIENT_SECRET

7. Check your docker-compose.yml file, and under the services: auth: environment section, add the following values if they don't yet exist:

services:
  auth:
    environment:
      # Apple OAuth settings
      GOTRUE_EXTERNAL_APPLE_ENABLED: "true"
      GOTRUE_EXTERNAL_APPLE_CLIENT_ID: ${GOTRUE_EXTERNAL_APPLE_CLIENT_ID}
      GOTRUE_EXTERNAL_APPLE_SECRET: ${GOTRUE_EXTERNAL_APPLE_SECRET}
      GOTRUE_EXTERNAL_APPLE_REDIRECT_URI: "${API_EXTERNAL_URL}/auth/v1/callback"

Restart your Docker Auth Service:

cd ~/Develop/ubuntu-home-server/stacks/11-supabase-stacks/calmlykids-stack
docker compose restart auth

🎉 Hey Presto - your Apple Auth should now work on your website!

All apple Images:

123456789101112131415