Configure Google OAuth

Saavo supports regular Google OAuth sign-in and optional Google One Tap. Both can use the same Web application Client ID, but their configuration requirements differ:

• Regular Google sign-in requires a complete Authorized redirect URI.
• Google One Tap also requires the current site in Authorized JavaScript origins and must be explicitly enabled in Saavo's configuration.

The template's regular sign-in flow requests only openid, email, and profile to identify the user and obtain their email address, name, and avatar. It does not request Gmail, Drive, or similar permissions.

Prepare the URLs

The default Google sign-in callback path is in config/deploy.ts:

ui: {
    oauthRedirectTo: {
        github: '/api/auth/oauth2/github',
        google: '/api/auth/oauth2/google',
    },
},

For WebpageToPDF, prepare:

A JavaScript origin contains only the protocol, hostname, and port, with no path. A redirect URI must include the full callback path. They are not interchangeable.

Run npm run dev first and use the local address shown in the terminal. If Vite changes ports, update both the local origin and redirect URI in Google Cloud. For production, use VITE_SITE_URL from .env.production.

Create a Google Cloud project

Google continues to adjust the Branding, Audience, and Data Access UI. See the Google Identity Services setup guide for current navigation and field meanings.

Create an OAuth client

http://127.0.0.1:5173
https://webpagetopdf.dev

http://127.0.0.1:5173/api/auth/oauth2/google
https://webpagetopdf.dev/api/auth/oauth2/google

See Get your Google API client ID and Manage OAuth clients for Google's full requirements for Web application clients and URL formats.

Configure the local environment

In .env in the project root, enter:

GOOGLE_CLIENT_ID="Your Google Client ID"
GOOGLE_CLIENT_SECRET="Your Google Client Secret"

Save and restart the development server:

npm run doctor
npm run dev

The sign-in and sign-up pages enable Google sign-in when both credentials are present. A Client ID alone is not enough. Regular OAuth sign-in requires the server to exchange the authorization code using the Client Secret.

Configure production

After the initial deployment, enter the production credentials in .env.production:

GOOGLE_CLIENT_ID="Your production Google Client ID"
GOOGLE_CLIENT_SECRET="Your production Google Client Secret"

Then run:

npm run doctor:remote
npm run deploy:update

Deployment synchronizes the Client ID to Cloudflare as a Worker variable and the Client Secret as an encrypted secret. Do not change only the Cloudflare Dashboard. Saavo continues to use .env.production as the source of production settings.

If the initial deployment is not complete, you can leave the OAuth variables empty and run npm run deploy:init. Once you have the actual workers.dev address, add its origin and redirect URI to Google Cloud, fill in .env.production, and run npm run deploy:update.

When you switch to a custom domain later, complete all three steps:

1. Add the new origin to Authorized JavaScript origins in Google Cloud.
2. Add the new domain's full Google callback URL to Authorized redirect URIs.
3. Confirm that VITE_SITE_URL in .env.production uses the new origin, then redeploy.

Decide whether to enable Google One Tap

Once regular Google sign-in is configured, users can start Google authorization from the sign-in or sign-up page. One Tap is an additional feature, disabled by default:

auth: {
    enableGoogleOneTap: false,
},

To enable it, change the configuration to:

auth: {
    enableGoogleOneTap: true,
},

Before enabling it, confirm that the current page's origin is registered under Google Cloud's Authorized JavaScript origins. Production must use HTTPS. Local development can use http://localhost or a loopback address. After saving, restart npm run dev locally or run npm run deploy:update for production.

Browser privacy settings, third-party cookie policies, FedCM settings, or extensions may block One Tap. Regular Google sign-in on the sign-in page should still work if One Tap does not appear. Do not make the One Tap prompt your only acceptance check.

Verify Google sign-in

Complete at least these checks:

1. Open the sign-in page and confirm that the Google option appears.
2. Click it and confirm that Google shows the correct app name and requested permissions.
3. Approve sign-in and confirm that the browser returns to Saavo with an authenticated session.
4. Sign out, then sign in again with the same Google account and confirm that no duplicate user is created.
5. Test new-user registration with another Google account allowed to access the app.
6. If One Tap is enabled, test its prompt separately in a browser signed in to Google but not to your site.

Local development, workers.dev, and the production domain use different origins. Complete a full test at least on the domain you will ultimately make available to users.

Common issues