استكشاف منح OIDC: فهم واستكشاف خطأ "invalid_grant"

الخلفية#

في مجتمعنا، غالبًا ما نسمع سؤالًا متكررًا من مستخدمينا: ما المشكلة في خطأ "invalid_grant" في Logto؟ مثل #503

إنه تحدٍ شائع ومعيق لبعض مستخدمينا عند دمج Logto في تطبيقاتهم الخاصة. ومع ذلك، تختلف الأسباب وراء هذا الخطأ من حالة لأخرى، وأحيانًا يكون من الصعب تفسيرها بالسياق المحدود المتاح. لذا، فإن فهم مفهوم OIDC بالضبط وتعلم كيفية استكشاف المشكلة أمر ضروري للجميع.

لنتعمق الآن في أساسيات منح OIDC.

شرح منح OIDC#

كما قدمنا في منشور مدونة سابقًا، يُعتبر OpenID Connect (OIDC) بروتوكولًا مبنيًا على OAuth 2.0.

في سياق OIDC أو OAuth2، يُعتبر المنح مجموعة من الأذونات الممنوحة من قبل مالك المورد (عادةً المستخدم) إلى تطبيق العميل. المنح ضرورية لتطبيق العميل ليتمكن من الوصول إلى معلومات هوية المستخدم وغيرها من الموارد المحمية. يعرف OIDC عدة أنواع من المنح، كل منها مناسب لسيناريو مختلف وطريقة حصول التطبيق على رمز الوصول.

إليك تشبيهًا لمساعدتك على فهم منح OIDC بشكل أفضل.

تخيل أنك تسافر إلى دول مختلفة، وكل دولة تطلب تأشيرة دخول (فيزا) للدخول. في هذا السيناريو، يُعتبر جواز سفرك حساب المستخدم الخاص بك، والذي يحتوي على معلوماتك الشخصية. منح OIDC مثل الطرق التي تقدم بها طلب الحصول على تأشيرة لدخول بلد ما. عندما تُصدر لك التأشيرة، فإنك تحصل على "رمز" لدخول البلد.

وبالمثل، عند استخدام تطبيق، يكون طلب المنح هو الإجراء الذي تطلب من خلاله من خادم التفويض منحك إذن الوصول. يقوم خادم التفويض بالتحقق من هويتك، ثم يُصدر لك "التأشيرة" (رمز الوصول) لتسجيل الدخول إلى التطبيق.

أنواع منح OIDC المستخدمة بشكل شائع:#

1. منحة رمز التفويض: هذا هو النوع الأكثر شيوعًا في OIDC. يتضمن إعادة توجيه المستخدم إلى خادم التفويض، والحصول على رمز التفويض، وإعادة التوجيه إلى التطبيق وتبادل الرمز للحصول على رمز الوصول. فكّر فيه كالإجراء القياسي لتقديم طلب للحصول على تأشيرة من السفارة قبل دخول بلد أجنبي.
2. منحة رمز التحديث: في OIDC، يتيح هذا النوع من المنح لتطبيق العميل الحصول على رمز وصول جديد باستخدام رمز تحديث تم إصداره مسبقًا. يُستخدم عادةً لتمديد جلسة المستخدم دون الحاجة إلى إعادة دخول بياناتهم. تخيل أن تأشيرتك تأتي مع بطاقة سحرية تتيح لك تمديد إقامتك في البلد الأجنبي دون المرور عبر الجمارك مرة أخرى.
3. منحة ضمنية: يُستخدم هذا النوع من المنح لتطبيقات الويب القديمة وهو أقل أمانًا من منحة رمز التفويض. يُعيد رمز الوصول مباشرةً إلى تطبيق العميل. يعمل كالتأشيرة عند الوصول، حيث لا يتطلب طلب تأشيرة مسبقًا.
4. منحة بيانات الاعتماد للعميل: مناسب للاتصال من خادم إلى خادم، يتيح هذا النوع من المنح لتطبيق العميل المصادقة مباشرة باستخدام بيانات الاعتماد الخاصة به (معرف العميل وسر العميل). يشبه ذلك عميلًا خاصًا يعرض شارة عمل خاصة لدخول البلد دون المرور بإجراءات طلب التأشيرة.

نموذج عناصر المنح:#

في Logto، يتم تخزين المنح في قاعدة البيانات ككائن يحتوي على معلومات مثل معرف حساب المستخدم، ومعرف التطبيق، والموارد ذات الصلة في OIDC والنطاقات، ووقت الانتهاء، والمزيد. يرتبط كل رمز تحديث ورمز وصول بكائن منح محدد.

طلبات المنح:#

طلبات HTTP المقدمة إلى خادم التفويض عبر واجهات برمجة التطبيقات. يمكن لتطبيق العميل إرسال طلبات المنح إلى نقطة نهاية رمز OIDC لأغراض متنوعة، بما في ذلك التقديم للحصول على منحة جديدة (مثل تسجيل الدخول والحصول على رموز التحديث والوصول)، وتحديث تفاصيل المنح (مثل تبديل رمز تحديث بآخر جديد)، أو إلغاء المنحة (مثل إلغاء كل الرموز الصادرة لمستخدمين مسجلين وإنهاء وصولهم).

يبدو طلب منح رمز التفويض النموذجي كما يلي:

فهم خطأ "invalid_grant"#

