# Facebook Sign-In Setup

**Time: ~20 minutes. Cost: free.** Be warned: this is the fussiest of the four, and Facebook now requires a **Business Verification** step before your app can go live to the public. Budget a few days of waiting.

Facebook is also the one most likely to *not* return an email address (users can decline the email permission, and accounts created with a phone number may not have one). The app handles this gracefully — it tells the user to try another provider — but expect it.

---

## Step 1 — Create the app

1. Go to **https://developers.facebook.com/apps/**
2. **Create App**
3. Use case: **Authenticate and request data from users with Facebook Login**
4. **Next**
5. App name: `Paddlers Cove`; contact email: yours
6. Business portfolio: create one or select existing → **Create app**

---

## Step 2 — Add Facebook Login

1. In the app dashboard, find **Facebook Login** → **Set up**
2. Choose **Web**
3. Site URL: `https://paddlerscove.org` → **Save** → **Continue** (you can skip the quickstart code; we already have it)

---

## Step 3 — Configure OAuth settings

1. Left nav → **Facebook Login** → **Settings**
2. Set:
   - **Client OAuth Login:** Yes
   - **Web OAuth Login:** Yes
   - **Enforce HTTPS:** Yes
   - **Use Strict Mode for redirect URIs:** Yes
   - **Valid OAuth Redirect URIs:**
     ```
     https://paddlerscove.org/auth/facebook/callback
     ```
3. **Save changes**

---

## Step 4 — Get credentials

1. Left nav → **App settings** → **Basic**
2. Copy **App ID** and **App Secret** (click Show):

```ini
FB_CLIENT_ID=1234567890123456
FB_CLIENT_SECRET=abcdef1234567890abcdef1234567890
FB_GRAPH_VERSION=v20.0
```

3. On the same page, fill in:
   - **App Domains:** `paddlerscove.org`
   - **Privacy Policy URL:** `https://paddlerscove.org/privacy` *(required to go live)*
   - **Terms of Service URL:** `https://paddlerscove.org/terms`
   - **User Data Deletion:** a URL or instructions *(required)*
   - **Category:** Community
   - **App Icon:** 1024×1024 PNG

---

## Step 5 — Permissions

1. Left nav → **App Review** → **Permissions and Features**
2. `public_profile` and `email` are granted by default with **Standard Access** — that's all we need.
3. Do **not** request anything else. Additional permissions trigger a full App Review with a screencast submission.

---

## Step 6 — Business verification and going live

1. Complete **Business Verification** under Business Settings (Meta requires a business document or a verified domain).
2. Once verified, flip the app from **Development** to **Live** using the toggle at the top of the dashboard.

Until it's Live, only people listed under **App Roles** (admins, developers, testers) can sign in. Add yourself as an admin to test.

---

## Troubleshooting

| Error | Cause | Fix |
|---|---|---|
| "URL Blocked: redirect URI not whitelisted" | Strict mode mismatch | Paste the exact callback URL into Valid OAuth Redirect URIs |
| "App not active" | Still in Development mode | Toggle to Live after business verification |
| No email returned | User declined, or account has no email | App shows a message telling them to use another provider |
| `Invalid Scopes: public_profile` | Requesting it explicitly when already default | Leave the scopes as configured in `ProviderFactory` |

---

## Honest recommendation

If you want to reduce maintenance, **skip Facebook initially**. Google + Microsoft + Apple covers nearly everyone, requires no business verification, and none of the three will surprise you with a policy change that breaks sign-in. You can add Facebook later if neighbors actually ask for it.