نظرة عامة على طرق تسجيل الدخول في Spotnana

أنشئ بواسطة Ashish Chaudhary, تم التعديل في السبت, 4 أكتوبر في 9:27 م بحسب Ashish Chaudhary

نظرة عامة على طرق المصادقة في Spotnana

فهرس المحتويات

نظرة عامة على طرق المصادقة في Spotnana
- المكوّنات الأساسية
- طرق المصادقة المدعومة

توفر Spotnana عدة طرق للمصادقة تتيح للشركاء التكامل بشكل آمن مع منصتنا. في هذا الدليل ستجد لمحة عن طرق المصادقة المختلفة التي تدعمها Spotnana حالياً، مع شرح مفصل لكل آلية عمل. تستعرض هذه الطرق كيف تقوم Spotnana بالتحقق من هوية المستخدمين ومنحهم صلاحية الوصول إلى موارد الشركة المحمية (أي الموارد المملوكة لمؤسسة المستخدم على منصة Spotnana).

المكوّنات الأساسية

قبل البدء، ننصحك بمراجعة هذه القائمة للتعرف على أهم عناصر النظام التي يُشار إليها في هذا الدليل.

واجهة Spotnana(واجهة المستخدم في Spotnana) تشير إلى تطبيق Spotnana على الويب (أي أداة الحجز الإلكتروني) أو تطبيق Spotnana على الهاتف المحمول. وبشكل خاص، يُقصد بها صفحة تسجيل الدخول التي تبدأ عملية المصادقة عند دخول المستخدم أو إنشاء حساب جديد.
خادم Spotnana هو الخادم الخلفي الخاص بـ Spotnana والمستخدم في عمليات المصادقة (مثل منح المستخدم حق الوصول إلى مورد معين أو حفظ ومعالجة معلومات المستخدم بأمان).
واجهة الشريك (واجهة المستخدم الخاصة بالشريك) واجهة المستخدم (أي التطبيق الأمامي) التي يستخدمها الشركاء للوصول إلى منصة Spotnana. على سبيل المثال، في المصادقة عبر iFrame، يتم تضمين منصة Spotnana داخل واجهة الشريك ويقوم المستخدمون بالوصول إلى Spotnana من خلالها.
خادم الشريك يشير إلى خادم أو أكثر من الخوادم الخلفية التي يستخدمها شركاؤنا للتكامل مع Spotnana.
مزود هوية Spotnana (Spotnana IdP) (مزود الهوية الخاص بـ Spotnana) يشير إلى خدمة Spotnana الداخلية لإدارة هويات المستخدمين ومنحهم الصلاحيات.
مزود هوية الشريك (Partner IdP) مزودو الهوية الخارجيون الذين يستخدمهم الشركاء، مثل Google أو Azure وغيرهم.
OBT أداة الحجز الإلكتروني الخاصة بـ Spotnana (OBT)، ويمكن الوصول إليها عبر https://app.spotnana.com/
رمز المستخدم (Subject token) في المصادقة عبر iFrame (أو تبادل الرموز)، يمثل رمز المستخدم هوية المستخدم. ويُستخدم هذا الرمز لجلب معلومات المستخدم ومنحه صلاحية الدخول إلى منصة Spotnana.
رمز الوصول (Access token) هو بيانات اعتماد (OAuth) تستخدمها تطبيقات الشركاء للوصول إلى الموارد المحمية نيابة عن المستخدم. وهو بمثابة مفتاح مؤقت يتيح للتطبيقات تنفيذ طلبات API دون كشف بيانات اعتماد المستخدم.
رمز التحديث (Refresh token) بيانات اعتماد طويلة الأمد تُستخدم للحصول على رموز وصول جديدة دون الحاجة لإعادة مصادقة المستخدم. عادةً ما يتم إصدارها مع رمز الوصول عند أول تسجيل دخول.
بيانات اعتماد العميل (Client credentials) المعلومات التي يحصل عليها المستخدمون الذين يتصلون مباشرة بواجهات Spotnana البرمجية (API)، مثل clientId و clientSecret).
PID (المعرّف الشخصي) هو معرّف شخصي يُنشأ للمستخدم، ويُستخدم لجلب معلوماته من خادم Spotnana.
orgId معرّف فريد تعيّنه Spotnana لمؤسسة المستخدم.
tmcId معرّف فريد تعيّنه Spotnana لشركة إدارة السفر (TMC).

طرق المصادقة المدعومة

فيما يلي طرق المصادقة المختلفة التي تدعمها Spotnana:

