Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs: improve Facebook OAuth guide with troubleshooting and clearer instructions (#41893)

Guilherme Souza15eb27fb1913
diff --git a/apps/docs/content/guides/auth/social-login/auth-facebook.mdx b/apps/docs/content/guides/auth/social-login/auth-facebook.mdx
index 1f62867576f..555828dd3a4 100644
--- a/apps/docs/content/guides/auth/social-login/auth-facebook.mdx
+++ b/apps/docs/content/guides/auth/social-login/auth-facebook.mdx
@@ -8,9 +8,10 @@ To enable Facebook Auth for your project, you need to set up a Facebook OAuth ap
## Overview
-Setting up Facebook logins for your application consists of 3 parts:
+Setting up Facebook logins for your application consists of 4 parts:
- Create and configure a Facebook Application on the [Facebook Developers Site](https://developers.facebook.com)
+- **Configure email permissions** in your Facebook app (required for Supabase Auth)
- Add your Facebook keys to your [Supabase Project](/dashboard)
- Add the login code to your [Supabase JS Client App](https://github.com/supabase/supabase-js)
@@ -35,19 +36,39 @@ Setting up Facebook logins for your application consists of 3 parts:
From the `Add Products to your App` screen:
-- Click `Setup` under `Facebook Login`
-- Skip the Quickstart screen, instead, in the left sidebar, click `Settings` under `Facebook Login`
-- Enter your callback URI under `Valid OAuth Redirect URIs` on the `Facebook Login Settings` page
-- Enter this in the `Valid OAuth Redirect URIs` box
-- Click `Save Changes` at the bottom right
+- Click **Setup** under **Facebook Login**
+- Skip the Quickstart screen. Instead, in the left sidebar, click **Settings** under **Facebook Login**
+- Enter your callback URI under **Valid OAuth Redirect URIs** on the **Facebook Login Settings** page
+- Click **Save Changes** at the bottom right
-Be aware that you have to set the right use case permissions to enable Third party applications to read the email address. To do so:
+<Admonition type="tip">
-Under `Build Your App`, click on `Use Cases` screen. From there, do the following steps:
+Your callback URI follows this pattern: `https://<project-ref>.supabase.co/auth/v1/callback`
-- Click the Edit button in `Authentication and Account Creation` on the right side. This action will lead to the other page.
-- `public_profile` is set by default, so make sure it and `email` have status of **Ready for testing** in the redirected page.
-- If not, click the **Add** button in email on right side.
+You can find your project's callback URI in the [Supabase Dashboard](/dashboard/project/_/auth/providers) under **Authentication > Providers > Facebook**.
+
+</Admonition>
+
+## Configure email permissions (required)
+
+<Admonition type="caution">
+
+This step is **required** for Supabase Auth to work correctly. Without email permissions, Facebook will not return the user's email address, which may cause authentication failures or incomplete user profiles.
+
+</Admonition>
+
+You must configure the email permission in your Facebook app's Use Cases:
+
+1. In your Facebook app dashboard, click **Use Cases** under `Build Your App`
+2. Find **Authentication and Account Creation** and click the **Edit** button on the right
+3. Verify that both `public_profile` and `email` show status **Ready for testing**
+4. If `email` is not listed, click the **Add** button next to it
+
+<Admonition type="tip">
+
+You can verify the permissions are set correctly by checking that both `public_profile` and `email` appear with a green check mark or "Ready for testing" status.
+
+</Admonition>
## Copy your Facebook app ID and secret
@@ -102,6 +123,13 @@ async function signInWithFacebook() {
const { data, error } = await supabase.auth.signInWithOAuth({
provider: 'facebook',
})
+
+ if (error) {
+ console.error('Error signing in with Facebook:', error.message)
+ return
+ }
+
+ // The user will be redirected to Facebook for authentication
}
```
@@ -129,9 +157,15 @@ First, add the Facebook SDK dependency to your `pubspec.yaml`:
```yaml
dependencies:
- flutter_facebook_auth: ^7.0.1
+ flutter_facebook_auth: ^7.0.0
```
+<Admonition type="tip">
+
+Check [pub.dev](https://pub.dev/packages/flutter_facebook_auth) for the latest version of `flutter_facebook_auth`.
+
+</Admonition>
+
Then implement the Facebook authentication:
```dart
@@ -177,20 +211,40 @@ Make sure to configure your Facebook app properly and add the required permissio
When your user signs in, call [`signInWithOAuth()`](/docs/reference/swift/auth-signinwithoauth) with `facebook` as the `provider`:
```swift
-func signInWithFacebook() async throws {
- try await supabase.auth.signInWithOAuth(
- provider: .facebook,
- redirectTo: URL(string: "my.scheme://my-host")!, // Optionally set the redirect link to bring back the user via deeplink.
- launchFlow: { url in
- // use url to start OAuth flow
- // and return a result url that contains the OAuth token.
- // ...
- return resultURL
+import SwiftUI
+
+struct SignInWithFacebook: View {
+ @Environment(\.webAuthenticationSession) var webAuthenticationSession
+
+ var body: some View {
+ Button("Sign in with Facebook") {
+ Task {
+ do {
+ try await supabase.auth.signInWithOAuth(
+ provider: .facebook,
+ redirectTo: URL(string: "my.scheme://my-host")!,
+ launchFlow: { @MainActor url in
+ try await webAuthenticationSession.authenticate(
+ using: url,
+ callbackURLScheme: "my.scheme"
+ )
+ }
+ )
+ } catch {
+ print("Failed to sign in with Facebook: \(error)")
+ }
+ }
}
- )
+ }
}
```
+<Admonition type="note">
+
+Make sure to configure your app's URL scheme in Xcode under **Target > Info > URL Types**. The callback URL scheme should match the scheme used in `redirectTo` (e.g., `my.scheme`).
+
+</Admonition>
+
</TabPanel>
</$Show>
<$Show if="sdk:kotlin">
@@ -228,6 +282,13 @@ const supabase = createClient('https://your-project.supabase.co', 'sb_publishabl
// ---cut---
async function signOut() {
const { error } = await supabase.auth.signOut()
+
+ if (error) {
+ console.error('Error signing out:', error.message)
+ return
+ }
+
+ // User has been signed out
}
```
@@ -271,8 +332,89 @@ suspend fun signOut() {
</$Show>
</Tabs>
-Now, you should be able to login with Facebook and alert you to `Submit for Login Review` when users try to sign into your app. Follow the instructions there to make your app go live for full features and products.
-You can read more about App Review [here](https://developers.facebook.com/docs/app-review/).
+## Testing your integration
+
+Facebook apps start in **Development** mode, which has the following limitations:
+
+- Only users with a role on the app (administrators, developers, testers) can authenticate
+- Other users will see an "App Not Setup" error when trying to log in
+
+To add test users:
+
+1. Go to [developers.facebook.com](https://developers.facebook.com) and select your app
+2. Navigate to **App Roles > Roles**
+3. Add users as Testers, Developers, or Administrators
+4. Users must accept the invitation from their Facebook notification settings
+
+<Admonition type="tip">
+
+Development mode is sufficient for local development and testing. You only need to submit for App Review when you're ready to allow any Facebook user to authenticate with your app.
+
+</Admonition>
+
+## Going live with app review
+
+Before your app can be used by the general public, you need to complete Facebook's App Review process:
+
+1. **Complete App Settings**: In your Facebook app's **Settings > Basic**, fill in all required fields including:
+
+ - App Icon
+ - Privacy Policy URL
+ - Terms of Service URL (if applicable)
+ - App Domain
+
+2. **Request Permissions**: Navigate to **App Review > Permissions and Features** and request the permissions you need:
+
+ - `public_profile` - Usually pre-approved
+ - `email` - Requires verification that your app needs email access
+
+3. **Submit for Review**: Click **Submit for Review** and provide:
+
+ - Detailed instructions for how Facebook reviewers should test your login flow
+ - A screencast video demonstrating the Facebook Login feature
+ - Explanation of how user data will be used
+
+4. **Wait for Approval**: Facebook typically reviews apps within 1-5 business days
+
+<Admonition type="note">
+
+If you only need basic authentication (name and profile picture), you may not need full App Review. Apps requesting only `public_profile` and `email` with the "Authenticate and request data from users with Facebook Login" use case can often go live without a detailed review.
+
+</Admonition>
+
+For more details, see the [Facebook App Review documentation](https://developers.facebook.com/docs/app-review/).
+
+## Troubleshooting
+
+### "App not setup" error
+
+This error occurs when a user without a role on your app tries to log in while the app is in Development mode.
+
+**Solution**: Either add the user as a tester in your Facebook app settings, or complete the App Review process to make your app available to all users.
+
+### User's email not returned
+
+Facebook only returns the email address if:
+
+- The user has a confirmed email on their Facebook account
+- Your app has been granted the `email` permission
+- The `email` permission is marked as "Ready for testing" in **Use Cases > Authentication and Account Creation**
+
+**Solution**: Check that the `email` permission is properly configured in your Facebook app's Use Cases settings.
+
+### "Redirect URI mismatch" error
+
+This error indicates the callback URL configured in Facebook doesn't match the one used during authentication.
+
+**Solution**: Verify that the **Valid OAuth Redirect URIs** in your Facebook app settings exactly matches `https://<project-ref>.supabase.co/auth/v1/callback`. Make sure there are no trailing slashes or typos.
+
+### Login works in development but not production
+
+If login works locally but fails in production, check:
+
+- Your production URL is added to **Valid OAuth Redirect URIs** in Facebook
+- The App ID and Secret in your Supabase dashboard match your Facebook app
+- Your Facebook app is in **Live** mode (not Development mode)
## Resources
diff --git a/supa-mdx-lint/Rule003Spelling.toml b/supa-mdx-lint/Rule003Spelling.toml
index 9d0dc1857b1..c032198ff5b 100644
--- a/supa-mdx-lint/Rule003Spelling.toml
+++ b/supa-mdx-lint/Rule003Spelling.toml
@@ -392,6 +392,7 @@ allow_list = [
"plpgsql",
"psql",
"scrypt",
+ "screencast",
"sessionStorage",
"signInWithIdToken",
"stdin",