الانتقال إلى المحتوى الرئيسي
اسمح للمستخدمين بتفويض تطبيقك للوصول إلى ملفاتهم الشخصية في Ace Data Cloud، واشتراكات الخدمات، وAPI Key، والاستخدام أو الطلبات. استخدم Authorization Code + S256 PKCE القياسي: يفتح التطبيق صفحة التفويض، وبعد موافقة المستخدم يتلقى code لمرة واحدة، ثم يستبدله بـ OAuth access token. يُستخدم OAuth access token للوصول إلى واجهات موارد الحساب؛ ويستخدم استدعاء Model API مفتاح API Key المقابل. لا يؤدي تفويض OAuth تلقائيًا إلى إنشاء API Key أو تفعيل خدمة أو زيادة الرصيد.

اختيار طريقة التكامل

لا تتطلب إعادة التوجيه القياسية embed=studio أو embed_origin أو postMessage. ينشئ وضع مكوّن Studio صفحة التفويض ويحافظ على جسر الرسائل بواسطة المضيف؛ يجب على الأطراف الثالثة التكامل وفق بروتوكول المكوّن في نهاية هذا المستند، وألا تُركّب هاتين المعلمتين بنفسها.

نقاط النهاية ووثيقة الاكتشاف

تتطلب واجهة إدارة التطبيقات مصادقة تسجيل الدخول إلى الحساب، وليست واجهة تسجيل ديناميكي مجهول (DCR). إن عناوين الاكتشاف/التسجيل الخاصة بخدمة MCP نفسها ومنافذ OAuth الخاصة بحساب هذا الجدول هي نقاط دخول مختلفة؛ عند الاتصال بـ MCP محدد، اتبع وثائق تلك الخدمة ونتائج الاكتشاف. تُستخدم وثيقة الاكتشاف للحصول على نقاط النهاية وقدرات البروتوكول. تُرجع العملية الحالية OAuth token، ولا تُرجع id_token؛ لا تتعامل معها كتدفق تسجيل دخول كامل لـ OpenID Connect لمجرد وجود scope openid.

نطاقات الصلاحيات: استخدم أسماء scope الحالية

scope هو اسم صلاحية مفصول بمسافات وحساس لحالة الأحرف. تستخدم التطبيقات الجديدة صلاحيات محددة مثل profile:read وemail:read وphone:read.

من أين تحصل على الصلاحيات القابلة للطلب

بعد تسجيل الدخول، تُرجع واجهة قائمة تطبيقات OAuth GET /api/v1/oauth2/applications/ القيمة available_scopes؛ ويستخدم منتقي الصلاحيات في صفحة إدارة التطبيقات الكتالوج نفسه. هذه هي النطاقات الاختيارية التي ينبغي أن تعتمدها التطبيقات العادية ذاتية الخدمة. يتضمن scopes_supported في Discovery جميع أسماء الصلاحيات التي تتعرف عليها المنصة، ولا يعني أن تطبيقك يمكنه طلب كل واحدة منها. يتحقق التفويض الفعلي في الوقت نفسه من:
  1. ما إذا كانت الصلاحية مسموحًا بتفويضها لنوع هذا التطبيق؛
  2. ما إذا كانت الصلاحية مسجّلة ضمن النطاقات المسموح بها لتطبيق OAuth هذا؛
  3. ما إذا كان المستخدم الحالي يملك الصلاحية المطلوبة.
تُرجع الصلاحيات غير المعروفة أو غير المسجّلة أو غير المسموح بتفويضها أو التي لا يملكها المستخدم invalid_scope. ويُعاد التحقق أيضًا عند استبدال رمز التفويض وعند التحديث، ولا تُستكمل الصلاحيات أو تُرفع تلقائيًا.

الصلاحيات الاختيارية للتطبيقات العادية ذاتية الخدمة

