إعداد SAML SSO · EasyLiveChat

§ 00ما هو SAML SSO

يربط SAML SSO تطبيق EasyLiveChat بموفر الهوية الذي تستخدمه شركتك بالفعل — Okta أو Microsoft Entra أو Google Workspace أو أي موفر SAML 2.0 آخر. عندما ينقر الوكيل على بلاطة EasyLiveChat في لوحة موفر الهوية (أو يفتح إشارة مرجعية)، يتم تحويله إلى موفر الهوية، ويسجل الدخول هناك بكلمة المرور التي يستخدمها لكل شيء آخر، ثم يعود إلى صندوق وارد EasyLiveChat. لا تتم كتابة أي كلمة مرور خاصة بـ EasyLiveChat على الإطلاق.

إذا سبق لك النقر على "تسجيل الدخول باستخدام Google" على موقع ويب، فقد استخدمت النسخة الاستهلاكية من هذا النمط. SAML هو المكافئ المؤسسي — يثق الموقع (نحن) بأي شيء يقوله موفر الهوية (Okta أو Microsoft أو Google) عن هوية المستخدم.

لا يقوم EasyLiveChat بتشغيل موفر الهوية أبدًا. أنت تحضر موفرك الخاص. نحن نوفر طرف الاستقبال.

§ 01توفر الخطة

تسجيل الدخول الموحد SAML ميزة Enterprise. يتم فتحه أيضًا خلال التجربة المجانية لمدة 14 يومًا حتى تتمكن من تقييم الإعداد قبل اتخاذ القرار.

الخطة	SAML SSO
تجربة مجانية	مفتوح خلال التجربة
Starter	مقفل
Growth	مقفل
Enterprise	مضمّن

§ 02القيم لإعطائها لمشرف IdP

هذه هي معرفات جانب EasyLiveChat التي يحتاج IdP إلى معرفتها. استبدل <slug> بـ slug مساحة العمل الخاصة بك. تعرض صفحة /settings/sso كل هذه القيم مع أزرار نسخ.

عنوان تسجيل الدخول الموحد / ACS	https://api.livechattools.com/api/saml/<slug>/callback
الجمهور / معرف كيان SP	https://api.livechattools.com/api/saml/<slug>/metadata
تنسيق Name ID	عنوان البريد الإلكتروني
السمة المطلوبة	email (أو NameID = email)
تأكيد موقّع	مطلوبة (الاستجابة الموقّعة اختيارية)

يمكن لمعظم موفري IdP استيراد مستند XML الخاص بالبيانات الوصفية مباشرةً — عنوان البيانات الوصفية هو نفسه معرف الكيان ويُرجع XML الذي يبنيه الواجهة الخلفية لدينا.

§ 03إعداد Okta

تفترض هذه الخطوات أن لديك صلاحية المشرف على مساحة عمل Okta. طبقة Okta dev مجانية وتعمل للتقييم.

سجل الدخول إلى لوحة مشرف Okta → Applications → Create App Integration → SAML 2.0.
اختر اسمًا للتطبيق (مثلاً "EasyLiveChat") وانقر Next.
في خطوة Configure SAML، املأ هذه الحقول من صفحة EasyLiveChat /settings/sso الخاصة بك:
- Single sign-on URL → عنوان ACS الذي قدمناه لك.
- حدد "Use this for Recipient URL and Destination URL".
- Audience URI (SP Entity ID) → معرف الكيان الذي قدمناه لك.
- Name ID format → EmailAddress.
- Application username → Email.
- Attribute Statements → أضف صفًا واحدًا: email → user.email — Name format Basic.
انقر Next → "I'm an Okta customer adding an internal app" → Finish.
في علامة تبويب Sign On للتطبيق الجديد → "View SAML setup instructions". انسخ IdP Single Sign-On URL و IdP Issuer و X.509 Certificate (بصيغة PEM مع علامتي BEGIN/END).
عيّن التطبيق للمستخدمين الذين تتطابق رسائلهم الإلكترونية مع الوكلاء الموجودين في مساحة عمل EasyLiveChat (People → Assignments).

§ 04إعداد Microsoft Entra (Azure AD)

تفترض هذه الخطوات أن لديك دور Global Administrator أو Application Administrator في Microsoft Entra.

Entra admin → Enterprise applications → New application → Create your own application → اختر اسمًا (مثلاً "EasyLiveChat") → Non-gallery app.
افتح التطبيق الجديد → Single sign-on → SAML.
Basic SAML Configuration → عيّن Identifier (Entity ID) و Reply URL (ACS) إلى القيم من صفحة EasyLiveChat /settings/sso الخاصة بك.
Attributes & Claims → تأكد من وجود claim يحمل البريد الإلكتروني للمستخدم. إما الاعتماد على claim emailaddress الافتراضي ولصق URI الخاص به في حقل "Email claim" في EasyLiveChat، أو إضافة claim جديد يسمى email بقيمة user.mail.
SAML Signing Certificate → نزّل ملف "Certificate (Base64)" .cer. افتحه في محرر نصوص وانسخ محتوى PEM الكامل (مع علامتي BEGIN/END) إلى حقل شهادة التوقيع في EasyLiveChat.
ضمن "Set up <app name>"، انسخ Login URL (→ IdP entry URL في EasyLiveChat) و Microsoft Entra Identifier (→ IdP issuer). عيّن المستخدمين عبر Users and groups.

