OAuth Sign-In Setup (Google & Apple)

This app supports Sign in with Google and Sign in with Apple. The code is already implemented: you only need to create credentials in each provider's console, add the right URLs and IDs to your config, and it will work.

This guide is for developers who need to configure or reconfigure OAuth from scratch (e.g. when creating a new app or moving to production).

Overview

After configuration, the login/signup page shows working Google and Apple buttons; choosing a role (Customer / Service provider) and signing in sends the token to the backend and redirects to the correct dashboard.

Google Sign-In

1. Create credentials (Google Cloud Console)

1. Go to Google Cloud Console → APIs & Services → Credentials.
2. Create or select a project for your application.
3. Click Create credentials → OAuth client ID.
4. If prompted, configure the OAuth consent screen (e.g. External, app name, support email).
5. Application type: Web application.
6. Name: e.g. Slortfolio Web or your app name.
7. Authorized JavaScript origins – add every origin where your frontend runs:
   • Local: http://localhost:3000 and http://127.0.0.1:3000
   • Production: https://yourdomain.com (and https://www.yourdomain.com if you use it)
8. Authorized redirect URIs – optional for the client-side flow we use; you can leave default or add the same URLs if required.
9. Click Create. Copy the Client ID (e.g. 123456789-xxx.apps.googleusercontent.com).

2. Set environment variables

Frontend (needed for the "Choose an account" popup):

• With Docker: ensure the frontend sees the variable. Options:
  • Put in root .env: NEXT_PUBLIC_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com (and reference it in docker-compose.yml, which is already set up), or
  • Put in fadefolio-frontend/.env.local: NEXT_PUBLIC_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
• Without Docker: put in fadefolio-frontend/.env.local.

Backend (verifies the Google ID token):

• With Docker: in root .env: GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
• Without Docker: set GOOGLE_CLIENT_ID in the backend environment (e.g. .env in fadefolio-backend).

Restart the frontend (and backend if you changed backend env) after editing.

3. Verify

Open the app's login page, choose Customer or Service provider, and click Sign in with Google. You should see Google's account picker and, after sign-in, be redirected into the app.

Troubleshooting Google Sign-In

• "The given origin is not allowed for the given client ID" (403)
  Your frontend URL is not in the OAuth client’s Authorized JavaScript origins. In Google Cloud Console → Credentials, open your Web application OAuth 2.0 Client ID and add:

  • http://localhost:3000
  • http://127.0.0.1:3000 (if you use that)
  • Your production origin, e.g. https://yourdomain.com
    Save and try again (no code change needed).

