使用 OAuth2 將 Gmail 或 Microsoft 365 連接到 Nextcloud Mail

若要使用 OAuth2 將 Gmail 或 Microsoft 365 連接到 Nextcloud Mail，請先向郵件提供者註冊一個 Web 應用程序，將 Nextcloud Mail 的重定向 URI 複製到該註冊資訊中，並將客戶端 ID 和金鑰保存在 Nextcloud 的群組管理設定中。然後在郵件應用程式中連接郵箱，並批准提供者的登入提示。成功的設定必須能夠載入收到的郵件並發送測試郵件，而不僅僅是顯示授權成功的畫面。

請檢查您的帳戶和 Nextcloud 安裝是否符合此方法。

Nextcloud Mail 使用 IMAP 協定讀取郵件，使用 SMTP 協定傳送郵件。 OAuth2 從身分提供者取得授權；XOAUTH2 是郵件用戶端用來提供這些郵件服務存取權杖的機制。它並不能將 Nextcloud 登入轉換為適用於所有郵件伺服器的通用單一登入。

Nextcloud 目前的管理文件詳細介紹了 Gmail OAuth 和 Microsoft Outlook XOAUTH2 的整合。 Microsoft 支援是在 Mail 3.0.0 版本中新增的；選單措詞可能會因 Mail 和 Nextcloud 版本而異。本指南基於Nextcloud 35 Mail 管理手冊，截至 2026 年 10 月為最新版本。

• 使用可在瀏覽器中穩定開啟的 HTTPS Nextcloud URL，前提是已安裝並啟用郵件應用程式。
• 擁有 Nextcloud 管理員權限，並獲准在 Google Cloud 或 Microsoft Entra 中註冊 OAuth 應用程式。
• 了解該帳號是 Gmail/Google Workspace、Outlook.com 還是託管在 Exchange Online 中的 Microsoft 365 信箱。
• 確認服務提供者允許 IMAP 訪問，並且對於發送操作，允許按照組織政策進行身份驗證的 SMTP 連線。

重要限制： Nextcloud Mail 的 Gmail/Microsoft 設定介面不會自動支援接受 OAuth2 的自訂 IMAP 提供者。 Nextcloud Mail 針對通用 OAuth2 提供者的功能請求中對此差異進行了說明。對於其他供應商，請查看您使用的 Mail 版本及其支援的驗證方法，而不是輸入不相關的 Google 或 Microsoft 憑證。

使用正確的重定向 URI 註冊 OAuth 用戶端

Gmail 或 Google Workspace

1. 在 Nextcloud 中，以管理員身分登錄，開啟「管理設定」→「群組軟體」，找到Gmail 整合。複製您的實例顯示的重定向 URI。不要想當然地認為從其他人的安裝複製的 URL 是正確的。
2. 開啟Google Cloud 控制台並選擇或建立專案。根據您的 Workspace 組織或外部用戶，設定 Google Auth Platform 的同意/品牌和受眾群體設定；如果應用程式仍處於測試階段，請新增測試用戶。
3. 建立一個類型為Web 應用程式的 OAuth 用戶端。將 Nextcloud 的完整 URL 填入「已授權重新導向 URI」中，然後安全地儲存用戶端 ID 和用戶端金鑰。 Google 要求重定向 URI 必須完全匹配，包括協定、路徑、大小寫和尾部斜線。
4. 請審查授權範圍和發布要求。 Gmail IMAP 和 SMTP OAuth 存取使用https://mail.google.com/廣泛的受限權限，並受 Google 使用者資料和驗證政策的約束。管理員必須確定擬議用途是否符合這些要求。

Google 在其OAuth2 Web 應用程式說明以及Gmail 的 XOAUTH2 範圍和協定中記錄了 Web 伺服器註冊流程。測試配置有助於初始驗證，但通常情況下，在請求存取 Gmail 郵件時，外部 OAuth 應用程式在測試模式下收到的刷新令牌會在七天後過期。請參閱Google 的令牌過期指南。因此，每週重複重新授權可能表示存在發布狀態限制，而不是 IMAP 密碼錯誤。

Microsoft 365 或 Outlook.com

