إنتقل إلى المحتوى الرئيسي

إعداد مصادقة Gmail OAuth

سيرشدك هذا الدليل خلال إنشاء تطبيق Google Cloud لمصادقة OAuth مع Gmail. يوفر OAuth طريقة أكثر أمانًا للوصول إلى حساب Gmail مقارنة بمصادقة كلمة المرور التقليدية.

المتطلبات الأساسية​

  • حساب Google (شخصي أو Google Workspace)
  • الوصول إلى Google Cloud Console
  • عنوان URL لتثبيت Perfex CRM (لتكوين redirect URI)

إعداد خطوة بخطوة​

الخطوة 1: إنشاء مشروع Google Cloud​

  1. انتقل إلى Google Cloud Console
  2. انقر على قائمة مشروع في أعلى الصفحة
  3. انقر "New Project"
  4. أدخل اسم المشروع (مثل "Perfex Mailbox OAuth")
  5. انقر "Create"
  6. انتظر إنشاء المشروع وحدده

الخطوة 2: تفعيل Gmail API​

  1. في Google Cloud Console، انتقل إلى "APIs & Services" > "Library"
  2. ابحث عن "Gmail API"
  3. انقر على "Gmail API" من النتائج
  4. انقر "Enable"
  5. انتظر تفعيل API

الخطوة 3: تكوين شاشة موافقة OAuth​

  1. انتقل إلى "APIs & Services" > "OAuth consent screen"
  2. حدد "External" كنوع المستخدم (ما لم يكن لديك حساب Google Workspace، فيمكنك اختيار "Internal")
  3. انقر "Create"
  4. املأ المعلومات المطلوبة:
    • App name: أدخل اسم التطبيق (مثل "Perfex CRM Mailbox")
    • User support email: بريدك الإلكتروني
    • Developer contact information: بريدك الإلكتروني
  5. انقر "Save and Continue"
  6. في صفحة "Scopes"، انقر "Add or Remove Scopes"
  7. أضف النطاقات التالية:
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/gmail.send
    • https://www.googleapis.com/auth/gmail.modify
  8. انقر "Update"، ثم "Save and Continue"
  9. في صفحة "Test users" (إذا كنت تستخدم نوع التطبيق External):
    • أضف عنوان Gmail كمتسخدم اختبار
    • انقر "Save and Continue"
  10. راجع وانقر "Back to Dashboard"

الخطوة 4: إنشاء بيانات اعتماد OAuth 2.0​

  1. انتقل إلى "APIs & Services" > "Credentials"
  2. انقر "Create Credentials" > "OAuth client ID"
  3. حدد "Web application" كنوع التطبيق
  4. أدخل اسمًا لعميل OAuth (مثل "Perfex Mailbox Client")
  5. تحت "Authorized redirect URIs"، انقر "Add URI"
  6. أضف redirect URI بالتنسيق:
https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail

استبدل your-domain.com بالنطاق الفعلي لـ Perfex CRM.

  1. انقر "Create"
  2. مهم: انسخ واحفظ كلاً من:
    • Client ID (ستحتاجه)
    • Client Secret (ستحتاجه - انقر "Show" للكشف عنه)

الخطوة 5: التكوين في Perfex CRM​

  1. انتقل إلى منطقة إدارة Perfex CRM
  2. انتقل إلى Mailbox > Configuration
  3. حدد "OAuth2" كطريقة المصادقة
  4. حدد "Gmail" كمقدم الخدمة
  5. أدخل Client ID في حقل "Gmail Client ID"
  6. أدخل Client Secret في حقل "Gmail Client Secret"
  7. انقر "Save Configuration"
  8. انقر زر "Connect Gmail"
  9. قم بتفويض التطبيق في النافذة المنبثقة من Google
  10. يجب أن ترى رسالة نجاح تؤكد الاتصال

القيود والاعتبارات المهمة​

قيود تطبيق Google Test​

