為 OpenConnector 建立 Google OAuth app

自架 OOMOL OpenConnector 需要連接使用者的 Google 帳號時，請使用 Google OAuth app。一個 Google Cloud project 可以保存 Gmail、Google Drive、Google Calendar、Google Sheets、Google Docs、Google Slides、YouTube、Google Analytics、Google BigQuery 等 provider 使用的 OAuth client。

OpenConnector services

Service ID	Provider
`gmail`	Gmail
`googledrive`	Google Drive
`googlecalendar`	Google Calendar
`googlesheets`	Google Sheets
`googledocs`	Google Docs
`googleslides`	Google Slides
`youtube`	YouTube
`google_analytics`	Google Analytics
`google_bigquery`	Google BigQuery

每個 service 在 OpenConnector 中會個別保存 OAuth client config。如果同一個 Google OAuth client 已允許相同的 redirect URI，且已啟用所需的 API 和 scopes，你可以把同一組 client ID / client secret 儲存給多個 Google service。

前置條件

一個正在運作的 OpenConnector runtime。
可以存取 Google Cloud project 的 Google 帳號。
有權限設定 OAuth consent、啟用 APIs、建立 OAuth credentials。
使用者在瀏覽器中開啟的 OpenConnector origin，例如 http://localhost:3000 或 https://connect.example.com。

第 1 步：確定 OpenConnector callback URL

本機測試時使用：

http://localhost:3000/oauth/callback

公開 runtime 請先設定 OOMOL_CONNECT_ORIGIN，重新啟動後使用：

https://connect.example.com/oauth/callback

第 2 步：準備 Google Cloud project

在 Google Cloud Console 中：

建立或選擇一個 project。
開啟 APIs & Services。
啟用 OpenConnector service 需要的 API，例如 Gmail API、Google Drive API、Google Calendar API、Google Sheets API、YouTube Data API、Google Analytics Data API 或 BigQuery API。
開啟 OAuth consent screen，依 Google 要求設定 app name、support email、audience、contact information 和 test users。
新增 OpenConnector service 需要的 scopes，或在啟動 OAuth 授權時由 Google 顯示這些 scopes。

敏感或受限 scopes 在廣泛正式使用前可能需要 Google verification。本機使用或內部測試時，請依你的 Google 帳號類型使用 testing 或 internal 狀態。

第 3 步：建立 OAuth credentials

在 APIs & Services > Credentials 中：

選擇 Create credentials。
選擇 OAuth client ID。
Application type 選擇 Web application。
在 authorized redirect URIs 中新增 OpenConnector 的正確 callback URL。
建立 client。
複製 client ID 和 client secret。

Google 官方文件請見 Using OAuth 2.0 for Web Server Applications。

第 4 步：在 OpenConnector 中儲存 client

建議優先在 OpenConnector Web 控制台設定目標 service：

開啟 OpenConnector Web 控制台，例如 http://localhost:3000。
開啟 Providers，選擇 Gmail 或其他 Google provider。
點擊 Configure OAuth Client 或 Edit OAuth Client。
貼上 Google client ID 和 client secret。
點擊 Save OAuth Client。

如果要把同一個 Google OAuth client 用到其他 Google provider，請在對應的 Google provider 頁面重複這些步驟。

第 5 步：連接並測試

儲存 OAuth client 後，在 Google provider 頁面點擊 Connect。完成 Google consent，回到 OpenConnector，並確認 provider 頁面顯示帳號已連接。

Gmail 可用 gmail.get_profile 或 gmail.list_labels 做低風險測試。執行 action 前，請先在控制台 action 詳情中確認正確輸入。

疑難排解建議

現象	檢查項目
`redirect_uri_mismatch`	Google 收到的 URI 必須和 OAuth client 中的 authorized redirect URI 完全一致。確認它是 `<openconnector-origin>/oauth/callback`。
Google 顯示 app 未驗證	使用允許的 test users 測試，能使用 internal mode 時請使用 internal mode；廣泛使用前完成 Google verification。
Google 沒有發出 refresh token	重新連接帳號。需要 refresh token 的 OpenConnector Google provider 會在定義中請求 offline access 和 consent。
Google action 提示權限不足	在 Google Cloud 啟用所需 API，新增或核准所需 scope，然後重新連接帳號。
執行時用了錯誤的 Google 帳號	使用已登入目標 Google 帳號的瀏覽器 profile 重新連接。

請把 Google client secret 放在密鑰管理系統中，並在 OpenConnector 中儲存 OAuth client 前設定 OOMOL_CONNECT_ENCRYPTION_KEY。