§ 05إعداد Google Workspace

تفترض هذه الخطوات أنك Super Admin في Workspace.

Google admin → Apps → Web and mobile apps → Add app → Add custom SAML app. أعطه اسمًا مثل "EasyLiveChat".
في خطوة IdP details، نزّل شهادة X.509 وانسخ SSO URL و Entity ID.
في خطوة Service provider details، الصق ACS URL و Entity ID من صفحة EasyLiveChat /settings/sso. اضبط Name ID format على EMAIL و Name ID على Basic Information > Primary email.
Attribute mapping → ربط Primary email → app attribute email.
أنهِ، ثم فعّل التطبيق لوحدة المؤسسة التي يُسمح لمستخدميها بتسجيل الدخول. احفظ الشهادة + الروابط في EasyLiveChat.

§ 06الإعداد في EasyLiveChat

افتح https://app.livechattools.com/settings/sso. والصق القيم الأربع التي جمعتها للتو من IdP الخاص بك:

IdP entry URL — عنوان تسجيل الدخول الموحد الذي أعطاك إياه IdP (مثلاً https://yourcompany.okta.com/app/exk.../sso/saml).
IdP issuer — معرف كيان IdP (يُسمى أحيانًا Issuer URL أو Entity ID في جانب IdP).
شهادة توقيع IdP (PEM) — الصق شهادة X.509 مع علامتي BEGIN CERTIFICATE / END CERTIFICATE.
ادعاء البريد الإلكتروني (اختياري) — اتركه فارغًا لاستخدام NameID. الصق URI الخاص بالـ claim إذا كان IdP يرسل البريد الإلكتروني تحت اسم سمة محدد.

انقر Save. تتغير شارة الحالة إلى CONFIGURED ويظهر عنوان تسجيل الدخول من جانب SP في أسفل الصفحة.

مساران — كلاهما ينتهي في نفس المكان (صندوق الوارد الخاص بك)، مع مصادقة برمز جلسة جديد.

من جانب SP — أرسل الوكلاء إلى https://api.livechattools.com/api/saml/<slug>/login. هذا الرابط الصديق للإشارات المرجعية يحولهم إلى IdP الخاص بك ثم يعيدهم.
من جانب IdP — ينقر الوكلاء على بلاطة EasyLiveChat من لوحة تطبيقات IdP الخاصة بهم (Okta dashboard أو Microsoft 365 app launcher أو Google Workspace app launcher). يهبطون مباشرة على صندوق وارد EasyLiveChat.

§ 08مطابقة الوكلاء

يطابق EasyLiveChat مستخدم SAML مع صف Agent موجود حسب البريد الإلكتروني — يجب أن يكون المستخدم الذي يصادقه IdP موجودًا بالفعل كوكيل في مساحة عملك. نحن لا ننشئ الوكلاء تلقائيًا عند أول تسجيل دخول SSO (لا يوجد توفير "just-in-time" بعد) حتى لا يتجاوز SSO حوكمة دعوات فريقك.

إذا لم يكن لمستخدم SAML وكيل مطابق، يقوم callback بإعادة التوجيه إلى صفحة تسجيل دخول EasyLiveChat مع reason=agent_not_found. ادعُ المستخدم عبر Settings → Team بالبريد الإلكتروني الذي يرسله IdP بالضبط، ثم أعد المحاولة.

§ 09استكشاف الأعطال

إذا فشل تسجيل الدخول، يعيد EasyLiveChat التوجيه إلى /login?saml_error=1&reason=<code>. يخبرك الرمز بما حدث:

reason=	ما حدث	الحل
missing_response	لم يرسل IdP استجابة SAMLResponse إلى callback الخاص بنا.	تحقق مرة أخرى من ACS / Single Sign-On URL في جانب IdP — يجب أن يكون بالضبط callback URL الذي عرضناه لك، بما في ذلك slug مساحة العمل.
validation_failed	تلقينا SAMLResponse لكن لم يتم التحقق من التوقيع.	يجب أن تتطابق شهادة التوقيع الملصقة في /settings/sso مع شهادة توقيع IdP الفعلية. أعد نسخ PEM (بما في ذلك علامتي BEGIN/END) من IdP.
no_email	التوقيع سليم لكن لا يوجد بريد إلكتروني في assertion.	تأكد من أن IdP يرسل البريد الإلكتروني للمستخدم — إما كـ NameID (بصيغة EmailAddress) أو كـ claim. إذا كان claim، الصق URI الخاص به في حقل Email claim.
agent_not_found	البريد الإلكتروني الذي أكده IdP غير موجود في قائمة الوكلاء.	ادعُ المستخدم عبر Settings → Team بنفس البريد الإلكتروني، ثم أعد محاولة تسجيل الدخول.

اقتراح تعديل