OAuth2 is the preferred way to connect many hosted mail accounts to Nextcloud Mail because the mail provider issues tokens instead of requiring Nextcloud to keep using the user’s normal mailbox password. In practice, however, a good setup is not measured by whether an OAuth consent window closes successfully. The useful outcome is that Nextcloud Mail can load folders over IMAP, send mail over SMTP, refresh authentication without repeated user prompts, and continue doing so after the first access token expires.
This guide covers the two OAuth integrations that Nextcloud Mail documents directly: Google accounts and hosted Microsoft Outlook/Microsoft 365 accounts. As of October 6, 2026, the Nextcloud App Store lists Mail 5.12.3 as the stable release for Nextcloud 32 through 35, while the current administration manual documents Google OAuth and Microsoft XOAUTH2 configuration. If you are running an older Mail release, update within the compatibility range supported by your Nextcloud server before troubleshooting behavior that may already have changed.
Official references used here include the Nextcloud Mail administration manual, the Nextcloud Mail App Store page, Google’s IMAP, POP, and SMTP OAuth documentation, and Microsoft’s OAuth documentation for IMAP and SMTP.
Before changing provider settings, define the result you expect. A working configuration should pass all of these checks:
If the setup only passes the consent-screen step but not the IMAP and SMTP tests, treat it as incomplete. OAuth authorization and mail-protocol access are related but separate stages.
Nextcloud Mail currently exposes built-in OAuth handling for Google and Microsoft accounts. Google’s mail servers support OAuth 2.0 with SASL XOAUTH2 for IMAP and SMTP. Microsoft documents OAuth2 support for IMAP, POP, and SMTP in Microsoft 365 and Outlook.com. Nextcloud then uses the provider-issued token when authenticating to the mail protocols.
Do not assume that any OpenID Connect or OAuth2-capable mail server can be dropped into the same interface. A 2026 Nextcloud Mail enhancement request for generic third-party OAuth/OpenID providers remained an enhancement rather than a documented general configuration path. If your provider is neither Google nor Microsoft, verify support for that exact provider before building a production rollout around OAuth2. The project discussion is available in the Nextcloud Mail generic OAuth2 enhancement issue.
Sign in as a Nextcloud administrator, open the administration settings, go to Groupware, and find Gmail integration. The Nextcloud administration manual says to enter a Google client ID and client secret in this section. Use the redirect URI displayed by your own instance when configuring Google; do not reconstruct the path from an example because reverse proxies, web-root changes, and deployment layout can affect the externally visible URL.
Quality check: the redirect URI should use your production HTTPS hostname and should be reachable from the user’s browser. If Nextcloud shows an internal host name while users access a public host name, correct the Nextcloud/proxy URL configuration first. OAuth will not compensate for a mismatched public URL.
In Google Cloud, configure the Google Auth Platform/consent settings for the project and create an OAuth client for a Web application. Add the redirect URI copied from Nextcloud as an authorized redirect URI. Google requires the redirect URI in the authorization request to match an authorized value exactly; scheme, case, path, and trailing slash matter. Google documents this behavior in Using OAuth 2.0 for Web Server Applications.
Gmail mail access is important from a compliance perspective. Google classifies the broad https://mail.google.com/ scope, including IMAP, SMTP, and POP3 usage, as a restricted scope. Depending on whether the app is internal, in testing, or intended for broader production use, Google verification requirements can apply. Review Google’s restricted scopes documentation and OAuth app verification guidance before onboarding a large user population.
ارجع إلى إعدادات الإدارة > برامج العمل الجماعي > تكامل Gmail ، والصق معرّف عميل Google وسر العميل، ثم احفظ التغييرات. تجنّب مشاركة السر في لقطات الشاشة أو التذاكر أو سجل الأوامر أو الملاحظات المشتركة. إذا قمت بتغيير سر عميل OAuth لاحقًا، فقم بتحديث Nextcloud فورًا وجدول عملية تحقق مُراقبة للحسابات الحالية.
افتح تطبيق Nextcloud Mail بصفتك المستخدم وأضف حساب Gmail. يتعرف التطبيق حاليًا على Gmail من خلال خوادم IMAP/SMTP القياسية، ويُغيّر طريقة المصادقة إلى XOAUTH2 عندما يُفعّل المسؤول مصادقة Google OAuth. تُوفّر Google مستندات imap.gmail.com:993IMAP عبر SSL و smtp.gmail.comTLS على منافذ SMTP المدعومة.
تابع عملية تسجيل الدخول إلى حساب جوجل واطلع على شاشة الموافقة. قد يعرض مزود الخدمة تحذيرات أو يقيد الوصول إذا لم يتم تكوين تطبيق OAuth أو التحقق منه للنطاقات والجمهور المستخدمين.
لا تكتفِ بـ "تم ربط الحساب". افتح صندوق الوارد، وافتح رسالة واحدة على الأقل، ثم أرسل رسالة إلى صندوق بريد ثانٍ تتحكم به، وردّ عليها، ثم أكّد عملية الإرسال والاستقبال. هذا الاختبار يُثبت أكثر بكثير من مجرد إعادة توجيه OAuth.
افتح مركز إدارة Microsoft Entra وأنشئ تسجيل تطبيق. يُشير دليل Nextcloud إلى ضرورة اختيار أنواع الحسابات التي تسمح بحسابات Microsoft المؤسسية والشخصية كمثال عام، وتكوين عنوان URI لإعادة توجيه الويب منقول من Nextcloud. إذا كانت مؤسستك تستخدم مستأجرًا واحدًا فقط، فلا تقم بنسخ مثال المستأجرين المتعددين بشكل أعمى؛ بل وازن بين أنواع الحسابات المدعومة وإعدادات المستأجر وسياسة الهوية الخاصة بك.
تُلزم مايكروسوفت بتسجيل عناوين إعادة التوجيه في التطبيق. قد يؤدي عدم التطابق إلى ظهور أخطاء AADSTS50011. تجدون إرشادات مايكروسوفت الحالية في قسم " أفضل الممارسات والقيود المتعلقة بعناوين إعادة التوجيه" .
انسخ مُعرّف التطبيق (العميل) . ثم افتح "الشهادات والأسرار" ، وأنشئ سرًا جديدًا للعميل، وانسخ قيمة السر فورًا. تُشير مايكروسوفت إلى أن القيمة لا تُعرض مرة أخرى بعد مغادرة الصفحة. كما أنها تُحدد مدة صلاحية سر العميل بـ 24 شهرًا أو أقل، وتوصي بفترة صلاحية أقصر في وثائق تسجيل التطبيقات الحالية.
يُعد تاريخ انتهاء الصلاحية هذا شرطًا تشغيليًا، وليس تفصيلًا خاصًا بعملية التثبيت لمرة واحدة. لذا، أدرج تاريخ انتهاء صلاحية كلمة المرور السرية ضمن عملية تدوير بيانات الاعتماد في مؤسستك. وإلا، فقد يفشل نشر Nextcloud Mail الذي يبدو مستقرًا ظاهريًا لاحقًا، نظرًا لعدم إمكانية إكمال عملية تحديث الرمز المميز.
في إعدادات إدارة Nextcloud، افتح برنامج إدارة المجموعات ومنطقة تكامل Microsoft. أدخل معرّف العميل وكلمة مرور العميل. يستخدم دليل Nextcloud الرسمي قيمة المستأجر commonلتكوين Outlook المستضاف العام، ويحذر صراحةً من أن استخدام معرّف مستأجر مخصص لا يتوافق مع هذا الدليل الأساسي إلا إذا قمت بتغيير أنواع الحسابات المدعومة أيضًا.
فيما يخص أذونات البروتوكول الأساسية، توثق مايكروسوفت نطاقات التفويض، بما في ذلك https://outlook.office.com/IMAP.AccessAsUser.Allبروتوكولي IMAP و https://outlook.office.com/SMTP.SendSMTP، بالإضافة إلى offline_accessالحالات التي تتطلب رمز تحديث. يقوم Nextcloud بإنشاء تدفق الموفر؛ ومع ذلك، يجب عليك التأكد من أن سياسات المستأجر وقواعد الوصول المشروط تسمح بالوصول المفوض المطلوب.
أضف عنوان Outlook أو Microsoft 365 في Nextcloud Mail، ثم تابع عملية تسجيل الدخول/الموافقة الخاصة بـ Microsoft. يوضح دليل إدارة Nextcloud أنه بمجرد إعداد OAuth، يتم تجاهل كلمة المرور المُدخلة أثناء إعداد الحساب، ويُطلب من المستخدم الموافقة من Microsoft.
مرة أخرى، نتيجة الموافقة الظاهرة ليست سوى إشارة مؤقتة. تأكد من تحميل قائمة المجلدات، وإمكانية قراءة رسالة اختبارية، وإمكانية إرسال رسالة، وأن مجلد "المرسلة" يحتوي على النسخة المتوقعة.
| إشارة | ماذا يعني ذلك؟ | ما الخطوة التالية؟ |
|---|---|---|
| تمت الموافقة بنجاح وتم تحميل صندوق الوارد | من المحتمل أن يكون كل من التفويض وIMAP يعملان | اختبار سلوك إرسال وتحديث SMTP |
| تمت الموافقة بنجاح ولكن المجلدات لم يتم تحميلها | ربما اكتملت عملية إعادة التوجيه بينما فشل اتصال البريد الإلكتروني | تحقق من سياسة مزود الخدمة، وإمكانية الوصول إلى بروتوكول IMAP، وسجلات Nextcloud، وإعدادات الحساب. |
| الاستقبال يعمل لكن الإرسال يفشل | يعمل بروتوكول IMAP؛ قد لا يعمل ترخيص SMTP أو سياسة الخادم. | تحقق من خدمة SMTP، والأذونات المفوضة، وقيود المستأجر/المزود |
| يعمل التطبيق في البداية، لكنه يطلب تسجيل الدخول بشكل متكرر لاحقاً | قد يكون استخدام رمز التحديث، أو صلاحية السر، أو حالة التطبيق، أو سياسة الموفر، غير ناجح. | تحقق من تاريخ انتهاء صلاحية السر، وحالة نشر/التحقق من تطبيق OAuth، وأخطاء الرمز المميز، والتغييرات الأخيرة في السياسة |
| خطأ في عدم تطابق إعادة التوجيه | عنوان URL المسجل لإعادة الاتصال لا يتطابق تمامًا مع الطلب | انسخ عنوان URI من Nextcloud مرة أخرى وقارنه حرفًا بحرف. |
قم بتغيير إعدادات تطبيق OAuth عندما لا يتطابق عنوان إعادة التوجيه، أو جمهور الحساب المدعوم، أو إعدادات المستأجر، أو إعدادات الموافقة مع بيئة النشر الخاصة بك. لن تُصلح المحاولات المتكررة عدم التوافق الهيكلي.
قم بتغيير إعدادات عنوان URL/الوكيل الخاص بالنشر عندما يُنشئ Nextcloud عنوان رد اتصال داخليًا أو HTTP أو عنوان رد اتصال عام غير صحيح. أصلح عنوان URL الخارجي الأساسي أولًا، ثم أعد إنشاء أو حدّث عنوان URI لإعادة توجيه المزوّد.
استخدم إدارة خاصة بمزود الخدمة بدلاً من افتراضات OAuth العامة عندما تمنع قيود الوصول المشروط، أو سياسة موافقة المسؤول، أو التحقق من تطبيق Google، أو النطاقات المقيدة المستخدمين من إكمال عملية التفويض. يتم تطبيق هذه الضوابط عمدًا من قِبل مزود الهوية.
لا تستخدم طريقة مصادقة مختلفة إلا إذا سمح بذلك صراحةً مزود الخدمة وسياسة الأمان الخاصة بك. على سبيل المثال، تشير واجهة Nextcloud Mail إلى أن كلمة مرور تطبيق Google يمكن أن تكون بديلاً عندما لا يكون Google OAuth مُهيأً ويستخدم حساب Google المصادقة الثنائية. هذا لا يُعادل OAuth2، ولا ينبغي اعتباره البديل المُفضل على مستوى المؤسسة لمجرد سهولة إعداده.
يوجد تحذير تشخيصي هام في تاريخ مشروع Nextcloud Mail. في يوليو 2026، أكد القائمون على الصيانة وجود خلل برمجي حيث يمكن أن تؤدي أخطاء OAuth من جانب مزود الخدمة إلى ظهور صفحة إعادة التوجيه نفسها "تم ربط الحساب" كما لو كانت عملية تفويض ناجحة. شمل التقرير شركة مايكروسوفت بشكل مباشر، وحدد نمط التحكم نفسه لشركة جوجل. وصف تقرير منفصل صدر في عام 2026 صعوبة إعادة ربط حساب بعد أن أصبح رمز التحديث الخاص به غير قابل للاستخدام. تم تقديم هذه التقارير بخصوص كود Mail 5.10.7؛ لذا لا تفترض أن كل إصدار متأثر بشكل دائم، ولكن لا تعتمد أيضًا على صفحة إعادة التوجيه كدليل وحيد على نجاح العملية.
يمكنك مراجعة مشكلة معالجة أخطاء إعادة توجيه OAuth ومشكلة إعادة اتصال OAuth في المشروع . إذا كنت تحاول حل مشكلة في إصدار حالي، فتحقق أولاً من إصدار البريد الإلكتروني المثبت وأحدث ملاحظات الإصدار قبل تطبيق الحلول البديلة المكتوبة لفرع أقدم.
يُحسّن بروتوكول OAuth2 نموذج المصادقة لبريد Nextcloud، ولكنه لا يُغني عن إدارة سياسة المزوّد، وعناوين URI لإعادة التوجيه، وبيانات اعتماد التطبيق، والوصول إلى بروتوكول البريد. يكون الإعداد جاهزًا للاستخدام الفعلي عندما تعمل جميع مراحل العملية - من تفويض المزوّد، وتحديث الرمز المميز، واسترجاع IMAP، وإرسال SMTP - بسلاسة وفقًا للسياسات المطبقة على المستخدمين.
قم باستكشاف أخطاء فك تشفير Element Web وإصلاحها عن طريق التحقق من الجهاز، ونسخ المفاتيح الاحتياطية، ومفاتيح الاسترداد، ومفاتيح الغرف المفقودة - دون المخاطرة بسجل الرسائل.
تعرف على كيفية تمكين موفري المصادقة الثنائية في Nextcloud، وفرض المصادقة الثنائية للمستخدمين أو المجموعات، وإعداد عملية الاسترداد، والتحقق من عمليات تسجيل الدخول وتطبيقات العميل.
قم بتقييد إعادة توجيه البريد الصادر غير المصادق عليه في Zimbra إلى عناوين IP الموثوقة باستخدام zimbraMtaMyNetworks. تعرّف على كيفية فحص قائمة السماح وتحديثها وإعادة تحميلها والتحقق منها بأمان.
قم بتعيين قيمة memory_limit لـ PHP إلى 512 ميجابايت على الأقل لـ Nextcloud، وابحث عن تكوين PHP الصحيح للويب، وأعد تشغيل Apache أو PHP-FPM، وتحقق من إزالة التحذير.
قم بإعداد Coturn مع Synapse لإجراء مكالمات Matrix WebRTC. قم بتكوين بيانات الاعتماد المشتركة، وNAT، ومنافذ جدار الحماية، وخيارات TLS، وميّز بين TURN القديم وMatrixRTC وLiveKit.
Configure Nextcloud Mail with OAuth2 for Gmail or Microsoft 365, verify IMAP/SMTP access, troubleshoot redirect issues, and know the limits.
قم بإصلاح تحذير جلسة Element "تعذر التحقق من الهوية" عن طريق التحقق باستخدام جهاز موثوق آخر أو مفتاح استرداد، وتعرف على متى تكون إعادة التعيين آمنة.
قارن بين عملية ترحيل البيانات إلى Kopano و grommunio و Zammad. تعرّف على بيانات صناديق البريد التي يمكن لكل مسار الاحتفاظ بها، وكيفية تجربة النتائج والتحقق منها، ومتى يكون استخدام IMAP أو الاستيراد المخصص مناسبًا.
انقل مجلد بيانات Nextcloud إلى قرص صلب خارجي دون الإخلال بمراجع الملفات. استخدم النسخ الاحتياطية، والربط الدائم، وrsync، والأذونات، والروابط الرمزية بأمان.
قم باستكشاف أخطاء مؤقتات Cron الخاصة بنظام Nextcloud على Ubuntu وإصلاحها عن طريق التحقق من مستخدم الخدمة ومسارات PHP و Nextcloud وتفعيل المؤقت وسجل تشغيل المهمة.
