ملخص

تسمح تطبيقات OAuth للتطبيقات الخارجية بالاتصال بأمان بـ Astra نيابة عن المستخدمين. بدلاً من مشاركة بيانات الاعتماد، يقوم المستخدمون بتسجيل الدخول إلى Astra ومنح الإذن صراحةً للتطبيق. يشرح هذا الدليل كيفية عمل تطبيقات OAuth، وكيفية إنشائها وإدارتها، ومتى يتم استخدام تطبيقات OAuth بدلاً من مفاتيح API.

التعليمات

ما هو تطبيق OAuth؟

تطبيق OAuth هو تطبيق تقوم بتسجيله في Astra للسماح للمستخدمين بتفويض الوصول إلى مساحة العمل الخاصة بهم بشكل آمن.

عند إنشاء تطبيق OAuth، يقوم Astra بإنشاء:

معرف العميل، الذي يتعرف على تطبيقك.
سر العميل، الذي يصادق على تطبيقك.

عندما يقوم المستخدم بتوصيل تطبيقك بـ Astra، تتم إعادة توجيهه إلى Astra لتسجيل الدخول ومراجعة الأذونات التي يطلبها تطبيقك. يتم منح الوصول فقط بعد موافقة المستخدم على الطلب.

حالات الاستخدام الموصى بها

تعتبر تطبيقات OAuth مثالية لـ:

منتجات SaaS التي تتصل بحساب Astra الخاص بالعميل
التطبيقات التي تتطلب موافقة المستخدم قبل الوصول إلى بيانات Astra
التطبيقات متعددة المستأجرين التي تخدم عملاء أو مساحات عمل متعددة
عمليات التكامل التي تسمح للمستخدمين بتوصيل حساب Astra الخاص بهم من خلال زر توصيل Astra

متى لا تستخدم تطبيقات OAuth

قد لا تكون تطبيقات OAuth الخيار الأفضل لـ:

المسارات النصية الداخلية والأتمتة الخلفية
عمليات التكامل بين النظام والنظام دون تفاعل المستخدم
الوظائف المجدولة التي تعمل تحت حساب مؤسسة واحدة

لهذه السيناريوهات، عادةً ما تكون مفاتيح API أبسط في الإدارة.

كيفية إنشاء تطبيق OAuth

لإنشاء تطبيق OAuth:

قم بتسجيل الدخول إلى حساب Astra الخاص بك.
انتقل إلى الحساب > تطبيقات OAuth.
انقر فوق إنشاء تطبيق.

أدخل التفاصيل المطلوبة:
- اسم التطبيق - الاسم المعروض للمستخدمين أثناء التفويض.
- عنوان URI لإعادة التوجيه - عنوان URL حيث يتم إرسال المستخدمين بعد الموافقة على الوصول.
- النطاقات - الأذونات التي يحتاجها تطبيقك.
انقر فوق إنشاء.

هام: احفظ سر العميل الخاص بك على الفور

بعد إنشاء التطبيق، يعرض Astra سر العميل مرة واحدة فقط.

انسخ وخزن معرف العميل وسر العميل في مكان آمن قبل مغادرة الصفحة.

بعد ذلك، سيستمر Astra في عرض معرف العميل، ولكن لا يمكن عرض سر العميل الكامل مرة أخرى.

فهم عناوين URI لإعادة التوجيه

عنوان URI لإعادة التوجيه هو الوجهة التي يرسل إليها Astra المستخدمين بعد موافقتهم أو رفضهم الوصول إلى تطبيقك.

يجب أن يتطابق عنوان URI لإعادة التوجيه المقدم أثناء التفويض تمامًا مع أحد عناوين URI المسجلة لتطبيق OAuth. إذا لم تتطابق القيم، فسيفشل طلب التفويض.

أمثلة لعناوين URI لإعادة التوجيه

بيئة الإنتاج:

https://your-app.com/oauth/callback

بيئة التطوير المحلية:

http://localhost:8787/callback

فهم النطاقات

تحدد النطاقات الأذونات التي يمكن لتطبيقك طلبها من Astra.

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

النطاقات المتاحة