These limitations are imposed by Google, not by our software.

  1. انتهاء صلاحية Token (7 أيام) - التطبيقات غير المُتحقق منها (التطبيقات في وضع الاختبار) لديها OAuth tokens تنتهي صلاحيتها بعد 7 أيام. بعد 7 أيام، يجب على المستخدمين إعادة تفويض الاتصال. هذه سياسة أمان Google للتطبيقات غير المُتحقق منها.

  2. قيود مستخدمي الاختبار - يمكن فقط للمستخدمين المضافين إلى قائمة "Test users" استخدام تطبيق OAuth. الحد الأقصى 100 مستخدم اختبار مسموح به. يطبق هذا القيد حتى يتم التحقق من التطبيق ونشره.

  3. عملية التحقق من التطبيق - لإزالة انتهاء صلاحية token لمدة 7 أيام، يجب تقديم التطبيق للتحقق من Google. قد يستغرق التحقق عدة أسابيع (عادةً 4-8 أسابيع). تراجع Google عن التطبيق للأمان والامتثال.

التحقق من التطبيق ونشره​

لإزالة القيود:

  1. التقديم للتحقق

    • انتقل إلى "OAuth consent screen" في Google Cloud Console
    • انقر زر "PUBLISH APP"
    • املأ نموذج التحقق مع:
      • غرض التطبيق ووظائفه
      • رابط سياسة الخصوصية
      • رابط شروط الخدمة
      • فيديو توضيحي (اختياري لكن موصى به)
    • قدّم للمراجعة

  2. جدول التحقق

    • المراجعة الأولية: 1-2 أسبوع
    • طلبات معلومات إضافية: متغيرة (إذا احتاج Google لتوضيح)
    • الموافقة النهائية: 4-8 أسابيع إجمالاً (نموذجية)

  3. بعد التحقق

    • لا تنتهي صلاحية tokens بعد 7 أيام
    • لا توجد قيود على مستخدمي الاختبار
    • يمكن لأي مستخدم Gmail استخدام التطبيق

الإنتاج مقابل الاختبار​

  • وضع الاختبار: إعداد سريع، لكن tokens تنتهي كل 7 أيام
  • وضع الإنتاج: يتطلب التحقق، لكن tokens لا تنتهي
  • الاختيار لك - برنامجنا يعمل مع كلا الوضعين

تحديث Token​

تقوم الوحدة تلقائيًا بتحديث token عند الإمكان. ومع ذلك:

  • التطبيقات غير المُتحقق منها: تنتهي tokens بعد 7 أيام وتتطلب إعادة تفويض يدوية
  • التطبيقات المُتحقق منها: تتحدث tokens تلقائيًا بدون تدخل المستخدم

ملاحظات​

  • يجب أن يتطابق redirect URI تمامًا مع ما قمت بتكوينه في Google Cloud Console
  • احتفظ بـ Client Secret آمنًا - لا تشاركه أبدًا علنًا
  • إذا غيرت النطاق، حدّث redirect URI في Google Cloud Console
  • يتم التعامل مع تدفق OAuth بالكامل بواسطة Google - الوحدة تبدأ فقط وتستقبل الاستجابة

استكشاف الأخطاء​

خطأ "Redirect URI mismatch":

  • تأكد من أن redirect URI في Google Cloud Console يتطابق تمامًا: https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail
  • تحقق من الشرطات الزائدة أو عدم تطابق HTTP مقابل HTTPS

"Token expired" بعد 7 أيام:

  • متوقع للتطبيقات غير المُتحقق منها (سياسة Google)
  • أعد التفويض بالنقر على "Connect Gmail" مرة أخرى
  • لتجنب ذلك، قدّم التطبيق للتحقق من Google

خطأ "Access blocked":

  • تأكد من إضافة بريدك الإلكتروني إلى قائمة "Test users" (للتطبيقات غير المُتحقق منها)
  • تحقق من تفعيل Gmail API في مشروع Google Cloud

لا يمكن العثور على Gmail API:

  • تأكد من أنك في مشروع Google Cloud الصحيح
  • جرّب البحث عن "Gmail" في مكتبة API

موارد إضافية​

معلومات

انتهاء صلاحية token لمدة 7 أيام وقيود مستخدمي الاختبار هي سياسات أمان Google للتطبيقات غير المُتحقق منها. لم تفرض برنامجنا هذه القيود. بمجرد التحقق من تطبيقك بواسطة Google، تُزال هذه القيود.