فيما يلي الكتالوج الحالي (2026-10-09)؛ اعتمد على available_scopes عند التكامل. على سبيل المثال، استخدم profile:read لقراءة الملف الشخصي فقط؛ وأضف email:read عند الحاجة إلى البريد الإلكتروني؛ واستخدم profile:read credentials:read لقراءة API Key الحالية. لا تطلب credentials:write إلا عند الحاجة الفعلية إلى إنشاء Key أو تعديله، وأضف offline_access عند الحاجة إلى التحديث. بعض الصلاحيات متاحة فقط للتطبيقات الموثوقة المعتمدة من المنصة، مثل sites:read وsites:write وplatform-tokens:read؛ ولا تكون صلاحيات أخرى متاحة لتطبيقات OAuth العادية التابعة لأطراف ثالثة. يصف نوع العميل public/confidential ما إذا كان يمكنه حفظ secret، ولا يتعلق بما إذا كان التطبيق موثوقًا. لا يمكن للتطبيقات المنشأة ذاتيًا تفعيل الصلاحيات الموثوقة بنفسها. account هو منتقي صلاحيات الحساب الذي يستخدمه MCP الرسمي المحدد لإدارة الحسابات، وليس scope «جميع الصلاحيات» لتطبيقات الأطراف الثالثة، ولا يمكن استخدامه مع scope أخرى. ينبغي للأطراف الثالثة أن تسرد بوضوح الصلاحيات المحددة التي تحتاجها.

الترحيل من المستندات القديمة

لا تُقبل الأسماء القديمة كأسماء مستعارة متوافقة. حدّث في الوقت نفسه scopes المسجّلة لتطبيق OAuth وAuthorization URL والتحقق من الصلاحيات الخاص بك؛ لا يؤدي تعديل إعدادات التطبيق إلى إضافة صلاحيات إلى token الصادرة بالفعل، ويجب على المستخدم إعادة التفويض.

الخطوة 1: تسجيل تطبيق OAuth

افتح إدارة تطبيقات OAuth، وأنشئ تطبيقًا واملأ:
  • الاسم، الوصف، وشعار التطبيق: تُعرض على أحد جانبي التطبيق في صفحة التفويض.
  • نوع العميل: اختر Public للعملاء الأماميين البحتين، أو عملاء الأجهزة المحمولة أو سطح المكتب؛ واختر Confidential للخدمات التي يمكنها حفظ secret في الخلفية.
  • عنوان إعادة التوجيه: استخدم HTTPS في بيئة الإنتاج، وسجّل عنوان URL الكامل الذي يعالج فيه التطبيق رد الاتصال فعليًا.
  • الصلاحيات: اختر scopes المطلوبة فعليًا من الدليل الذي توفره الصفحة.
احفظ client_id. على عملاء Confidential حفظ client_secret على الخادم، ولا يجوز وضعه في HTML أو متغيرات بناء الواجهة الأمامية أو URL. لا تستخدم عملاء Public secret عند استبدال token، وحتى إذا تضمّن رد التسجيل هذا الحقل، فلا يجوز اعتباره بيانات اعتماد يمكن للعميل الحفاظ على سريتها. يجب أن يكون redirect_uri متطابقًا تمامًا عند التسجيل والتفويض واستبدال token، بما في ذلك المسار والشرطة المائلة الختامية ومعلمات الاستعلام. يمكن لكل حساب إنشاء ما يصل إلى 20 تطبيقًا. لا يظهر Secret إلا عند الإنشاء/التدوير؛ بعد التدوير، لا يمكن للـ secret القديم الاستمرار في إجراء عمليات الاستبدال التي تتطلب مصادقة العميل.

الخطوة 2: يبدأ الزر التفويض

في كل مرة يتم فيها النقر على الاتصال، أنشئ state وcode_verifier عشوائيين جديدين، واحسب:
احفظ state وverifier وعنوان رد الاتصال في جلسة التطبيق الخاصة، ثم افتح صفحة التفويض باستخدام المعلمات المشفرة بـ URL:
يجب على عملاء Public إرسال S256 PKCE. رغم أن Discovery لا يزال يسرد plain، لا يجوز لعملاء Public استخدامه. يُوصى أيضًا بأن يستخدم عملاء Confidential S256؛ إذا تم استخدام PKCE عند بدء التفويض، فيجب إرسال verifier المقابل عند الاستبدال. بعد موافقة المستخدم، يعود إلى redirect_uri، وتتضمن معلمات الاستعلام code وstate المعاد كما هو. عند الرفض، يتم إرجاع error=access_denied ووصف الخطأ وstate. تحقّق أولًا من تطابق state مع الجلسة الحالية قبل معالجة رد الاتصال. مدة صلاحية رمز التفويض هي 10 دقائق، ولا يمكن استبداله إلا مرة واحدة؛ بعد الفشل، يجب بدء الاتصال من جديد، ولا تكرر تحديث URL قديم لرد الاتصال.