النطاق	الوصف
الكل	وصول كامل إلى جميع إمكانيات واجهة برمجة التطبيقات العامة المتاحة
دردشة	الدردشة مع الوكلاء
وكلاء: قراءة	عرض الوكلاء
وكلاء: كتابة	إنشاء الوكلاء وتحديثهم وإدارتهم
جهات الاتصال: قراءة	عرض جهات الاتصال
جهات الاتصال: كتابة	إنشاء جهات الاتصال وتحديثها وإدارتها
المحادثات: قراءة	عرض سجل المحادثات
المعرفة: قراءة	عرض قواعد المعرفة
المعرفة: كتابة	إنشاء قواعد المعرفة وتحديثها وإدارتها
خطافات الويب: إدارة	إنشاء وإدارة خطافات الويب
التحليلات: قراءة	الوصول إلى بيانات التحليلات

أفضل الممارسات عند العمل مع تطبيقات OAuth

اطلب فقط الأذونات التي تحتاجها

اطلب فقط النطاقات المطلوبة لوظائف تطبيقك.

يساعد طلب عدد أقل من الأذونات المستخدمين على فهم ما يمكن لتطبيقك الوصول إليه ويحسن الثقة أثناء عملية التفويض.

كيف تعمل عملية التفويض (تجربة المستخدم)

عندما يقوم المستخدم بتوصيل تطبيق OAuth الخاص بك بـ Astra:

ينقر المستخدم على توصيل Astra في تطبيقك.
تتم إعادة توجيه المستخدم إلى صفحة تفويض Astra.
يعرض Astra اسم التطبيق والأذونات المطلوبة.
يسجل المستخدم الدخول إلى Astra إذا لم يكن مسجلاً دخوله بالفعل.
ينقر المستخدم على تفويض أو رفض.
إذا تمت الموافقة، يعيد Astra توجيه المستخدم إلى عنوان URI المحدد لإعادة التوجيه.
يتلقى تطبيقك بيانات اعتماد التفويض ويمكنه الوصول إلى Astra نيابة عن المستخدم.

ما يعنيه هذا للمستخدمين

لا يحتاج المستخدمون أبدًا إلى مشاركة كلمة مرور Astra الخاصة بهم مع تطبيقك.
يمنح كل مستخدم حق الوصول بشكل فردي.
ينطبق الوصول فقط على مساحة العمل التي يقوم المستخدم بتفويضها.
يمكن للمستخدمين إزالة الوصول في أي وقت عن طريق فصل التطبيق.

إدارة تطبيقات OAuth

تعرض صفحة تطبيقات OAuth جميع التطبيقات المسجلة.

يمكنك مراجعة التطبيقات الحالية وإزالة التطبيقات التي لم تعد مطلوبة.

كيفية حذف تطبيق OAuth

لحذف تطبيق OAuth:

قم بتسجيل الدخول إلى حساب Astra الخاص بك.
افتح الحساب → تطبيقات OAuth.
حدد موقع التطبيق الذي تريد إزالته.
احذف التطبيق.
قم بتأكيد الإجراء.

ماذا يحدث عند حذف تطبيق؟

عند حذف تطبيق OAuth:

لم يعد من الممكن بدء طلبات التفويض الجديدة.
يتم إلغاء صلاحية رموز الوصول الحالية.
يفقد المستخدمون المتصلون الوصول على الفور.
يجب على المستخدمين إعادة الاتصال إذا تم إنشاء تطبيق بديل.

تطبيقات OAuth مقابل مفاتيح API

أي خيار يجب أن تختار؟

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

	تطبيقات OAuth	مفاتيح API
المستخدمون المستهدفون	العملاء والمستخدمون النهائيون	الأنظمة الداخلية والخدمات الخلفية
مطلوب تفويض المستخدم	نعم	لا
شاشة موافقة المستخدم	نعم	لا
يدعم عملاء متعددين	نعم	لا
نوع بيانات الاعتماد	رموز وصول قصيرة الأجل يمكن تحديثها	مفاتيح API طويلة الأجل
حالة الاستخدام النموذجية	تكامل "توصيل حساب Astra الخاص بك"	مزامنة البيانات الآلية أو سير العمل الداخلي