Skip to content

Commit 24b655e

Browse files
AzizX-coderclaude
AzizX-coder
and
claude
committed
docs: complete OAuth setup guide for Google + GitHub
Step-by-step, copy-pasteable. Covers consent-screen setup, the exact callback URL to paste, where the secrets go in Supabase, common errors and how to fix them, and what to flip when going live with a real domain. Explicitly notes you write zero JWT code - Supabase handles the verification. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent 5f69960 commit 24b655e

1 file changed

Lines changed: 199 additions & 0 deletions

File tree

‎docs/OAUTH-SETUP.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# OAuth setup for Delay
2+
3+
How to wire Google and GitHub sign-in to Delay's Supabase project so the
4+
"Continue with Google" and "Continue with GitHub" buttons on the auth
5+
screen actually work.
6+
7+
You do this once per provider. After that, every user who clicks the
8+
button just signs in — no further code changes.
9+
10+
---
11+
12+
## Before you start
13+
14+
| Need | Where to get it |
15+
| --- | --- |
16+
| A Supabase project | Already done. Project ref: `splthfrwtddrkcherwwj` |
17+
| The schema applied | Run `supabase/schema.sql` once in the Supabase SQL editor before testing sign-in — otherwise the auto-create-profile trigger has no `profiles` table to write to |
18+
| Your Supabase callback URL | `https://splthfrwtddrkcherwwj.supabase.co/auth/v1/callback` — you will paste this several times below, keep it handy |
19+
20+
> **Why Supabase, not me?** The browser → Google → Supabase → back-to-app
21+
> dance involves a JWT signed by Google. Supabase already knows how to
22+
> fetch Google's public keys (JWKS), verify the signature, and mint its
23+
> own Supabase JWT for the app. Doing that yourself is ~200 lines of
24+
> security-sensitive code you would have to maintain forever. Don't.
25+
26+
---
27+
28+
## 1. Google sign-in
29+
30+
### 1.1 Create the Google Cloud project (one-time)
31+
32+
1. Open <https://console.cloud.google.com>. Sign in with whichever Google
33+
account you want to own the OAuth app.
34+
2. Top-left next to the Google Cloud logo → **Select a project** → **New project**.
35+
3. Name it `Delay`. Leave organization on "No organization". Click **Create**.
36+
4. Wait ~10s, then select the new project from the same dropdown.
37+
38+
### 1.2 Set up the OAuth consent screen
39+
40+
This is the page users see *before* they're sent back to Delay — it's
41+
the "Delay wants to access your name and email" prompt.
42+
43+
1. Left nav → **APIs & Services** → **OAuth consent screen**.
44+
2. **User Type → External** → **Create**.
45+
3. **App information:**
46+
- App name: `Delay`
47+
- User support email: your email
48+
- App logo: optional, skip for now
49+
4. **App domain:** leave blank, or paste your landing URL once you have one.
50+
5. **Developer contact information:** your email.
51+
6. Click **Save and continue**.
52+
7. **Scopes** → **Save and continue** (don't add any — Supabase asks for
53+
the minimum it needs at sign-in time).
54+
8. **Test users** → **+ Add Users** → add your own email and any teammate
55+
who'll test before you publish. Save and continue.
56+
9. **Summary** → **Back to dashboard**.
57+
58+
> Your app is now in "Testing" mode. Only listed test users can sign in.
59+
> When you're ready for real users, come back here and click
60+
> **Publish app** (Google will ask you to verify ownership).
61+
62+
### 1.3 Create the OAuth client ID (the credential)
63+
64+
1. Left nav → **APIs & Services** → **Credentials**.
65+
2. **+ Create credentials** → **OAuth client ID**.
66+
3. **Application type → Web application**.
67+
4. **Name:** `Delay Web` (this is internal, users never see it).
68+
5. **Authorized JavaScript origins** → **+ Add URI**, add the URLs Delay
69+
runs at:
70+
- `http://localhost:5173`
71+
- `https://azizx-coder.github.io`
72+
- Your Vercel landing URL once you have one, e.g. `https://delay.vercel.app`
73+
6. **Authorized redirect URIs** → **+ Add URI** → paste exactly:
74+
```
75+
https://splthfrwtddrkcherwwj.supabase.co/auth/v1/callback
76+
```
77+
This is the *only* redirect URI you need — Supabase handles
78+
the redirect from there into Delay.
79+
7. **Create**. A modal appears with **Client ID** and **Client secret**.
80+
Copy both into a notes file — you cannot see the secret again later
81+
(you can regenerate it if you lose it).
82+
83+
### 1.4 Paste them into Supabase
84+
85+
1. Open <https://supabase.com/dashboard/project/splthfrwtddrkcherwwj/auth/providers>.
86+
2. Find **Google** in the providers list, click the row to expand.
87+
3. Toggle **Enable Sign in with Google** to ON.
88+
4. **Client ID (for OAuth)**: paste the Client ID.
89+
5. **Client Secret (for OAuth)**: paste the Client Secret.
90+
6. **Callback URL (for OAuth)**: confirm it shows the same `…/auth/v1/callback` URL you used above.
91+
7. **Save**.
92+
93+
Done. The "Continue with Google" button now works.
94+
95+
---
96+
97+
## 2. GitHub sign-in
98+
99+
### 2.1 Create the OAuth app
100+
101+
1. Open <https://github.com/settings/developers> → **OAuth Apps** → **New OAuth App**.
102+
2. **Application name:** `Delay`
103+
3. **Homepage URL:** your landing or app URL — e.g.
104+
`https://azizx-coder.github.io/Delay/` (you can change this later).
105+
4. **Application description:** optional.
106+
5. **Authorization callback URL** — paste exactly:
107+
```
108+
https://splthfrwtddrkcherwwj.supabase.co/auth/v1/callback
109+
```
110+
6. **Register application**.
111+
7. On the next page you see a **Client ID** — copy it.
112+
8. Click **Generate a new client secret** → copy the secret immediately
113+
(GitHub will hide it on refresh).
114+
115+
### 2.2 Paste them into Supabase
116+
117+
1. Same providers page in Supabase. Find **GitHub** → expand the row.
118+
2. Toggle **Enable Sign in with GitHub** to ON.
119+
3. Paste **Client ID** and **Client Secret**.
120+
4. **Save**.
121+
122+
Done.
123+
124+
---
125+
126+
## 3. (Optional) Email + magic link
127+
128+
Email/password sign-in is already enabled by default — no setup needed.
129+
130+
For **magic link** (no password, just email):
131+
132+
1. Same providers page → **Email** is already on.
133+
2. **Authentication → URL configuration**: set the **Site URL** to your
134+
app URL — for now, `https://azizx-coder.github.io/Delay/`. This is
135+
where the link in the email sends them after clicking. Without this,
136+
the magic link redirects to localhost and breaks for real users.
137+
138+
---
139+
140+
## 4. Verify it works
141+
142+
1. Make sure the secrets are deployed: GitHub repo → Settings → Secrets
143+
and variables → Actions. You should see `VITE_SUPABASE_URL` and
144+
`VITE_SUPABASE_ANON_KEY`.
145+
2. Trigger a fresh deploy (Actions → Deploy Site → Run workflow) or
146+
wait for your next push to `main`.
147+
3. Open `https://azizx-coder.github.io/Delay/app/`.
148+
4. You should see the auth screen. Click **Continue with Google**.
149+
5. Google's consent screen appears → approve → you bounce back into
150+
Delay, signed in. Open the profile menu — you should see your name.
151+
6. Check Supabase: **Authentication → Users**. Your account should be
152+
listed. **Table Editor → profiles** should have a row for you with
153+
`plan = 'free'`.
154+
155+
If step 6 shows the auth user but **no profiles row**, the
156+
`handle_new_user` trigger didn't run — most likely because you didn't
157+
run `supabase/schema.sql` yet. Run it and try a new sign-up.
158+
159+
---
160+
161+
## 5. Troubleshooting
162+
163+
| Symptom | Cause | Fix |
164+
| --- | --- | --- |
165+
| `redirect_uri_mismatch` from Google | Google's authorized redirect doesn't match | Copy the URI from the error message and add it under **Credentials → your OAuth client → Authorized redirect URIs** |
166+
| GitHub: "The redirect_uri MUST match" | Same as above, on the OAuth app page | Update **Authorization callback URL** to match exactly |
167+
| `400 Database error saving new user` | `profiles` table doesn't exist, or the trigger references columns that don't exist | Re-run `supabase/schema.sql` — it's idempotent, safe to run again |
168+
| Bounce-back lands on a blank page | Site URL not set in Supabase | Supabase → Authentication → URL Configuration → set Site URL to your deployed app URL |
169+
| Works locally, not in production | `VITE_SUPABASE_URL` / `VITE_SUPABASE_ANON_KEY` not set as GitHub secrets, OR a deploy hasn't run since they were added | Set them, then **Actions → Deploy Site → Run workflow** |
170+
| "App is blocked" Google warning | App is in Testing mode and you're not a listed Test User | Add the email under **OAuth consent screen → Test users**, or **Publish app** for real users |
171+
172+
---
173+
174+
## 6. What you never need to do
175+
176+
- You don't write any JWT verification code. Supabase fetches Google's
177+
and GitHub's public keys, verifies the upstream JWT signature, and
178+
issues you a Supabase JWT. The browser stores that one. The
179+
`useAuth.ts` hook already reads it.
180+
- You don't need to handle refresh tokens. Supabase rotates them
181+
silently inside `supabase.auth.getSession()`.
182+
- You don't add a backend just for auth. The whole flow is
183+
browser → Google → Supabase → browser. No server you run.
184+
185+
---
186+
187+
## 7. When you go live (later)
188+
189+
Two things to flip when you have a real domain:
190+
191+
1. **Google OAuth consent screen → Publishing status → Publish app**.
192+
Removes the "Testing" banner and lets anyone sign in. (Google may
193+
ask for verification; for a personal app reading basic profile only,
194+
verification is usually not required.)
195+
2. **Supabase → Authentication → URL Configuration → Site URL**:
196+
change to your real domain. Update Google's
197+
"Authorized JavaScript origins" and "redirect URIs" to match.
198+
199+
That's it.

0 commit comments

Comments
 (0)