如何設定 Nextcloud 郵件應用程式以使用 OAuth2 身份驗證

OAuth2 是連接許多託管郵件帳戶到 Nextcloud Mail 的首選方式，因為郵件提供者會頒發令牌，而無需 Nextcloud 繼續使用使用者的常規郵箱密碼。然而，在實踐中，衡量設定是否完善的標準並非 OAuth 授權視窗是否成功關閉。真正有效的結果是 Nextcloud Mail 可以透過 IMAP 載入資料夾、透過 SMTP 發送郵件、無需使用者重複提示即可刷新身分驗證，並且在第一個存取權杖過期後仍能繼續正常運作。

本指南涵蓋了 Nextcloud Mail 文件中明確說明的兩種 OAuth 整合：Google 帳戶和託管的 Microsoft Outlook/Microsoft 365 帳戶。截至 2026 年 10 月 6 日，Nextcloud 應用程式商店將 Mail 5.12.3 列為 Nextcloud 32 至 35 的穩定版本，而目前的管理手冊則記錄了 Google OAuth 和 Microsoft XOAUTH2 的配置。如果您正在執行較舊的 Mail 版本，請在 Nextcloud 伺服器支援的相容範圍內進行更新，然後重新檢查可能已經變更的問題。

本文所使用的官方參考資料包括Nextcloud Mail 管理手冊、Nextcloud Mail 應用程式商店頁面、Google 的IMAP、POP 和 SMTP OAuth 文件以及 Microsoft 的IMAP 和 SMTP OAuth 文件。

成功的 Nextcloud Mail OAuth2 設定應該實現什麼目標

在變更提供者設定之前，請先定義您期望的結果。一個有效的配置應該通過以下所有檢查：

• 提供者會將使用者重新導向回為 OAuth 用戶端配置的 Nextcloud 重定向 URI。
• Nextcloud Mail 無需再次輸入郵箱密碼即可開啟郵箱並列出資料夾。
• 新郵件透過 IMAP 到達，手動刷新收件匣後會更新，不會出現驗證錯誤。
• 透過 Nextcloud Mail 發送的測試郵件會被 SMTP 接收，並出現在「已傳送」資料夾中。
• 在短暫的存取令牌過期後，帳戶會透過刷新令牌繼續工作，而不是每次都強制重新登入。

如果設定程序僅通過了同意確認步驟，但未通過 IMAP 和 SMTP 測試，則視為設定不完整。 OAuth 授權和郵件協定存取是相關但獨立的階段。

步驟 1：確認您的提供者與受支援的 OAuth 路徑匹配

Nextcloud Mail 目前內建了 Google 和 Microsoft 帳戶的 OAuth 處理功能。 Google 的郵件伺服器支援 OAuth 2.0，並使用 SASL XOAUTH2 協定進行 IMAP 和 SMTP 通訊。 Microsoft 的文件中也提供了對 Microsoft 365 和 Outlook.com 中 IMAP、POP 和 SMTP 協定的 OAuth2 支援。 Nextcloud 透過郵件協定進行驗證時，會使用提供者所頒發的令牌。

不要想當然地認為任何支援 OpenID Connect 或 OAuth2 的郵件伺服器都可以直接整合到同一個介面中。 Nextcloud Mail 2026 年提出的針對通用第三方 OAuth/OpenID 提供者的增強功能請求，目前仍處於增強功能階段，而非已記錄的通用配置路徑。如果您的提供者既不是 Google 也不是 Microsoft，請在圍繞 OAuth2 建置生產環境部署之前，請務必確認該提供者是否完全支援 OAuth2。相關專案討論請參考Nextcloud Mail 通用 OAuth2 增強功能問題。

配置 Gmail 使用 OAuth2

步驟 2：從 Nextcloud 複製 Gmail 重新導向 URI

以 Nextcloud 管理員身份登錄，開啟管理設置，前往「群組軟體」，找到Gmail 整合。 Nextcloud 管理手冊指出，需要在此部分輸入 Google 用戶端 ID 和用戶端金鑰。設定 Google 時，請使用您自己的實例顯示的重定向 URI；不要根據範例重新建置路徑，因為反向代理、網站根目錄變更和部署佈局都可能影響外部可見的 URL。

