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

إعداد مصادقة Outlook/Microsoft 365 OAuth

سيرشدك هذا الدليل خلال إنشاء تطبيق Microsoft Azure لمصادقة OAuth مع Outlook/Microsoft 365. يوفر OAuth طريقة أكثر أمانًا للوصول إلى حساب Outlook مقارنة بمصادقة كلمة المرور التقليدية.

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

  • حساب Microsoft (شخصي أو Microsoft 365/Office 365)
  • الوصول إلى Azure Portal
  • عنوان URL لتثبيت Perfex CRM (لتكوين redirect URI)
معلومات

بالنسبة لمنظمات Microsoft 365، قد تحتاج موافقة المسؤول.

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

الخطوة 1: تسجيل تطبيق في Azure Portal​

  1. انتقل إلى Azure Portal
  2. سجّل الدخول بحساب Microsoft
  3. انتقل إلى "Azure Active Directory" (أو ابحث عنه)
  4. انقر على "App registrations" في القائمة اليسرى
  5. انقر "+ New registration"
  6. املأ تفاصيل التطبيق:
    • Name: أدخل اسمًا (مثل "Perfex CRM Mailbox")
    • Supported account types: اختر "Accounts in any organizational directory and personal Microsoft accounts" للتوافق الأقصى
    • Redirect URI:
      • Platform: Web
      • URI: https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
      • استبدل your-domain.com بالنطاق الفعلي لـ Perfex CRM
  7. انقر "Register"

الخطوة 2: تكوين أذونات API​

  1. في تسجيل التطبيق، انقر "API permissions" في القائمة اليسرى
  2. انقر "+ Add a permission"
  3. حدد "Microsoft Graph"
  4. حدد "Delegated permissions"
  5. أضف الأذونات التالية:
    • Mail.Read - قراءة البريد في جميع صناديق البريد
    • Mail.ReadWrite - قراءة وكتابة البريد في جميع صناديق البريد
    • Mail.Send - إرسال البريد كمستخدم
    • offline_access - الحفاظ على الوصول إلى البيانات التي منحتها إمكانية الوصول (لتحديث token)
  6. انقر "Add permissions"
  7. مهم: انقر "Grant admin consent for [Your Organization]" إذا رأيت هذا الزر
تحذير

مطلوب لحسابات المنظمة. يتطلب امتيازات المسؤول.

الخطوة 3: إنشاء Client Secret​

  1. في تسجيل التطبيق، انقر "Certificates & secrets" في القائمة اليسرى
  2. انقر "+ New client secret"
  3. أدخل وصفًا (مثل "Perfex Mailbox Secret")
  4. اختر فترة انتهاء الصلاحية: 24 شهرًا (موصى به للإنتاج)
  5. انقر "Add"
  6. مهم: انسخ Value فورًا (لن تتمكن من رؤيته مرة أخرى) - هذا هو Client Secret

الخطوة 4: الحصول على Application (Client) ID​

  1. في تسجيل التطبيق، انتقل إلى "Overview"
  2. انسخ Application (client) ID - هذا هو Client ID

الخطوة 5: التحقق من Redirect URI​

  1. في تسجيل التطبيق، انقر "Authentication" في القائمة اليسرى
  2. تحت "Redirect URIs"، تحقق من إدراج redirect URI:
https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
  1. إذا لم يكن موجودًا، انقر "+ Add a platform" > "Web" وأضفه
  2. تحت "Implicit grant and hybrid flows"، تأكد من تحديد "Access tokens" (إن أمكن)
  3. انقر "Save"

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

  1. انتقل إلى منطقة إدارة Perfex CRM
  2. انتقل إلى Mailbox > Configuration
  3. حدد "OAuth2" كطريقة المصادقة
  4. حدد "Outlook" كمقدم الخدمة
  5. أدخل Client ID (Application ID من Azure)
  6. أدخل Client Secret (القيمة التي نسختها)
  7. للمنظمات Microsoft 365: أدخل Tenant ID (موجود في Azure AD > Overview). اتركه فارغًا لحسابات Microsoft الشخصية.
  8. انقر "Save Configuration"
  9. انقر زر "Connect Outlook"
  10. قم بتفويض التطبيق في النافذة المنبثقة من Microsoft
  11. يجب أن ترى رسالة نجاح تؤكد الاتصال

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

