Inboxintel/docs/GOOGLE_OAUTH_SETUP.md

Google OAuth2 Setup

InboxIntel logs users in with Google only. The GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET you create here identify the application to Google — every user (you or anyone else) signs in through this one credential pair. They are required; without them nobody can log in.

1. Create the OAuth client

1. Go to the Google Cloud Console and create (or pick) a project.
2. APIs & Services → Library → enable the Gmail API.
3. APIs & Services → OAuth consent screen:
   • User type: External.
   • Fill app name, support email, developer email.
   • Scopes: add openid, email, profile, .../auth/gmail.readonly, .../auth/gmail.modify.
4. APIs & Services → Credentials → Create credentials → OAuth client ID:

   • Application type: Web application.

   • Authorized redirect URIs — add the one(s) matching how you run it:

     How you run it	Redirect URI
     Docker (frontend on :8081)	http://localhost:8081/signin-google
     Docker + top-level nginx (--profile proxy, :80)	http://localhost/signin-google
     Local dev (API via dotnet run, :5080)	http://localhost:5080/signin-google
     Production	https://your-domain/signin-google

   • Copy the generated Client ID and Client secret.

2. Put the credentials where the app reads them

Docker — in .env at the repo root:

GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxxxx

Local dev — use user-secrets so they never touch source control:

cd src/InboxIntel.Api
dotnet user-secrets init
dotnet user-secrets set "GoogleOAuth:ClientId" "xxxxx.apps.googleusercontent.com"
dotnet user-secrets set "GoogleOAuth:ClientSecret" "xxxxx"

3. Who is allowed to log in

This is controlled by the consent screen publishing status, not the app code (the code already creates a new user row per Google account — it does not restrict to one person):

• Testing (default): only Google accounts you add under Test users can sign in (max 100).
• In production (click Publish app): any Google account can sign in.

Caveat for the Gmail scopes

gmail.readonly and gmail.modify are restricted scopes. A published-but-unverified app still works, but:

• users see a "Google hasn't verified this app" warning screen, and
• you're capped at 100 users until Google verifies the app.

Removing the warning / going beyond 100 users requires Google's OAuth verification (a CASA security assessment for restricted scopes). For personal or small-team use, published-unverified (≤100 users) is usually fine.

4. Redirect URI must match exactly

The URI registered in the Console must character-for-character match what the app sends. The app builds it from the request's host + scheme; behind nginx, UseForwardedHeaders + the X-Forwarded-Proto/Host headers (already configured) make that the external URL, and nginx routes /signin-google to the API. If you get redirect_uri_mismatch, compare the URI in the browser's address bar during the error against what's registered.