Saavo

設定 Google OAuth

設定 Google Auth Platform，建立 Web 應用程式用戶端，並啟用 Saavo 的 Google 登入與 One Tap。

Saavo 支援一般的 Google OAuth 登入，也支援選用的 Google One Tap。兩種方式可以使用同一個 Web application Client ID，但設定需求不同：

  • 一般 Google 登入需要完整的 Authorized redirect URI。
  • Google One Tap 還要求目前網站列在 Authorized JavaScript origins，並且在 Saavo 設定中明確啟用。

範本的一般登入流程只要求 openid、email 和 profile，用來確認使用者身分、電子郵件地址、姓名和頭像，不會要求 Gmail、Drive 等權限。

先整理要填寫的網址

Google 登入的預設回呼路徑位於 config/deploy.ts：

config/deploy.ts
ui: {
    oauthRedirectTo: {
        github: '/api/auth/oauth2/github',
        google: '/api/auth/oauth2/google',
    },
},

以 WebpageToPDF 為例，需要準備：

環境Authorized JavaScript originAuthorized redirect URI
本機http://127.0.0.1:5173http://127.0.0.1:5173/api/auth/oauth2/google
首次部署https://<實際的 workers.dev 網域>https://<實際的 workers.dev 網域>/api/auth/oauth2/google
正式網域https://webpagetopdf.devhttps://webpagetopdf.dev/api/auth/oauth2/google

JavaScript origin 只能包含通訊協定、主機名稱和連接埠，不能有路徑。Redirect URI 則必須包含完整回呼路徑，兩者不能互換。

先執行 npm run dev，使用終端機實際顯示的本機網址。如果 Vite 更換連接埠，Google Cloud 中的本機 Origin 和 Redirect URI 也要一併更新。正式環境則以 .env.production 的 VITE_SITE_URL 為準。

建立 Google Cloud 專案

進入 Google Auth Platform

登入 Google Cloud Console，在頂端選擇既有專案，或新增專門供 WebpageToPDF 登入使用的專案，再開啟 Google Auth Platform。

選擇或建立專案

不要隨意沿用用途不明的舊專案。OAuth 品牌、使用者範圍和用戶端驗證資訊，都屬於目前的 Google Cloud 專案。如果選錯，建立的 Client ID 也會留在錯誤專案中。

在 Google Cloud 側邊欄按下 OAuth consent screen。

開啟 OAuth 同意畫面

進入 Google Auth Platform 設定頁面。

Google Auth Platform 設定

按下右側中央的 Get Started，進入詳細設定：

Google Auth Platform 專案設定

填寫應用程式名稱、選擇電子郵件地址等資訊後，前往下一步。

Google Auth Platform 目標對象設定

選擇 External，前往下一步。

Google Auth Platform 聯絡資訊

填寫聯絡資訊後，前往下一步，勾選同意條款，再按下 Create 建立。

設定 Branding

建立後會自動前往 Branding 頁面，可以在這裡補齊應用程式相關資訊。

Google Auth Platform 品牌設定

Authorized domains 是必填項目，也建議填寫其他選項，增加通過審核的機會。

填寫後按下 Save 儲存。

Google 會持續調整 Branding、Audience 和 Data Access 介面。最新入口與欄位意義，請以 Google Identity Services 設定說明為準。

建立 OAuth 用戶端

新增 Web application 用戶端

在 Google Auth Platform 開啟 Clients 頁面：

開啟 Clients 頁面

按下 Create client，Application type 選擇 Web application。名稱可以填入 Webpage to PDF。

建立 Web application 用戶端

不要選擇 Desktop app、Chrome extension 或其他類型。Saavo 的回呼由網站伺服器端接收，因此需要 Web application 用戶端。

新增 JavaScript origins

在 Authorized JavaScript origins 加入實際會顯示 Google One Tap 的網站 Origin，例如：

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

Origin 不包含結尾路徑，也不使用萬用字元。

新增 JavaScript origins

如果暫時不啟用 One Tap，一般 OAuth 登入不依賴這裡的設定。不過建議建立用戶端時一併填好，之後啟用 One Tap 就能直接使用。

新增 redirect URIs