المصادقة باستخدام كلمة المرور
- مستخدم حالي
- مستخدم جديد
المصادقة عبر مزود الهوية (IdP)
المصادقة عبر واجهة البرمجة (API)
المصادقة عبر iFrame
المصادقة عبر رمز التفويض (Auth code)
المصادقة بين الأنظمة (M2M)

المصادقة باستخدام كلمة المرور

عند استخدام المصادقة بكلمة المرور، تقوم واجهة Spotnana (أي صفحة الدخول أو التسجيل في OBT) ببدء وإدارة عملية المصادقة مع خوادم Spotnana الخلفية. وتختلف خطوات العملية حسب ما إذا كان المستخدم يسجل الدخول بحساب موجود أو ينشئ حساباً جديداً. سنوضح كل سيناريو من خلال مخططات تسلسل الخطوات في الأقسام التالية.

مستخدم حالي

يوضح مخطط التسلسل والخطوات التالية كيف تتفاعل واجهة Spotnana مع الخدمات الخلفية للتحقق من هوية مستخدم حالي.

الشكل: مخطط تسلسل يوضح المصادقة بكلمة المرور للمستخدمين الحاليين.

الخطوة	التسلسل
يقوم مستخدم حالي بتسجيل الدخول عبر OBT أو تطبيق Spotnana على الهاتف باستخدام بريده الإلكتروني.
1	ترسل واجهة Spotnana طلب API إلى خادم Spotnana لجلب إعدادات المصادقة الخاصة بالمستخدم. يتضمن الطلب بيانات اعتماد المستخدم. ويحتوي الرد على `tmcId`، `orgId`، و `authProviderType`.
2	ترسل واجهة Spotnana طلب API إلى مزود هوية Spotnana (IdP) باستخدام `clientId`، البريد الإلكتروني وكلمة المرور. يقوم IdP بإنشاء رمز دخول (bearer token) جديد وإعادته إلى واجهة Spotnana. بهذه الخطوة يتم التحقق من المستخدم.
3	بعد نجاح المصادقة في الخطوة 2، يجب أن تتضمن جميع طلبات API اللاحقة رمز الدخول (bearer token)، و `orgId`، و `tmcId` في ترويسة الطلب. يتم التحقق من صحة رمز الدخول في جميع طلبات API الواردة، ثم يُعاد الرد إلى واجهة Spotnana.

مستخدم جديد

يوضح مخطط التسلسل والخطوات التالية كيف تتفاعل واجهة Spotnana مع الخدمات الخلفية للتحقق من هوية مستخدم جديد (أو مستخدم حالي يرغب في إعادة تعيين كلمة المرور).

الشكل: مخطط تسلسل يوضح المصادقة بكلمة المرور للمستخدمين الجدد.

الخطوة	التسلسل
يدخل المستخدم الجديد بريده الإلكتروني في صفحة تسجيل الدخول على OBT ثم يضغط على التالي.
1	ترسل واجهة Spotnana طلب API إلى خادم Spotnana لجلب إعدادات المصادقة الخاصة بالمستخدم. يتضمن الطلب بيانات اعتماد المستخدم. ويحتوي الرد على `tmcId`، `orgId`، و `authProviderType`.
1 أ	يدخل المستخدم كلمة مرور جديدة ثم يضغط على التالي.
2	ترسل واجهة Spotnana طلب API إلى مزود الهوية (IdP) لتسجيل المستخدم مع `clientId`، البريد الإلكتروني وكلمة المرور الجديدة. بعد تسجيل البيانات، يتم إرسال رمز تحقق لمرة واحدة (OTP) إلى بريد المستخدم الإلكتروني.
3	يدخل المستخدم رمز OTP في واجهة Spotnana ثم يضغط على تأكيد. ترسل واجهة Spotnana طلباً إلى مزود الهوية للتحقق من رمز OTP وإنشاء رمز دخول (bearer token) لتسجيل الدخول. يتم إنشاء رمز الدخول وإعادته إلى واجهة Spotnana، ما يعني نجاح المصادقة وإمكانية الدخول إلى منصة Spotnana باستخدام هذا الرمز.
4	بعد نجاح المصادقة في الخطوة 3، يجب أن تتضمن جميع طلبات API اللاحقة رمز الدخول (bearer token)، و `orgId`، و `tmcId` في ترويسة الطلب. يتم التحقق من صحة رمز الدخول في جميع طلبات API الواردة، ثم يُعاد الرد إلى واجهة Spotnana.

المصادقة عبر مزود الهوية (IdP)