الخطوة 3: استبدال OAuth token

يستبدل عملاء Public مباشرة من المتصفح أو العميل؛ ويستبدل عملاء Confidential من الخلفية الخاصة بهم. يدعم نص الطلب الترميز بالنموذج، وتمثل المتغيرات التالية البيانات التي حصل عليها التطبيق من هذا التفويض:
يجب على عملاء Confidential أيضًا إضافة حقل نموذج client_secret على الخادم. يدعم حاليًا client_secret_post، ولا تتعامل مع مصادقة عميل HTTP Basic على أنها طريقة مدعومة. اقرأ من الاستجابة الناجحة access_token وtoken_type وexpires_in وscope الممنوحة فعليًا. لا يوجد refresh_token إلا عند طلب offline_access والموافقة عليه. لا تعامل OAuth access token على أنه API Key لواجهة API الخاصة بالنموذج، ولا تكتب token أو verifier أو رمز التفويض في السجلات أو أحداث التحليلات أو روابط المشاركة.

الخطوة 4: قراءة معلومات المستخدم وAPI Key

استخدم أولًا OAuth access token لطلب UserInfo:
تعتمد الحقول المعادة على scope: يمثّل id معرّف المستخدم؛ ويمكن لـ profile:read أو openid قراءة البيانات الأساسية (مثل username وnickname وavatar وis_verified وdate_joined وregistration_method)؛ ويتطلب البريد الإلكتروني email:read، بينما يتطلب رقم الهاتف والمنطقة phone:read. لا تعتمد على وجود الحقول غير المصرح بها دائمًا. عند الحاجة إلى API Key موجودة مسبقًا والحصول على credentials:read، استخدم id من UserInfo كشرط تصفية:
تستخدم القائمة المعادة count وitems، وحقل Key هو items[*].token، وليس data[0].value. إن user_id=me ليس معرّف مستخدم صالحًا لهذه الواجهة. تابع قراءة البيانات متعددة الصفحات باستخدام offset/limit، ولا تعامل الصفحة الأولى على أنها جميع بيانات الاعتماد. اختر بيانات الاعتماد المناسبة وفقًا للتطبيق والخدمة وحالة الصلاحية، ولا تأخذ الأولى بشكل أعمى. لا تعني القائمة الفارغة فشل التفويض؛ فقد لا يكون المستخدم قد أنشأ Key مناسبة بعد. إن التحكم في صلاحيات OAuth access token وقيود نطاق الخدمة والحصة وشروط انتهاء الصلاحية الخاصة بـ API Key نفسها هي قيود مختلفة. السماح بقراءة API Key يعني أن طرفًا ثالثًا يمكنه حفظها واستخدامها. لن يؤدي إلغاء طلب OAuth أو مسح حالة تسجيل دخول التطبيق إلى إبطال API Key التي تم نسخها بالفعل؛ يحتاج المستخدم إلى إبطال أو تدوير تلك Key بشكل منفصل في إدارة بيانات الاعتماد.

مثال متصفح Public / PKCE قابل للتشغيل

انشر الصفحة التالية على REDIRECT_URI الذي سجلته، واستبدل CLIENT_ID وعنوان رد الاتصال. يبدأ الزر التفويض القياسي، وبعد العودة إلى الصفحة نفسها يقرأ الملف الشخصي وعدد Key الموجودة. لا يعرض المثال Key ولا يحفظها بشكل دائم؛ يستهلك تطبيق الإنتاج النتائج وفقًا للاستخدام الفعلي. تحقّق أولًا في صفحة متصفح مستقلة، ثم اقبل وفقًا لمتطلبات iframe اللاحقة.
يجب أن تكون عملية الاستدعاء ونقطة الدخول في المثال ضمن نفس المصدر، وفي علامة تبويب المتصفح/iframe نفسها، حتى يمكن قراءة sessionStorage المحفوظة مسبقًا. يجب أن يدير تطبيق الإنتاج الرموز المميزة ضمن مخطط الجلسة الخاص به، وأن يعالج انتهاء الصلاحية، وأن يمسح معلمات عنوان URL للتفويض عند تلقي الاستجابة؛ ويجب عرض الواجهة الرئيسية للصفحة أولًا، بحيث تؤثر إخفاقات الشبكة في حالة الاتصال فقط.

iframe في مواقع العلامة البيضاء

انتقال موقع العميل بنفسه إلى صفحة التفويض