• Backend returns 400 "Invalid Google ID token" or 500

  • Ensure backend GOOGLE_CLIENT_ID is the same as the frontend NEXT_PUBLIC_GOOGLE_CLIENT_ID (same Web client ID from the console).
  • If the frontend runs on a different port or host, add that origin in Google Console and in the backend CORS_ORIGINS env (e.g. CORS_ORIGINS=http://localhost:3000,https://myapp.example.com).

Apple Sign-In

Apple requires an App ID (with Sign in with Apple enabled) and a Services ID (used as the "Client ID" for the web). The Return URL must match exactly what the app uses.

1. Apple Developer account

Use an Apple Developer account (Account Holder or Admin for creating identifiers).

2. Enable Sign in with Apple on your App ID

1. Go to developer.apple.com → Account → Certificates, Identifiers & Profiles → Identifiers.
2. Open your App ID (or create one: + → App IDs → App → enable Sign in with Apple).
3. Under Capabilities, enable Sign in with Apple → Save.

3. Create a Services ID (web "Client ID")

1. In Identifiers, use the filter and select Services IDs.
2. Click + → Services IDs → Continue.
3. Description: e.g. My App Web.
4. Identifier: reverse-domain style, e.g. com.yourcompany.yourapp.service.
   This value is your Apple Client ID – you'll use it in both backend and frontend env.
5. Enable Sign in with Apple → Configure.
6. Primary App ID: select the App ID from step 2.
7. Domains and Subdomains: hostname only, no https:// or path, e.g. www.yourdomain.com or yourdomain.com.
8. Return URLs: add the exact callback URL the app uses. The app uses the path /auth/apple/callback, so add:
   • Production: https://www.yourdomain.com/auth/apple/callback (or https://yourdomain.com/auth/apple/callback if that's your canonical URL).
   • For local testing, Apple does not allow http://localhost. Use an HTTPS tunnel (e.g. ngrok) and add e.g. https://your-subdomain.ngrok.io/auth/apple/callback.
9. Save the configuration → Continue → Register.

4. Set environment variables

Backend (verifies the Apple ID token):

• With Docker: in root .env: APPLE_CLIENT_ID=com.yourcompany.yourapp.service (use your Services ID).
• Without Docker: set APPLE_CLIENT_ID in the backend environment.

Frontend (initiates the Apple popup):

• With Docker: in root .env: NEXT_PUBLIC_APPLE_CLIENT_ID=com.yourcompany.yourapp.service (same value), or in fadefolio-frontend/.env.local.
• Without Docker: in fadefolio-frontend/.env.local: NEXT_PUBLIC_APPLE_CLIENT_ID=com.yourcompany.yourapp.service.

Restart backend and frontend after changing env.

5. Verify

Deploy (or use your tunnel) so the app is served from the domain in Domains and Subdomains and Return URLs. Open the login page, choose Customer or Service provider, and click Apple. The Apple popup should open; after sign-in, the popup closes and you're logged in.

How to do stuff (quick reference)

Run the app

• With Docker (from repo root):
  docker compose up --build (first time or after dependency changes), then docker compose up.
• Frontend: http://localhost:3000
• Backend / Swagger: http://localhost:8000 and http://localhost:8000/docs

Environment files

• Repo root .env – used by Docker Compose; set GOOGLE_CLIENT_ID, APPLE_CLIENT_ID, NEXT_PUBLIC_GOOGLE_CLIENT_ID, NEXT_PUBLIC_APPLE_CLIENT_ID, NEXT_PUBLIC_API_BASE_URL as needed.
• fadefolio-frontend/.env.local – Next.js env (gitignored); use for NEXT_PUBLIC_* when not using Docker or to override.
• fadefolio-frontend/.env.example – template; copy to .env.local and fill in values.

Run tests

• Backend (Docker):
  docker compose build backend && docker compose run --rm backend sh -c "alembic upgrade head && python -m pytest tests/ -v"
• Frontend typecheck:
  cd fadefolio-frontend && npm run typecheck

Where OAuth is implemented

• Frontend:
  • fadefolio-frontend/app/components/SocialAuthButtons.tsx – Google and Apple buttons, popup flow, call to POST /auth/oauth.
  • fadefolio-frontend/app/auth/apple/callback/route.ts – Apple callback; receives Apple's POST and returns HTML that sends the ID token back to the opener window.
• Backend:
  • fadefolio-backend/app/auth/routes.py – POST /auth/oauth accepts provider, id_token, and optional role; verifies token and issues app tokens.
  • fadefolio-backend/app/auth/services.py – verify_google_id_token, verify_apple_id_token.

Checklist for a new app / production

1. Google: Create Web OAuth Client ID, add production origin(s), set GOOGLE_CLIENT_ID and NEXT_PUBLIC_GOOGLE_CLIENT_ID.
2. Apple: Create or use App ID with Sign in with Apple; create Services ID; set Domains and exact Return URL (https://yourdomain.com/auth/apple/callback); set APPLE_CLIENT_ID and NEXT_PUBLIC_APPLE_CLIENT_ID.
3. Restart backend and frontend (or rebuild/restart containers) after env changes.

Once these URLs and IDs are in place, sign-in should work without further code changes.