تدعم Spotnana المصادقة عبر مزودي الهوية مثل Google وAzure وموفري IdP المخصصين باستخدام بروتوكول OpenID Connect أو SAML. يوضح مخطط التسلسل والخطوات التالية كيفية عمل المصادقة عبر IdP.

الشكل: مخطط تسلسل يوضح تدفق المصادقة عبر IdP.

الخطوة	التسلسل
يقوم المستخدم بتسجيل الدخول عبر OBT أو تطبيق Spotnana على الهاتف باستخدام بريده الإلكتروني.
1	ترسل واجهة Spotnana طلب API إلى خادم Spotnana لجلب إعدادات المصادقة الخاصة بالمستخدم. يتضمن الطلب بيانات اعتماد المستخدم. ويحتوي الرد على `tmcId`، `orgId`، و `authProviderType`.
2	تقوم واجهة Spotnana بإعادة توجيه الطلب إلى مزود الهوية Spotnana IdP.
3	يقوم مزود الهوية Spotnana بإعادة توجيه الطلب إلى مزود هوية الشريك، لتبدأ عملية المصادقة عبر IdP. ملاحظة: مع كل إعادة توجيه، يتم إرجاع رمز حالة 302 للدلالة على أن الطلب انتقل إلى عنوان URL آخر.
4	يتم إنشاء اتصال بين مزود هوية Spotnana ومزود هوية الشريك للتحقق من هوية المستخدم. ملاحظة: خلال هذا الاتصال، يرسل Spotnana IdP كل من `clientId` و `clientSecret` كبيانات مشفرة ضمن نموذج URL عبر مكالمة API إلى مزود هوية الشريك. إذا لم يستطع خادم IdP التعامل مع هذا النوع من البيانات، يمكن لخادم Spotnana العمل كوسيط لترجمة البيانات إلى تنسيق مقبول لدى مزود هوية الشريك.
5	يقوم مزود هوية الشريك بالتحقق من المستخدم بنجاح. ملاحظة: بعد هذه الخطوة، يجب أن يخضع ملف المستخدم للتحقق من رمز الدخول (bearer token).
5 أ	بعد نجاح المصادقة، يتم إرسال رد مزود هوية الشريك إلى Spotnana IdP.
5 ب	يقوم Spotnana IdP بإنشاء رمز فريد لملف المستخدم ويرسله إلى واجهة Spotnana.
6	ترسل واجهة Spotnana طلب API إلى Spotnana IdP باستخدام `clientID` والرمز الذي تم استلامه في الخطوة 5(ب). يقوم Spotnana IdP بإنشاء رمز دخول (bearer token) جديد وإرساله إلى واجهة Spotnana. ملاحظة: نجاح إنشاء رمز الدخول يعني أن المستخدم تم التحقق منه ويستطيع الوصول إلى Spotnana.
7	بعد نجاح المصادقة في الخطوة 6، يجب أن تتضمن جميع طلبات API اللاحقة رمز الدخول (bearer token)، و `orgId`، و `tmcId` في ترويسة الطلب. يتم التحقق من صحة رمز الدخول في جميع طلبات API الواردة، ثم يُعاد الرد إلى واجهة Spotnana.

المصادقة عبر واجهة البرمجة (API)

يمكن للشركاء الذين يستخدمون واجهات Spotnana البرمجية (APIs) للاتصال بالمنصة استخدام نقطة النهاية الخاصة بالمصادقة لإنشاء رمز دخول (bearer token) لمستخدميهم. يوضح مخطط التسلسل التالي كيف تتم عملية المصادقة عبر API لأي شريك.

الشكل: مخطط تسلسل يوضح المصادقة عبر واجهة البرمجة (API).

الخطوة التسلسل

الخطوة	التسلسل
1	يقوم مستخدم API بإرسال طلب POST إلى نقطة النهاية `get-auth-token(clientId,clientSecret)` على خادم Spotnana لإنشاء واستلام رمز دخول مؤقت. فيما يلي نموذج لطلب cUrl يمكن استخدامه عند استدعاء نقطة النهاية `get-auth-token` : curl -i -X POST \ https://api.spotnana.com/get-auth-token \ -H 'Content-Type: application/json' \ -d '{ "clientId": "sample-apiuser@tmcorg.com", "clientSecret": "<password>" }' ملاحظة: يرجى استبدال قيم `clientId` و `clientSecret` ببيانات الاعتماد التي حصلت عليها من Spotnana.
2	يقوم خادم Spotnana باستدعاء دالة `getToken(clientId,clientSecret)` في Spotnana IdP، والتي تنشئ رمز دخول مؤقت `bearerToken` وتعيده إلى خادم Spotnana. يرسل خادم Spotnana هذا الرمز كاستجابة JSON إلى مستخدم API.