يكفي استخدام معلمات OAuth القياسية ومعالجة الاستدعاء الخاصة به؛ إذ يقوم window.location.assign() بتوجيه iframe الحالي، بينما تبقى الصفحة الأصلية ضمن نطاق العلامة البيضاء. لا حاجة إلى إضافة embed=studio لأجل الأيقونة أو تنفيذ بروتوكول رسائل Studio. يجب استيفاء الشروط التالية:
  • تستخدم صفحة التطبيق وصفحة الاستدعاء HTTPS، ويمكن الوصول إليهما فعليًا، وتسمحان بتضمين نطاق العلامة البيضاء الأصل عبر iframe؛ تحقق من Content-Security-Policy: frame-ancestors وX-Frame-Options لدى الطرفين.
  • يسمح sandbox بالنصوص البرمجية والنماذج وقدرات المصدر/التخزين التي تحتاجها الصفحة. عند دعم تسجيل الدخول عبر النوافذ المنبثقة، يلزم أيضًا توفر قدرات النوافذ المنبثقة المقابلة؛ يُفضّل استخدام إعدادات مكوّن Website التي يوفرها Studio.
  • يسمح المتصفح باستخدام التخزين المطلوب لحالة التفويض ضمن سياق التضمين الحالي. قد تختلف حالة تسجيل الدخول إلى موقع العلامة البيضاء عن حالة تسجيل الدخول إلى AuthFrontend، ولا ينبغي افتراض أن تسجيل الدخول إلى موقع العلامة البيضاء يعني تسجيل الدخول إلى صفحة التفويض.
  • تكون خدمة تبادل الرموز المميزة في الاستدعاء متاحة، وتسمح الطلبات عبر النطاقات بمصدر التطبيق؛ يجب عرض حالة قابلة لإعادة المحاولة لأخطاء DNS وCORS وHTTP، ولا يجوز إيقاف عرض الصفحة بالكامل.
تقرأ صفحة التفويض شعار تطبيق OAuth على اليسار؛ وعلى اليمين، تقرأ favicon/logo الخاص بهذا Site عندما يستطيع المتصفح توفير المصدر الأب ويجتاز النطاق الأب تحقق الموقع الموثّق، وإلا تعرض الأيقونة الافتراضية. يحدد هذا عرض العلامة التجارية فقط، ولا ينشئ جلسة تسجيل دخول، ولا يوفّر صلاحيات الحساب لصفحة العميل. القيود الحالية: عند الحاجة إلى إعادة تسجيل الدخول داخل iframe في OAuth العادي، لا تزال توجد فجوة في تدفق العودة إلى صفحة التفويض بعد اكتمال تسجيل الدخول. قبل الإطلاق، يجب قبول حالتي «Auth مسجّل الدخول» و«Auth غير مسجّل الدخول/منتهية صلاحيته» كل على حدة. قبل إصلاح هذه الفجوة والتحقق منها، يمكن لإتمام تسجيل الدخول الأول استخدام صفحة مستقلة لإكمال OAuth القياسي، أو استخدام تفويض مكوّن Studio أدناه؛ لا تعتمد فقط على نتائج اختبار تسجيل الدخول لتتعهد بأن جميع سيناريوهات iframe قابلة للاستخدام.

استخدام حساب Studio الحالي للتفويض

فعّل OAuth في Studio عبر «الإعدادات → الصفحة الرئيسية → مكوّنات الموقع»، واملأ client_id وعنوان الاستدعاء المسجّل. يجب أن يستخدم الموقع والاستدعاء نفس مصدر HTTPS، وأن يكونا مختلفين عن مصدر Studio. تحتاج صفحة الطرف الثالث إلى:
  1. إرسال acedatacloud:oauth:ready إلى origin الدقيق للموقع الأب، واستقبال acedatacloud:oauth:init والتحقق منه.
  2. أن ينشئ الزر state وPKCE verifier، ويرسل acedatacloud:oauth:authorize ‏(state، وتحدي S256)؛ ويبقى verifier داخل صفحته الخاصة.
  3. التحقق من النافذة الأب وorigin وstate، ومعالجة code أو error في acedatacloud:oauth:result، والتبادل عبر نقطة نهاية الرموز المميزة القياسية. يعرض Studio صفحة التفويض في منطقة المكوّن، وبعد موافقة المستخدم يعيد رمز التفويض عبر رسالة، ولا يحتاج التطبيق إلى إعادة التوجيه. عند عدم تسجيل الدخول يعيد login_required، وعند الرفض يعيد access_denied، وعند انتهاء مهلة الانتظار يعيد authorization_timeout. يؤدي تغيّر الحساب إلى إعادة إنشاء iframe الخاص بالتطبيق وإلغاء التفويضات غير المكتملة.