ظهور خطأ invalid_grant في OIDC يشير عادةً إلى أن نوع المنح أو البيانات المرتبطة بطلب المنح غير صالحة أو لا تُدعم. إليك بعض الأسباب الشائعة وراء هذا الخطأ:

1. نوع المنح غير صحيح: استخدام نوع المنح الخاطئ لتطبيقك يمكن أن يؤدي إلى خطأ invalid_grant. تأكد من أنك تستخدم النوع المنح المناسب من خلال استثمار حزم تطوير البرامج (SDKs) الخاصة بـ Logto.
2. تطابق غير صحيح لعنوان URL لإعادة التوجيه: عند مبادلة رمز التفويض للحصول على الرموز، يجب أن يتطابق عنوان URL لإعادة التوجيه المستخدم في الطلب مع ذلك المستخدم خلال طلب التفويض الأولي. عدم التطابق يمكن أن يؤدي إلى خطأ invalid_grant.
3. رمز التفويض المنتهي أو المستهلك: في تدفق تسجيل الدخول برمز التفويض، يكون لرمز التفويض عمر محدود، وسيُعين كـ"مستهلك" بمجرد استخدامه للحصول على الرموز. محاولة مبادلة رمز منتهي أو مستهلك للحصول على رمز الوصول ستنتج عن خطأ invalid_grant.
4. رمز التحديث المنتهي أو المدور: عند مبادلة رمز التحديث للحصول على رمز الوصول، يحدث خطأ invalid_grant إذا كان رمز التحديث منتهي الصلاحية. بالإضافة إلى ذلك، لتعزيز الأمان، يمكّن Logto دوران رمز التحديث افتراضيًا. طلب نقطة النهاية بالرمز ذاته مرة ثانية يُعتبر استخدام رمز تحديث "مدور" وسيرفض.
5. البيانات الإلزامية أو رؤوس الطلب المفقودة: عند تكوين طلب المنح، يجب توفير المعلمات الإلزامية ورؤوس الطلب لنوع المنح المحدد. على سبيل المثال، يجب توفير معرف العميل في كل طلبات المنح، ويجب توفير معرف وسر العميل لمنح بيانات الاعتماد للعميل. يمكن تقليل هذا الخطر باستخدام استثمار حزم SDK الخاصة بـ Logto.
6. أسباب أخرى: يمكن أن يحدث هذا الخطأ أيضًا بسبب أسباب مثل عدم تطابق بيانات الاعتماد الخاصة بالعميل، انتهاء المنح أو عدم العثور عليها، عدم العثور على رمز التحديث، إلخ.

استكشاف الخطأ#

بعض النصائح لاستكشاف خطأ "invalid_grant" بفعالية:

1. استخدم دائمًا حزم SDK الخاصة بـ Logto لدمج Logto في تطبيقك، للتأكد من أن طلبات المنح تُقدم إلى نقطة النهاية المعنية ومع البيانات الصحيحة.
2. تحقق من أن بيانات اعتماد التطبيق الخاص بك وعناوين URL لإعادة التوجيه تتطابق مع التكوينات في وحدة التحكم الإدارية.
3. تجنب تقديم طلبات زائدة، خاصة لتطبيقات صفحة واحدة مثل React وVue، حيث يمكن أن تُعاد تقديم عناصر الصفحة في حالة تغيير التبعيات. تأكد من أن الدوال المستخدمة لتبادل الرموز أو تحديث الرموز للحصول على رموز الوصول لا تُطلق عدة مرات بنفس معلمات الطلب. هذا هو خطأ شائع يقوم به بعض مستخدمينا. عادةً إذا كنت ترى عدة طلبات "token" في وحدة تنظيف الأخطاء، ستكون الأولى ناجحة، لكن الباقي فاشل، تحقق من معلمات الطلب لمعرفة ما إذا كانوا يستخدمون نفس "الرمز" أو "رمز التحديث". تذكر، يمكنك استخدام الرمز ورمز التحديث مرة واحدة فقط في طلبات المنح.
4. تحقق من أوقات الانتهاء. على سبيل المثال، إذا انتهى رمز التحديث الخاص بك (افتراضيًا 14 يومًا) وتلقيت خطأ invalid_grant، ينبغي عليك التعامل معه بشكل صحيح من خلال بدء تدفق تسجيل دخول المستخدم مرة أخرى. إذا كنت تستخدم Logto SDK، يمكنك استدعاء دالة signIn() مرة أخرى لإعادة توجيه المستخدمين إلى صفحة تسجيل الدخول.
5. راقب سجلات التدقيق. انتقل إلى وحدة التحكم الإدارية → سجلات التدقيق، وابحث عن سجل الخطأ المرتبط بالحادث وتحقق من المسار التفصيلي للخطأ. عادةً، هناك سبب أكثر تحديدًا في مسار الخطأ وراء خطأ invalid_grant، مثل "المنح غير موجود" أو "انتهاء صلاحية رمز التحديث".

ملاحظات ختامية#

يمكن أن يكون خطأ invalid_grant تحديًا ومربكًا للمبتدئين، لكن بفهم واضح لمنح OIDC والانتباه للتفاصيل، يمكنك تحديد المشكلة ومعالجتها بنفسك. انضم إلى نقاشاتنا على Discord أو GitHub، وأخبرنا إذا ساعدت هذه المدونة في توضيح الالتباس وتحديد المشاكل التي تواجهها. يسعد فريق تطوير Logto دائمًا بمساعدتك.

معًا، لنبني تجربة تحقق سلسة وآمنة لتطبيقاتك المحبوبة.