يقوم مستخدم API بإرسال طلب POST إلى نقطة النهاية get-auth-token(clientId,clientSecret) على خادم Spotnana لإنشاء واستلام رمز دخول مؤقت.

فيما يلي نموذج لطلب cUrl يمكن استخدامه عند استدعاء نقطة النهاية get-auth-token :

curl -i -X POST \
https://api.spotnana.com/get-auth-token \
-H 'Content-Type: application/json' \
-d '{
  "clientId": "sample-apiuser@tmcorg.com",
  "clientSecret": "<password>"
}'

ملاحظة: يرجى استبدال قيم clientId و clientSecret ببيانات الاعتماد التي حصلت عليها من Spotnana.

يقوم خادم Spotnana باستدعاء دالة getToken(clientId,clientSecret) في Spotnana IdP، والتي تنشئ رمز دخول مؤقت bearerToken وتعيده إلى خادم Spotnana.
يرسل خادم Spotnana هذا الرمز كاستجابة JSON إلى مستخدم API.

بعد استلام رمز الدخول، يجب أن تتضمن جميع الطلبات اللاحقة إلى واجهات Spotnana البرمجية (مثل Trip APIs) رمز الدخول في ترويسة الطلب للتحقق من الصلاحية.

ملاحظة: نقطة النهاية get-auth-token(clientId, clientSecret) لديها حد أقصى 100 طلب API كل 5 دقائق.

المصادقة عبر iFrame

iFrame أو الحلول المدمجة تعني أن الشركاء يدمجون واجهة Spotnana ضمن واجهتهم، بحيث يصل المستخدمون إلى Spotnana من خلال واجهة الشريك. في هذه الحالة، تتم عملية المصادقة عبر تبادل الرموز بين أنظمة الشريك وSpotnana.

ملاحظة: في المصادقة عبر iFrame، يُشار إلى المستخدم الذي يسجل الدخول باسم المتصل (caller). وذلك لتغطية حالات محددة مثل دخول مستخدم API/نظام وطلب رمز وصول لمستخدم آخر. يمكن لمستخدم API/النظام استخدام بيانات اعتماد مسؤول TMC للاتصال المباشر بخادم Spotnana. لذا سنستخدم مصطلح المتصل (caller) كمصطلح عام، سواء كان المستخدم يسجل الدخول إلى حسابه أو مستخدم API/نظام يطلب رمز وصول لمستخدم آخر.

يوضح مخطط التسلسل التالي كيف تتم عملية المصادقة عبر تبادل الرموز بين Spotnana وخوادم الشريك.

الشكل: مخطط تسلسل يوضح المصادقة عبر iFrame باستخدام تبادل الرموز.

الخطوة	التسلسل
يقوم المتصل بتسجيل الدخول من خلال واجهة الشريك.
1	تعرض واجهة الشريك واجهة Spotnana من خلال iFrame.
2	ترسل واجهة Spotnana طلباً إلى واجهة الشريك عبر post message لطلب الرموز. يكون الطلب من النوع `type=TOKEN_EXCHANGE_REQUEST`.
3	ترسل واجهة الشريك طلب API إلى خادم الشريك لجلب رمز OAuth، وتبدأ بذلك الخطوات التالية في التسلسل.
3 أ	يقوم خادم الشريك باستدعاء خادم Spotnana باستخدام بيانات اعتماد المستخدم ورمز المستخدم (subject token) كمعطيات. يتحقق خادم Spotnana ما إذا كان الطلب من مستخدم API/نظام.
3 ب	يستدعي خادم Spotnana خادم الشريك لجلب البريد الإلكتروني للمتصل (المستخدم). يتم جلب البريد الإلكتروني وإعادته إلى خادم Spotnana لتحديد هوية المستخدم.
3 ج	يتم إرسال الرد على طلب API من الخطوة 1 من خادم Spotnana إلى خادم الشريك ويحتوي على رمز الوصول ورمز التحديث. ثم تُرسل هذه التفاصيل إلى واجهة الشريك.
4	ترسل واجهة الشريك الرمز إلى واجهة Spotnana عبر post message من النوع `type=TOKEN_EXCHANGE_RESPONSE.`
5	ترسل واجهة Spotnana طلب API إلى خادم Spotnana لإنشاء واستلام رمز دخول جديد. يقوم خادم Spotnana بإنشاء رمز دخول وإعادته إلى واجهة Spotnana. ملاحظة: نجاح إنشاء رمز الدخول يعني أن المستخدم تم التحقق منه ويستطيع الوصول إلى Spotnana.
6	بعد نجاح المصادقة في الخطوة 3، يجب أن تتضمن جميع طلبات API اللاحقة رمز الدخول (bearer token)، و `orgId`، و `tmcId` في ترويسة الطلب. يتم التحقق من صحة رمز الدخول في جميع طلبات API الواردة، ثم يُعاد الرد إلى واجهة Spotnana.