1. 在 Nextcloud 的管理設定 → 群組中，找到Microsoft 整合並複製顯示的重定向 URI。
2. 在Microsoft Entra 管理中心，前往「應用程式註冊」並建立註冊。對於 Nextcloud 標準指南中所述的帳戶類型，選擇組織帳戶和個人 Microsoft 帳戶；使用網路重新導向平台，並準確輸入 Nextcloud 的 URI。
3. 複製應用程式（客戶端）ID。在「憑證和金鑰」下，建立一個客戶端密鑰，並立即複製其值，而不是密鑰標識符。將密鑰的過期時間記錄在您的維運行事曆中。
4. 使用提供者 IMAP 和 SMTP OAuth 流程所需的郵件相關委派權限，並在必要時獲得組織同意。 Microsoft 文件中提供了相關權限範圍IMAP.AccessAsUser.All以及SMTP.Send刷新offline_access令牌的權限。請勿將這些協定權限與 Microsoft Graph 的 Mail.Read/Mail.Send 權限混為一談。

有關註冊詳情，請參閱Microsoft 應用註冊文件和Exchange Online 的 IMAP/SMTP OAuth 說明。 Nextcloud 文件中提供的通用設定將租用戶欄位留空common。只有在管理員驗證了相關的帳戶類型和策略變更後，才應使用租用戶特定的值或更小的支援範圍。

將憑證儲存到 Nextcloud 並連接郵箱

1. 返回管理設定 → 群件。將提供者的客戶端 ID 和客戶端金鑰貼上到對應的Gmail 整合或Microsoft 整合部分，然後儲存。切勿將金鑰放入重定向 URI 字段，也不要將其發佈到螢幕截圖、工單或版本控制系統中。
2. 以目標郵箱使用者登入，開啟「郵件」應用程式，然後選擇新增郵件帳戶。輸入電子郵件地址，先選擇自動帳戶配置，然後開始連線。 Nextcloud 文件中記錄的 Microsoft 流程可能仍會顯示密碼欄位；設定提供者 OAuth 時，輸入的佔位符將被丟棄。請勿隨意替換為真實的帳戶密碼。
3. 在服務提供者彈出的視窗中，選擇正確的 Google 或 Microsoft 身份，查看請求的存取權限，並在獲得組織批准後授予權限。允許瀏覽器彈出窗口，並在服務提供者重定向後返回到原始的 Nextcloud 標籤頁。
4. 如果自動設定選擇了錯誤的伺服器，請檢查該特定提供者的 IMAP 和 SMTP 主機名稱以及加密選項。 OAuth 按鈕與已知的 Gmail/Microsoft 端點關聯；手動輸入無關的主機名稱可能無法啟動預期的登入流程。

在 Nextcloud 郵件帳戶表單中，已設定 OAuth 的 Google 端點會顯示「使用 Google 登入」，而 Microsoft 端點則會顯示「使用 Microsoft 登入」。 Nextcloud郵件帳戶表單的原始碼記錄了這些條件標籤。出現特定提供者的按鈕是 Nextcloud 已識別預期整合的有用早期跡象，但這並不代表授權或郵箱存取已完成。

依故障發生的階段解決故障

微軟在其 Exchange Online SMTP 驗證文件中解釋了 SMTP 驗證控制，包括郵箱層級的覆蓋設定。切勿為了讓一個郵箱正常運作而全域降低郵件安全性；如果策略禁止使用該協議，請改用經批准的郵件用戶端或組織支援的工作流程。

核實郵件雙向流動狀況

1. 開啟 Nextcloud 郵件收件匣，重新整理頁面，確認最近收到的郵件顯示預期的寄件者、主題和內容。
2. 向您控制的另一個郵箱發送一封簡短的測試郵件。驗證郵件是否送達，然後檢查 Nextcloud Mail 中的「已傳送郵件」資料夾。這樣可以區分 SMTP 權限問題和 IMAP 同步問題。
3. 登出登入並重新登錄，然後重新開啟郵件應用程式。對於正式部署，請在存取令牌正常刷新後再次檢查；立即成功並不代表令牌長期有效。

如果收件匣仍然無法同步，Nextcloud 文件occ mail:account:export提供了尋找郵件帳號 ID 的方法，occ mail:account:sync -vvv ACCOUNT_ID以便進行針對性故障排除。其群組故障排除手冊還解釋了每個帳戶的 IMAP/SMTP 偵錯日誌記錄，並警告日誌可能包含敏感資訊。請僅捕獲所需信息，在共享之前編輯令牌和地址，並在共享後關閉詳細調試模式。

當提供者同意完成、郵件應用程式可以檢索目前郵件、外寄郵件能夠送達目的地且連線保持可用狀態而無需重複授權提示時，即表示設定已準備就緒。如果上述任何一項檢查失敗，請先排查該特定階段的問題，而不要立即重新建立整個 OAuth 應用程式。