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.
من أين تحصل على الصلاحيات القابلة للطلب
بعد تسجيل الدخول، تُرجع واجهة قائمة تطبيقات OAuthGET /api/v1/oauth2/applications/ القيمة available_scopes؛ ويستخدم منتقي الصلاحيات في صفحة إدارة التطبيقات الكتالوج نفسه. هذه هي النطاقات الاختيارية التي ينبغي أن تعتمدها التطبيقات العادية ذاتية الخدمة.
يتضمن scopes_supported في Discovery جميع أسماء الصلاحيات التي تتعرف عليها المنصة، ولا يعني أن تطبيقك يمكنه طلب كل واحدة منها. يتحقق التفويض الفعلي في الوقت نفسه من:
- ما إذا كانت الصلاحية مسموحًا بتفويضها لنوع هذا التطبيق؛
- ما إذا كانت الصلاحية مسجّلة ضمن النطاقات المسموح بها لتطبيق OAuth هذا؛
- ما إذا كان المستخدم الحالي يملك الصلاحية المطلوبة.
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:
plain، لا يجوز لعملاء Public استخدامه. يُوصى أيضًا بأن يستخدم عملاء Confidential S256؛ إذا تم استخدام PKCE عند بدء التفويض، فيجب إرسال verifier المقابل عند الاستبدال.
بعد موافقة المستخدم، يعود إلى redirect_uri، وتتضمن معلمات الاستعلام code وstate المعاد كما هو. عند الرفض، يتم إرجاع error=access_denied ووصف الخطأ وstate. تحقّق أولًا من تطابق state مع الجلسة الحالية قبل معالجة رد الاتصال. مدة صلاحية رمز التفويض هي 10 دقائق، ولا يمكن استبداله إلا مرة واحدة؛ بعد الفشل، يجب بدء الاتصال من جديد، ولا تكرر تحديث URL قديم لرد الاتصال.
الخطوة 3: استبدال OAuth token
يستبدل عملاء Public مباشرة من المتصفح أو العميل؛ ويستبدل عملاء 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: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 اللاحقة.
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، ولا يجوز إيقاف عرض الصفحة بالكامل.
استخدام حساب Studio الحالي للتفويض
فعّل OAuth في Studio عبر «الإعدادات → الصفحة الرئيسية → مكوّنات الموقع»، واملأclient_id وعنوان الاستدعاء المسجّل. يجب أن يستخدم الموقع والاستدعاء نفس مصدر HTTPS، وأن يكونا مختلفين عن مصدر Studio. تحتاج صفحة الطرف الثالث إلى:
- إرسال
acedatacloud:oauth:readyإلى origin الدقيق للموقع الأب، واستقبالacedatacloud:oauth:initوالتحقق منه. - أن ينشئ الزر state وPKCE verifier، ويرسل
acedatacloud:oauth:authorize(state، وتحدي S256)؛ ويبقى verifier داخل صفحته الخاصة. - التحقق من النافذة الأب و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، يمكن استدعاء:
الأخطاء الشائعة والقبول
قبل التسليم، تحقق على الأقل من: رد الاتصال الصحيح، والرفض، وstate الخاطئة، وcode المنتهي الصلاحية/المستهلك، وعدم وجود Key، وفشل الشبكة، وانتهاء صلاحية token، وغياب scope المطلوبة، وكذلك تسجيل الدخول لأول مرة وتبديل الحساب في سيناريو iframe. لا تحفظ code أو token أو API Key كاملة في أدلة الاختبار.
التحقق بخطوتين وإعادة التفويض
بعد أن يفعّل المستخدم التحقق بخطوتين، تُكمل Ace Data Cloud التحقق من رمز تطبيق المصادقة أو رمز الاسترداد لمرة واحدة في صفحة التفويض، ثم تسلّم رمز التفويض. يجب أن يواصل تطبيقك استخدام تدفق OAuth القياسي، وألا يطلب من المستخدم مفاتيح تطبيق المصادقة أو رموز الاسترداد أو يحفظها أو يعيد توجيهها. بعد أن يفعّل المستخدم التحقق بخطوتين أو يغيّره أو يعطّله أو يستعيد حسابه، قد تصبح جلسات الحساب السابقة، ورموز التحديث، ورموز تفويض المنصة ذات الصلة غير صالحة. عند تلقي جلسة غير صالحة أوinvalid_grant، أعد بدء تدفق تفويض مرئي للمستخدم، ولا تستخدم رمز التفويض القديم مرارًا، ولا تحاول تجاوز التحقق. تبقى طريقة مصادقة API Key العادية للنموذج دون تغيير؛ وإذا اشتُبه في اختراق الحساب، فيجب فحص وإلغاء API Key المتأثرة بشكل منفصل.