يطلب المكوّن حاليًا profile:read credentials:read، ولا يتضمن offline_access. لا تفترض أنه يمكن دائمًا تلقي refresh token. تتم صيانة embed=studio وembed_origin بواسطة مضيف Studio وصفحة التفويض، وتحتاج صفحة العميل فقط إلى الالتزام ببروتوكول الرسائل. راجع المثال الكامل للزر في دليل تكامل OAuth لمكوّن موقع Studio.

دورة الحياة والتحديث والإلغاء

مدة صلاحية Access token الافتراضية هي 15 يومًا، ويجب ترتيب التحديث أو إعادة التفويض وفقًا لـ expires_in في كل استجابة؛ ومدة صلاحية refresh token الافتراضية هي 30 يومًا، وتتأثر المدة بإعدادات الخدمة. لا تقم بترميز هاتين القيمتين بشكل ثابت على أنهما التزامان دائمان. بعد منح offline_access، يمكن استدعاء:
سيعيد التحديث token جديدًا، ويجب على التطبيق حفظ أحدث قيمة. أثناء التحديث، يتم التحقق مما إذا كان التطبيق لا يزال صالحًا، وما إذا كان المستخدم متاحًا، وما إذا كانت الصلاحيات لا تزال ممنوحة. عند الفشل، امسح حالة الاتصال الخاصة بك وأعد التفويض. لا يضمن تنفيذ تحديث OAuth الحالي أن refresh token القديم يصبح غير صالح فورًا بعد التحديث. لا تعتبر الحصول على token جديد يعني أن token القديم قد أُلغي، ولا تستبدل إنهاء tokenات الموجودة بتدوير secret. طريقة استدعاء طلب الإلغاء هي:
تعيد نقطة نهاية الإلغاء الحالية HTTP 200، لكنها لا تطبّق الإبطال الفوري لـ JWT التي تم إصدارها. يجب على التطبيق مسح tokenات المحفوظة لديه، ولا يمكن اعتبار 200 دليلًا على أن جميع tokenات أو API Key التي تم إصدارها أصبحت غير صالحة. بالنسبة إلى API Key التي تم تسريبها أو نسخها، يجب إلغاء بيانات الاعتماد المقابلة أو تدويرها بشكل منفصل.

الأخطاء الشائعة والقبول

قبل التسليم، تحقق على الأقل من: رد الاتصال الصحيح، والرفض، وstate الخاطئة، وcode المنتهي الصلاحية/المستهلك، وعدم وجود Key، وفشل الشبكة، وانتهاء صلاحية token، وغياب scope المطلوبة، وكذلك تسجيل الدخول لأول مرة وتبديل الحساب في سيناريو iframe. لا تحفظ code أو token أو API Key كاملة في أدلة الاختبار.

التحقق بخطوتين وإعادة التفويض

بعد أن يفعّل المستخدم التحقق بخطوتين، تُكمل Ace Data Cloud التحقق من رمز تطبيق المصادقة أو رمز الاسترداد لمرة واحدة في صفحة التفويض، ثم تسلّم رمز التفويض. يجب أن يواصل تطبيقك استخدام تدفق OAuth القياسي، وألا يطلب من المستخدم مفاتيح تطبيق المصادقة أو رموز الاسترداد أو يحفظها أو يعيد توجيهها. بعد أن يفعّل المستخدم التحقق بخطوتين أو يغيّره أو يعطّله أو يستعيد حسابه، قد تصبح جلسات الحساب السابقة، ورموز التحديث، ورموز تفويض المنصة ذات الصلة غير صالحة. عند تلقي جلسة غير صالحة أو invalid_grant، أعد بدء تدفق تفويض مرئي للمستخدم، ولا تستخدم رمز التفويض القديم مرارًا، ولا تحاول تجاوز التحقق. تبقى طريقة مصادقة API Key العادية للنموذج دون تغيير؛ وإذا اشتُبه في اختراق الحساب، فيجب فحص وإلغاء API Key المتأثرة بشكل منفصل.