Skip to main content

Google Login (OAuth) Configuration

Bellamy Book supports Sign in with Google using Google Identity Services. Users can log in with their Google account; the backend validates the token and creates or links the user.

Step 1: Create Google OAuth credentials​

  1. Go to Google Cloud Console.
  2. Create a project (or select an existing one).
  3. Open APIs & Services → Credentials.
  4. Click Create Credentials → OAuth client ID.
  5. If prompted, configure the OAuth consent screen:
    • Choose External (or Internal for workspace-only).
    • Fill in App name, User support email, Developer contact.
    • Add scopes if needed: email, profile, openid are typically used for login.
    • Save.
  6. Back in Create OAuth client ID:
    • Application type: Web application.
    • Name: e.g. "Bellamy Book".
    • Authorized JavaScript origins — add the URLs where your app runs:
      • Production: https://app.yourdomain.com, https://admin.yourdomain.com
      • Local: http://localhost:5173, http://localhost:8081, http://127.0.0.1:8081
    • Authorized redirect URIs — add your app’s Google callback URL so sign-in works in Safari, Android mobile web, and PWA: https://app.yourdomain.com/auth/google/callback (use your real origin). For Desktop Chrome with One Tap/popup, origins are enough; for Safari, Android (mobile web and PWA), “Add to Home Screen,” the redirect flow is used and this URI is required.
  7. Click Create and copy the Client ID and Client Secret.

Step 2: Backend configuration (.env)​

In your .env set:

VariableExampleDescription
ExternalAuth__Google__ClientId123456789-xxx.apps.googleusercontent.comOAuth 2.0 Client ID from Google.
ExternalAuth__Google__ClientSecretGOCSPX-xxxOAuth 2.0 Client secret from Google.

The backend uses the Client ID to validate the Google ID token (aud claim). Keep the Client Secret private; do not commit it to git.

Step 3: Frontend configuration (Client ID)​

The frontend needs the Client ID to load the Google Sign-In button and request credentials.

If you use pre-built Docker images​

Set ExternalAuth__Google__ClientId and ExternalAuth__Google__ClientSecret in your .env. The pre-built frontend image typically reads the Google Client ID from runtime config (same .env). Backend and frontend must use the same Client ID. If the image was built with a different Client ID, ask the publisher for an image built with your Client ID or for runtime config support.

If you build the frontend from source​

Set VITE_GOOGLE_CLIENT_ID in your frontend build env and rebuild. Set ExternalAuth__Google__ClientId in .env to the same value.

Step 4: Restart services​

After changing .env:

docker compose restart api

If you changed the frontend env, rebuild and redeploy the frontend container.

Security​

  • Do not commit ExternalAuth__Google__ClientSecret or put it in frontend code. The frontend only needs the Client ID.
  • Restrict Authorized JavaScript origins in Google Console to your real domains and localhost for dev.
  • Keep the OAuth consent screen configured (e.g. verified domain, privacy policy) if you publish to all users.

Troubleshooting​

IssueWhat to check
"Google login failed" / invalid tokenBackend and frontend must use the same Client ID. Check ExternalAuth__Google__ClientId and VITE_GOOGLE_CLIENT_ID.
"Access blocked: This app's request is invalid"In Google Console, add your app URL to Authorized JavaScript origins (e.g. https://app.yourdomain.com).
Button shows "Set VITE_GOOGLE_CLIENT_ID..."Frontend Client ID is missing or placeholder. Set VITE_GOOGLE_CLIENT_ID and rebuild, or use runtime config if supported.
403 / redirect_uri_mismatchAdd the exact redirect URI used by your app to Authorized redirect URIs in Google Console. Required for Safari, Android mobile web, and "Add to Home Screen" (PWA).
"FedCM was disabled" / "FedCM get() rejects"The app falls back to redirect-based sign-in when FedCM is disabled or on Android/Safari/PWA. Ensure Authorized redirect URIs includes https://your-app-origin/auth/google/callback.
Store app Google login stays on the mobile websiteGoogle returns to /auth/google/callback on your public site. That page must bounce state=bb-native.* into the app. Redeploy the frontend that FRONTEND_PUBLIC_URL serves. Do not add bellamybook:// as a Web-client redirect.

Mobile app​

The store app is one binary (com.bellamy.book.mobile). After a member Connects, the app reads your Web client id from GET /api/mobile/bootstrap and signs in with the same Google Web client as the website.

Google never sees a custom app scheme. The app opens Google in a browser, Google returns to your existing

https://YOUR_FRONTEND_ORIGIN/auth/google/callback

(the URI you already added for the website), and that page hands the token back to the app.

Operator checklist (Android + iOS):

  1. Configure Google for the website as in steps 1–4 above (ExternalAuth__Google__ClientId + secret, same Client ID on the frontend).

  2. In Google Cloud → Web client → Authorized redirect URIs, keep:

    https://YOUR_FRONTEND_ORIGIN/auth/google/callback

    (YOUR_FRONTEND_ORIGIN is the public site URL, e.g. https://social.example.com.)

  3. Set Frontend:BaseUrl / FRONTEND_PUBLIC_URL to that same origin so bootstrap can publish it.

  4. Members install Bellamy Book, enter your API/site URL, tap Continue with Google.

Do not create Android/iOS OAuth clients for the store app, and do not add bellamybook:// to the Web client.

If Google is not configured, the native Google button stays hidden. See Mobile App.

Next steps​