品質檢查：重定向 URI 應使用您的生產環境 HTTPS 主機名，並且應可從使用者瀏覽器存取。如果 Nextcloud 顯示內部主機名，而使用者存取的是公用主機名，請先修正 Nextcloud/代理 URL 設定。 OAuth 不會補償不符的公共 URL。

步驟 3：建立 Google OAuth 用戶端

在 Google Cloud 中，為專案設定 Google Auth Platform/授權設置，並為Web 應用程式建立 OAuth 用戶端。將從 Nextcloud 複製的重定向 URI 新增為已授權的重定向 URI。 Google 要求授權請求中的重定向 URI 與已授權的值完全匹配；協定、大小寫、路徑和尾部斜線都至關重要。 Google 在「為 Web 伺服器應用程式使用 OAuth 2.0」文件中記錄了此行為。

從合規性角度來看，Gmail 郵件存取權限至關重要。 Google 將https://mail.google.com/包括 IMAP、SMTP 和 POP3 使用在內的廣泛範圍歸類為受限範圍。根據應用是內部使用、測試階段還是計畫用於更廣泛的生產環境，Google 的驗證要求可能適用。在向大量使用者開放之前，請務必查看 Google 的受限範圍文件和OAuth 應用程式驗證指南。

步驟 4：將 Google 用戶端 ID 和金鑰儲存到 Nextcloud 中

返回「管理設定」>「群組軟體」>「Gmail 整合」，貼上 Google 用戶端 ID 和用戶端金鑰，然後儲存。請勿在螢幕截圖、工單、shell 歷史記錄或共享筆記中洩漏密鑰。如果您之後更換了 OAuth 用戶端金鑰，請及時更新 Nextcloud 並安排對現有帳戶進行受控驗證。

步驟 5：新增 Gmail 帳戶並完成同意

以使用者身分開啟 Nextcloud Mail 並新增 Gmail 帳戶。目前郵件代碼透過標準的 Gmail IMAP/SMTP 主機識別 Gmail，並在管理員配置了 Google OAuth 後將身份驗證方法切換到 XOAUTH2。 Google 文件imap.gmail.com:993支援透過 SSL 和 TLS 在支援的 SMTP 連接埠上進行 IMAP 通訊smtp.gmail.com。

繼續登入 Google 帳戶並查看同意畫面。如果 OAuth 應用程式尚未針對所使用的範圍和受眾進行配置或驗證，則提供者可能會顯示警告或限制存取權限。

不要止步於「帳戶已連線」。打開收件匣，至少打開一封郵件，向您控制的第二個郵箱發送一封郵件，回覆該郵件，並確認往返過程。這項測試比單純的 OAuth 重定向更有說服力。

設定 Microsoft 365 或 Outlook 的 OAuth2

步驟 6：在 Microsoft Entra 中註冊應用程式

開啟 Microsoft Entra 管理中心並建立應用程式註冊。 Nextcloud 指南建議管理員選擇允許組織和個人 Microsoft 帳戶的帳戶類型（在其通用範例中），並配置從 Nextcloud 複製的Web重新導向 URI。如果您的組織有意使用單一租戶，請勿盲目複製多租戶範例：請確保支援的帳戶類型和租戶設定與您的身分策略保持一致。

微軟要求應用程式必須註冊重定向 URI。不匹配可能會導致錯誤，例如AADSTS50011…。微軟目前的指南請參閱「重定向 URI 最佳實務與限制」。

步驟 7：記錄客戶端 ID 並建立客戶端金鑰

複製應用程式（客戶端）ID。然後開啟「憑證和機密」，建立一個新的客戶端金鑰，並立即複製金鑰值。微軟指出，離開此頁面後，該值將不再顯示。此外，微軟在其目前的應用程式註冊文件中，將客戶端金鑰的有效期限制為 24 個月或更短，並建議使用更短的過期時間。

此過期日期是運行依賴項，而非一次性安裝細節。請將密鑰過期日期納入貴組織的憑證輪替流程。否則，看似穩定的 Nextcloud Mail 部署可能會因令牌刷新無法完成而導致失敗。

步驟 8：在 Nextcloud 中輸入 Microsoft 憑證

在 Nextcloud 管理設定中，開啟「群件」和「Microsoft 整合」區域。輸入客戶端 ID 和客戶端金鑰。官方 Nextcloud 指南使用租用戶值common來配置通用的託管 Outlook 配置，並明確警告說，除非您同時更改了支援的帳戶類型，否則自訂租用戶 ID 不在該基本指南的適用範圍內。