قيود تطبيق Microsoft Azure​

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

  1. متطلبات موافقة المسؤول - تتطلب حسابات المنظمة (Microsoft 365/Office 365) موافقة المسؤول لأذونات معينة. يجب على المسؤول الموافقة على التطبيق قبل أن يتمكن المستخدمون من استخدامه.

  2. قيود نوع الحساب:

    • "Accounts in this organizational directory only" - مستخدمو مؤسستك فقط
    • "Accounts in any organizational directory" - مستخدمو أي منظمة Microsoft 365
    • "Accounts in any organizational directory and personal Microsoft accounts" - أقصى توافق
    • "Personal Microsoft accounts only" - حسابات @outlook.com و @hotmail.com الشخصية فقط

  3. متطلبات Tenant ID - تتطلب حسابات المنظمة Tenant ID للمصادقة الصحيحة. الحسابات الشخصية يمكن تركها فارغة.

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

  • التطبيقات غير المُتحقق منها يمكن استخدامها فورًا للحسابات الشخصية لكن قد تعرض رسائل تحذير للمستخدمين.
  • التطبيقات المُتحقق منها تتطلب التقديم إلى Microsoft App Store (اختياري) وتوفر تجربة مستخدم أفضل (بدون تحذيرات).
  • سير عمل موافقة المسؤول - للحسابات المؤسسية، يجب على المسؤول منح الموافقة. يرى المسؤول الأذونات التي يطلبها التطبيق.

تحديث Token​

تقوم الوحدة تلقائيًا بتحديث token:

  • Refresh tokens: يتم الحصول عليها تلقائيًا بإذن offline_access
  • انتهاء صلاحية token: عادةً ساعة واحدة لـ access tokens، 90 يومًا لـ refresh tokens
  • تحديث تلقائي: تقوم الوحدة بتحديث tokens تلقائيًا قبل انتهاء الصلاحية

Multi-Tenant مقابل Single-Tenant​

  • Multi-Tenant: يمكن استخدام التطبيق من أي حساب Microsoft (يتطلب موافقة المسؤول لكل منظمة)
  • Single-Tenant: يمكن استخدام التطبيق فقط داخل مؤسستك

ملاحظات​

  • يجب أن يتطابق redirect URI تمامًا مع ما قمت بتكوينه في Azure Portal
  • احتفظ بـ Client Secret آمنًا - لا تشاركه أبدًا علنًا
  • إذا غيرت النطاق، حدّث redirect URI في Azure Portal
  • للحسابات المؤسسية، تأكد من منح موافقة المسؤول
  • Tenant ID مطلوب فقط لحسابات Microsoft 365/Office 365
  • يتم التعامل مع تدفق OAuth بالكامل بواسطة Microsoft - الوحدة تبدأ فقط وتستقبل الاستجابة

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

خطأ "AADSTS50011: Redirect URI mismatch":

  • تأكد من أن redirect URI في Azure Portal يتطابق تمامًا: https://your-domain.com/admin/mailbox/oauth/callback?provider=outlook
  • تحقق من الشرطات الزائدة أو عدم تطابق HTTP مقابل HTTPS
  • تحقق من إدراج URI تحت نوع منصة "Web"

خطأ "Admin consent required":

  • متوقع لحسابات المنظمة (سياسة Microsoft)
  • تواصل مع مسؤول Microsoft 365 لمنح الموافقة
  • يمكن للمسؤول منح الموافقة في Azure Portal > Enterprise applications

خطأ "Invalid client secret":

  • تنتهي صلاحية Client secrets - أنشئ واحدًا جديدًا في Azure Portal
  • تأكد من نسخ "Value" (وليست Secret ID)
  • تحقق من عدم انتهاء صلاحية السر

خطأ "AADSTS700016: Application not found":

  • تحقق من صحة Client ID
  • تأكد من استخدام Application (client) ID، وليس Object ID
  • تحقق من وجود تسجيل التطبيق في tenant Azure AD الصحيح

خطأ "Token refresh failed":

  • تأكد من منح إذن offline_access
  • تحقق من منح موافقة المسؤول (لحسابات المنظمة)
  • تحقق من عدم انتهاء صلاحية client secret

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

معلومات

متطلبات موافقة المسؤول وقيود نوع الحساب وسياسات token هي سياسات أمان Microsoft لتطبيقات Azure. لم تفرض برنامجنا هذه القيود.