المصادقة عبر رمز التفويض (Auth code)

يوضح مخطط التسلسل التالي كيف تتم عملية المصادقة باستخدام رمز تفويض.

الشكل: مخطط تسلسل يوضح المصادقة باستخدام رمز التفويض (auth code).

الخطوة	التسلسل
1	تستدعي واجهة الشريك خادم الشريك لجلب رمز التفويض للمستخدم الذي يسجل الدخول. يتم جلب رمز التفويض وإرساله إلى واجهة الشريك.
2	ترسل واجهة الشريك طلباً إلى واجهة Spotnana عبر رابط إعادة توجيه مخصص يحتوي على `tmcId` و `authCode` كمعطيات.
3	تقوم واجهة Spotnana بإرسال طلب POST إلى خادم Spotnana باستخدام نقطة النهاية `v2/auth/token/companies/<tmcId>(authCode)` .
3 أ	يرسل خادم Spotnana طلباً إلى خادم الشريك لجلب `pid` للمستخدم باستخدام رمز التفويض. يتم جلب `pid` الخاصة بالمستخدم وإرسالها إلى خادم Spotnana.
3 ب	يتم إنشاء رمز الوصول ورمز التحديث بواسطة خادم Spotnana وإرسالهما إلى واجهة Spotnana.
4	ترسل واجهة Spotnana طلباً إلى خادم Spotnana باستخدام رمز الوصول ورمز التحديث لإنشاء واستلام رمز دخول (bearer token) للوصول. يتم إنشاء رمز الدخول وإرساله إلى واجهة Spotnana. ملاحظة: نجاح إنشاء رمز الدخول يعني أن المستخدم تم التحقق منه ويستطيع الوصول إلى Spotnana.
5	بعد نجاح المصادقة في الخطوة 4، يجب أن تتضمن جميع طلبات API اللاحقة رمز الدخول (bearer token)، و `orgId`، و `tmcId` في ترويسة الطلب. يتم التحقق من صحة رمز الدخول في جميع طلبات API الواردة، ثم يُعاد الرد إلى واجهة Spotnana.

ملاحظة: لا يمكن استخدام هذا التدفق في الحالات التي يسمح فيها مسؤول TMC لأكثر من مستخدم باستخدام نفس البريد الإلكتروني عند تسجيل الدخول.

المصادقة بين الأنظمة (M2M)

تُعد طريقة المصادقة بين الأنظمة (M2M) مناسبة عندما تتطلب العملية أن يصل التطبيق العميل إلى رابط رد خارجي (callback) لإنشاء accessToken للمستخدم. يوضح مخطط التسلسل التالي كيفية عمل المصادقة بين الأنظمة (M2M).

الشكل: مخطط تسلسل يوضح تدفق المصادقة بين الأنظمة (M2M).

الخطوة	التسلسل
يتم مزامنة المفاتيح العامة لجميع التطبيقات المستخدمة في المصادقة بين خادم Spotnana وSpotnana IdP. وسيتم استخدام هذه المفاتيح لاحقاً للتحقق من رمز الوصول أثناء عملية المصادقة.
1	يرسل خادم الشريك طلب API إلى `/oauth2/token(clientId,clientSecret)` في Spotnana IdP لإنشاء رمز دخول (bearer token). يتم إرسال الرمز الجديد إلى خادم الشريك.
2	يرسل خادم الشريك طلب API إلى رابط رد خارجي (callback) لإنشاء رمز وصول (access token) للمستخدم. يتم إنشاء رمز الوصول وإرساله إلى خادم Spotnana.
3	يتحقق خادم Spotnana من توقيع رمز الوصول باستخدام المفاتيح العامة التي تم مزامنتها سابقاً، ويتحقق أيضاً من `claim_id` الذي يثبت هوية الشريك. ثم يُرسل رمز الوصول إلى خادم الشريك لمصادقة المستخدم.