أضف زر «اتصل بكورتيكسا» عبر OAuth 2.0
لتطبيق منشور لعملاء كثيرين، استخدم تدفق رمز التفويض مع PKCE: يوافق العميل على شاشة الأذونات، فتستبدل الرمز برمز وصول يبدأ بـcrtk_oauth_ ورمز تجديد.
قبل أن تبدأ · شيء واحد · للمالكتطبيقك مسجّل لدى فريق كورتيكسا
قبل أن تبدأ · شيء واحد · للمالك
تطبيقك مسجّل لدى فريق كورتيكسا
- تسجيل تطبيقك لدى فريق كورتيكسا: الاسم، وروابط إعادة التوجيه، والنطاقات المسموحة، ونوع العميل. تحصل على
client_idيبدأ بـcrtk_app_وسر للتطبيقات ذات الخادم.
الخطوات
1
وجّه متصفح المستخدم إلى
https://{HOST}/en/oauth/authorize مع client_id وredirect_uri وscope وstate وresponse_type=code، وcode_challenge مع code_challenge_method=S256 للعملاء العامين.هذه شاشة الموافقة في تطبيق كورتيكسا. المستخدم غير المسجّل دخوله يُوجَّه إلى تسجيل الدخول ولا يعود إلى هذه الشاشة، فعليه أن يبدأ الربط من تطبيقك من جديد.
2
يضغط المستخدم منح الصلاحية، أو إلغاء للرفض.
يعود المتصفح إلى رابطك بـ
?code=...&state=...، أو ?error=access_denied.3
تحقق من
state.4
من خادمك أرسل
POST https://{HOST}/api/v1/oauth/token بـgrant_type=authorization_code وcode وredirect_uri وclient_id وclient_secret أو code_verifier.الرد JSON قياسي:
access_token وrefresh_token وexpires_in وscope.5
احفظ المضيف والرموز وتاريخ الانتهاء لكل عميل، واستدعِ API بـ
Authorization: Bearer crtk_oauth_....6
جدّد قبل الانتهاء بـ
grant_type=refresh_token، واحفظ رمز التجديد الجديد في كل مرة.لا تستدعِ نقطة الرموز من المتصفح، ولا تضع client_secret أو أي رمز crtk_oauth_ في شيفرة الواجهة الأمامية.
نوعا العملاء
النوع
لمن
المصادقة
سرّي (confidential)
تطبيق له خادم
client_secretعام (public)
تطبيق صفحة واحدة أو جوال
PKCE (S256) إلزامي، بلا سر
القواعد
رابط إعادة التوجيه يطابق المسجّل حرفياً. الرمز يُستخدم مرة واحدة خلال 60 ثانية. النطاق الممنوح ضمن المطلوب، والمطلوب ضمن المسموح للتطبيق، والكل ضمن صلاحيات المستخدم الحية.
النطاقات بنجمة مثل read.* تشمل كل وحدة يصل إليها المستخدم، فيختار تطبيقك أي وحدة للمزامنة دون إعادة تسجيل.
الإلغاء
ألغِ من خادمك بـPOST /api/v1/oauth/revoke مع token وclient_id وclient_secret. أو يفصل العميل تطبيقك من امنح تطبيقاً خارجياً صلاحية الوصول أو اقطع اتصاله، فتتوقف الرموز فوراً.
إذا حدثت مشكلة
ما تراه
السبب
الحل
شاشة «تعذّر ربط هذا التطبيق»
client_id غير معروف، أو رابط إعادة التوجيه لا يطابق، أو نطاق غير مسموح، أو PKCE ناقص.صحّح طلب التفويض. لن يُعاد توجيه المتصفح عند الخطأ.
«ليس لديك الصلاحية لمنح الوصول الذي يطلبه هذا التطبيق.»
المستخدم لا يملك الصلاحيات.
اطلب نطاقات أقل، أو يرفع المالك صلاحياته.
invalid_grant: code is invalid, expired, or already usedالرمز قديم أو مستخدم.
استبدله فوراً بعد الرجوع.
invalid_grant: redirect_uri mismatchالرابط مختلف بحرف.
استخدم نفس الرابط في الخطوتين.
invalid_clientسر خطأ أو تطبيق غير نشط.
تحقق من بيانات التطبيق.
قواعد يجب معرفتها
رمز الوصول نحو ساعة، ورمز التجديد نحو 30 يوماً ويُستبدل في كل تجديد.
استخدام رمز تجديد قديم يُعتبر تسريباً ويُلغي كل رموز ذلك الاتصال.
اسم التطبيق حتى 120 حرفاً، والوصف حتى 500.
روابط إعادة التوجيه HTTPS، ويُقبل http على localhost للتطوير.
تسجيل التطبيقات عبر فريق كورتيكسا فقط.
هل حلّ هذا الدليل مشكلتك؟
إن لم يحلها، سنسألك عمّا كان ناقصاً.