對於底層協定權限，Microsoft 文件中列出了委派範圍，包括https://outlook.office.com/IMAP.AccessAsUser.AllIMAP 和https://outlook.office.com/SMTP.SendSMTP 的委派範圍，以及offline_access何時需要刷新令牌。 Nextcloud 會建立提供者流程；您仍應確認租用戶策略和條件存取規則允許所要求的委派存取權限。

步驟 9：連接 Microsoft 帳戶並驗證信箱

在 Nextcloud Mail 中新增 Outlook 或 Microsoft 365 位址，然後繼續完成 Microsoft 登入/授權流程。 Nextcloud 管理手冊解釋說，一旦配置 OAuth，帳戶設定期間輸入的密碼將被丟棄，系統會提示使用者進行 Microsoft 授權。

再次強調，可見的同意結果只是一個中間訊號。請確認資料夾清單已載入正常，測試郵件可以讀取，郵件可以傳送，並且「已傳送」資料夾中包含預期副本。

如何判斷 OAuth2 是否真正健康

何時改變策略

當重定向 URI、支援的帳戶受眾、租戶設定或授權配置與您的部署不符時，請變更 OAuth 應用程式配置。重複重試無法修復結構性不符。

當 Nextcloud 產生錯誤的內部、HTTP 或其他公用回呼位址時，請變更部署 URL/代理設定。首先修復規範的外部 URL，然後重新建立或更新提供者重新導向 URI。

當條件存取、管理員同意策略、Google 應用程式驗證或受限範圍阻止使用者完成授權時，請使用提供者特定的管理機制，而不是通用的 OAuth 假設。這些控制措施是身分提供者有意強制執行的。

只有當服務提供者和您的安全策略明確允許時，才可考慮使用其他身分驗證方法。例如，Nextcloud Mail 介面指出，如果未配置 Google OAuth 且 Google 帳戶啟用了雙重驗證，則可以使用 Google 應用程式密碼作為替代方案。但這與 OAuth2 並不等同，不應僅僅因為設置更簡單就將其視為組織範圍內的首選替代方案。

已知限制和 2026 年故障排除注意事項

Nextcloud Mail 專案歷史記錄中存在一個重要的診斷注意事項。 2026 年 7 月，維護人員確認了一份錯誤報告，該報告指出，即使提供者端的 OAuth 錯誤，仍可能將「帳戶已連線」重新導向頁面顯示為授權成功。該報告直接涉及 Microsoft，並指出 Google 也存在相同的控制器模式。另一份 2026 年的報告描述了帳戶刷新令牌失效後難以重新連線的問題。這些報表皆針對 Mail 5.10.7 及更早版本的程式碼；不要假設所有版本都會永久受到影響，但也不要將重定向頁面作為成功的唯一依據。

您可以查看專案的OAuth 重定向錯誤處理問題和OAuth 重新連線問題。如果您正在排查目前版本的問題，請先檢查已安裝的郵件版本和最新的發行說明，然後再套用為舊分支所寫的解決方法。

最終驗證清單

• 請確認已安裝的郵件應用程式版本與您的 Nextcloud 伺服器版本相容。
• 使用 Nextcloud 實例實際顯示的重定向 URI，並將其準確地註冊到提供者處。
• 對於 Google，請驗證 OAuth 受眾、同意配置、受限範圍要求以及生產/測試狀態。
• 對於 Microsoft，請驗證支援的帳戶類型、租用戶選擇、用戶端 ID、用戶端金鑰有效性以及任何條件存取或管理員同意策略。
• 在全面推廣配置之前，先連接一個試點帳戶。
• 測試收件匣載入、郵件讀取、傳送、已傳送郵件資料夾儲存空間以及後續令牌刷新。
• 記錄客戶端金鑰的過期時間和所有權，以避免憑證輪替導致計劃外停機。

OAuth2 改進了 Nextcloud Mail 的身份驗證模型，但並不能消除管理提供者策略、重定向 URI、應用程式憑證和郵件協定存取權限的必要性。當整個流程（提供者授權、令牌刷新、IMAP 取得和 SMTP 傳送）在適用於使用者的政策下都能如預期運作時，設定即可投入生產環境。