المصادقة · security
معمارية OAuth ودورة حياة الرموز
سلوك متحقق لرمز التفويض وPKCE S256 والتبادل وتدوير التحديث والتخزين والإلغاء.
معمارية OAuth ودورة حياة الرموز
يتضمن هذا التنفيذ تسجيل دخول التاجر واختيار المتجر والموافقة الصريحة على الربط. تبقى ميزة السوق معطلة في سياسة الإصدار الحالية إلى حين إكمال فحوص الأحداث والبيئة الشاملة. البيئة المعطلة لا تقدم خدمة تفويض؛ هذا المرجع ليس إعلاناً بإطلاق السوق.
بدء التفويض
وجّه المتصفح إلى GET /api/oauth/authorize مع المعاملات السبعة التالية. تفتح النقطة صفحة الموافقة داخل المنصة باللغة المناسبة. يمكنك استخدام /ar/oauth/authorize أو /en/oauth/authorize لتحديد اللغة صراحة.
| المعامل | القيمة المطلوبة |
|---|---|
client_id | UUID التطبيق المراجع |
response_type | code |
redirect_uri | عنوان مطابق حرفياً لأحد عناوين الإصدار المنشور والمراجع حالياً |
scope | صلاحيات مدعومة ومعلنة في الإصدار، تفصلها مسافات ومن دون تكرار |
code_challenge | SHA-256 لقيمة verifier عالية العشوائية، بترميز Base64url دون padding |
code_challenge_method | S256 |
state | قيمة عشوائية تربط طلبك بجلسة واحدة، بحد أقصى 512 حرفاً |
تُرفض المعاملات غير المعروفة أو المكررة. يلزم HTTPS للعودة، باستثناء عناوين HTTP المحلية المسجلة للتطوير. أنشئ verifier وstate جديدتين لكل رحلة واحفظهما في الخادم. لا تعيد المنصة توجيه التاجر إلى عنوان لم تتحقق منه.
مراجعة التاجر
يسجل التاجر دخوله ويعود إلى صفحة الموافقة. تعرض الصفحة اسم التطبيق وإصداره ووصف الصلاحيات من النسخة المراجعة. يمكنه اختيار متجر نشط يملك فيه دور المالك أو المدير فقط. فتح الصفحة لا يمنح أي صلاحية. يجب أن يوافق أو يرفض صراحة خلال خمس دقائق.
تنجح الموافقة ما دامت النسخة المنشورة وعضوية التاجر والمتجر والتثبيت القائم مطابقة لما راجعه. أي تغيير يتطلب رحلة جديدة. طلب رمز بصلاحيات أقل من صلاحيات تثبيت قائم لا يمسح بقية صلاحياته تلقائياً؛ يقتصر الرمز الناتج على الصلاحيات المطلوبة والمتجر المختار.
ترسل الصفحة المراجعة ذات الاستخدام الواحد إلى إجراء داخل المنصة من المصدر نفسه وبجلسة مصادق عليها عبر POST /api/oauth/authorize. يبدأ التطبيق الخارجي باستخدام GET؛ إرسال معرف تثبيت أو صلاحيات عشوائية مباشرة ليس عقد الموافقة. يلزم JavaScript لإرسال الصفحة والانتقال إلى عنوان العودة.
العودة وتبادل الرمز
تعيد الموافقة code وstate الأصلية إلى العنوان المسجل المطابق. يعيد الرفض error=access_denied وstate دون رمز. تحقق من state قبل أي إجراء. إذا تعذر تأكيد النتيجة، ابدأ رحلة جديدة بدلاً من تكرار إرسال موافقة قديمة.
استخدم POST /api/oauth/token مع grant_type=authorization_code وclient_id وcode وredirect_uri نفسه وcode_verifier الأصلية. تُقبل بيانات form وJSON ولا يوجد client secret. تقبل النقطة أيضاً منحة refresh_token.
خصائص الرموز
- عمر رمز الوصول 15 دقيقة، وعمر رمز التحديث الذي يدور عند الاستخدام 30 يوماً.
- ترتبط الاعتمادات بالمطور والتطبيق النشطين والإصدار المراجع المثبت بعينه وجيل تفويض التثبيت.
- ترتبط الصلاحيات المراجعة أيضاً بعقود تشغيل ذات إصدارات؛ توسيع العقد يتطلب مراجعة وموافقة جديدتين.
- لا تُخزّن إلا تجزئات الرموز في حالة السكون.
- يُستهلك رمز التفويض مرة واحدة. إعادة استخدام رمز التحديث تلغي عائلته ورموز وصول التثبيت.
التخزين الآمن والإلغاء
احفظ الرموز وverifier في تخزين خادمي مشفر. لا تضعها في تخزين المتصفح أو الروابط أو التحليلات أو الصور أو تذاكر الدعم أو السجلات. احجب ترويسات التفويض واستجابات الرموز. تمنع استجابات الموافقة التخزين المؤقت وإرسال المرجع والتضمين داخل الإطارات.
يمسح إلغاء التثبيت الصلاحيات ويعطل الاشتراكات ويلغي التفويض المشتق. يؤدي تعليق المطور أو فقدان صلاحية الإصدار المراجع أيضاً إلى الرفض. تنشئ إعادة التثبيت تفويضاً جديداً ولا تعيد إحياء الرموز القديمة. يُفحص الإلغاء قبل السماح بالإرسال وبعد التحقق من DNS؛ لا يمكن استرجاع طلب سُمح له بالدخول إلى الشبكة بالفعل. على المستلم منع تكرار معرفات الأحداث واحترام إلغاء وصول التاجر.