在 Authorized redirect URIs 加入完整回呼網址，例如：

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

如果仍使用 workers.dev 網址，也要將對應的完整回呼網址加入清單。

新增 redirect URIs

Google 要求實際請求的 Redirect URI 與登記網址完全一致，包括 http 或 https、主機名稱、連接埠、大小寫、路徑和結尾斜線。

儲存 Client ID 和 Client Secret

按下 Create。建立後立即儲存 Client ID 和 Client Secret。Client ID 通常以 .apps.googleusercontent.com 結尾。

儲存 Client ID 和 Client Secret

Client Secret 只能放在伺服器端環境，不能寫入前端程式碼或提交到 Git。

Google 對 Web application 用戶端和網址格式的完整要求，請參閱 Get your Google API client ID 和 Manage OAuth clients。

設定本機環境

在專案根目錄的 .env 填入：

GOOGLE_CLIENT_ID="你的 Google Client ID"
GOOGLE_CLIENT_SECRET="你的 Google Client Secret"

儲存後，重新啟動開發伺服器：

npm run doctor
npm run dev

兩項驗證資訊都存在時，登入和註冊頁面就會啟用 Google 登入。只填 Client ID 不夠，因為一般 OAuth 登入需要伺服器端使用 Client Secret 交換授權碼。

設定正式環境

完成首次部署後，在 .env.production 填入正式環境使用的驗證資訊：

GOOGLE_CLIENT_ID="正式環境的 Google Client ID"
GOOGLE_CLIENT_SECRET="正式環境的 Google Client Secret"

接著執行：

npm run doctor:remote
npm run deploy:update

部署時，Client ID 會作為 Worker Variable，Client Secret 則作為加密 Secret，同步到 Cloudflare。不要只修改 Cloudflare Dashboard，Saavo 後續仍以 .env.production 作為正式環境設定來源。

如果尚未首次部署，可以先將 OAuth 變數留白，執行 npm run deploy:init。取得實際的 workers.dev 網址後，將對應的 Origin 和 Redirect URI 加入 Google Cloud，再填寫 .env.production，並執行 npm run deploy:update。

日後改用自訂網域時，需要同時完成三件事：

  1. 在 Google Cloud 的 Authorized JavaScript origins 加入新 Origin。
  2. 在 Authorized redirect URIs 加入新網域對應的完整 Google 回呼網址。
  3. 確認 .env.production 的 VITE_SITE_URL 已改成新 Origin，並重新部署。

是否啟用 Google One Tap

完成一般 Google 登入設定後，使用者就能從登入或註冊頁面進入 Google 授權。One Tap 是額外功能，預設關閉：

config/deploy.ts
auth: {
    enableGoogleOneTap: false,
},

如需啟用，改成：

config/deploy.ts
auth: {
    enableGoogleOneTap: true,
},

啟用前，請確認目前頁面的 Origin 已登記在 Google Cloud 的 Authorized JavaScript origins。正式環境必須使用 HTTPS，本機開發可以使用 http://localhost 或本機回送位址。儲存設定後，本機需重新啟動 npm run dev，正式環境則執行 npm run deploy:update。

One Tap 可能被瀏覽器隱私權設定、第三方 Cookie 原則、FedCM 設定或擴充功能攔截。即使沒有出現，登入頁面的一般 Google 登入仍應可用，不要只以 One Tap 是否出現作為驗收標準。

驗證 Google 登入

至少完成以下檢查：

  1. 開啟登入頁面，確認能看到 Google 登入入口。
  2. 按下入口，確認 Google 顯示的應用程式名稱和要求權限正確。
  3. 同意登入，確認瀏覽器回到 Saavo，並成功建立登入工作階段。
  4. 登出後，用同一個 Google 帳號再次登入，確認不會重複建立使用者。
  5. 使用另一個允許存取該應用程式的 Google 帳號，測試新使用者註冊。
  6. 如果啟用了 One Tap，再使用尚未登入本站、但已登入 Google 的瀏覽器，另外測試提示框。

本機、workers.dev 和正式網域使用不同的 Origin，至少要在最終對外提供的網域上完整測試一次。

常見問題