تنفيذ SDK بسيط للعميل لـ OIDC

مقدمة#

Logto توفر للمطورين لدينا والمجموعات التجارية حلاً شاملاً لإدارة هوية العميل والوصول (CIAM). نحن نوفر مجموعة واسعة من SDKs الجاهزة للاستخدام للمنصات والأطر التطبيقية المختلفة. مع خدمة السحابة Logto، يمكنك بسهولة إنشاء تدفق تفويض المستخدم الآمن للغاية لتطبيقك في غضون دقائق. كشركة ولدت من مجتمع المطورين، ي embrace Logto وتقدر تفاعل مجتمعنا. بالإضافة إلى SDKs Logto التي تم تطويرها رسمياً، نشجع ونرحب بحرارة بالمطورين من المجتمع للمساهمة بخبراتهم من خلال إنشاء المزيد من SDKs المتعددة وسهلة الاستخدام، والتي تلبي الاحتياجات الفريدة للمنصات والأطر المختلفة. في هذه المقالة، سوف نوضح باختصار كيفية تنفيذ SDK مصدق قياسي لـ OIDC خطوة بخطوة.

السياق#

تدفق OpenID Connect (OIDC) هو بروتوكول مصدق يبنى على إطار OAuth 2.0 لتوفير التحقق من الهوية وقدرات تسجيل الدخول الفردي. يسمح للمستخدمين بالتحقق من هويتهم مع تطبيق والحصول على تفويض للوصول إلى أي موارد خاصة بشكل آمن. يرجى الرجوع إلى مواصفات OIDC لمزيد من التفاصيل.

سير العمل#

يتضمن تدفق رمز التفويض القياسي الخطوات التالية:

تدفق المصادقة#

1. المستخدم يشرع في طلب الدخول: يأتي مستخدم مجهول إلى تطبيقك من مدخل عام. يحاول الحصول على المصادقة وربما يطلب في وقت لاحق الوصول إلى مورد محمي في تطبيق أو خدمة طرف ثالث.
2. مصادقة المستخدم: ينشئ تطبيق العميل رابط مصادقة ويرسل طلباً إلى خادم التفويض، الذي يقوم بإعادة توجيه المستخدم إلى صفحة تسجيل الدخول الخاصة به. يتفاعل المستخدم مع صفحة تسجيل الدخول باستخدام مجموعة واسعة من طرق الدخول ويتم التحقق من هويته بواسطة خادم التفويض.
3. التعامل مع إرجاع تسجيل الدخول: عند المصادقة الناجحة، سيتم إعادة توجيه المستخدم إلى تطبيقك برمز authorization_code الممنوح. يحتوي هذا authorization_code على جميع الأذونات ذات الصلة المرتبطة بحالة المصادقة وبيانات التفويض المطلوبة.
4. تبادل الرموز: طلب لتبادل الرموز باستخدام authorization_code المستخرج من عنوان الإعادة أعلاه. في المقابل:
   • id_token: JWT موقعة رقمياً تحتوي على معلومات الهوية عن المستخدم المصدق.
   • access_token: access_token معتم غير شفاف يمكن استخدامه للوصول إلى نهاية معلومات المستخدم الأساسية.
   • refresh_token: رمز اعتماد يسمح للمستخدم بإجراء تبادل مستمر للحصول على access_token

تدفق التفويض#

1. الوصول إلى معلومات المستخدم: للوصول إلى مزيد من معلومات المستخدم، يمكن للتطبيق إجراء طلبات إضافية إلى نقطة النهاية UserInfo، باستخدام access_token غير الشفاف الذي تم الحصول عليه من تدفق تبادل الرموز الأولي. وهذا يمكّن من استرداد تفاصيل إضافية عن المستخدم، مثل عنوان بريده الإلكتروني أو صورة ملفه الشخصي.
2. منح الوصول إلى المورد المحمي: إذا لزم الأمر، يمكن للتطبيق إجراء طلبات إضافية إلى نقطة النهاية الخاصة بتبادل الرموز، باستخدام refresh_token مجتمعة مع resource و scope للحصول على access_token مخصص للمستخدم للوصول إلى المورد المستهدف. ينتج عن هذه العملية إصدار access_token مُشكّل بتنسيق JWT يحتوي على جميع المعلومات اللازمة للتفويض للوصول إلى المورد المحمي.

التنفيذ#

سنتبع بعض استراتيجيات التصميم داخل SDK نمط الجافا سكريبت @logto/client لتوضيح عملية تنفيذ SDK بسيطة لتطبيق عميلك الخاص. يرجى ملاحظة أن بنية الكود التفصيلية قد تختلف تبعاً للإطار الزمني للعميل الذي تعمل معه. لا تتردد في اختيار أي من SDKs Logto الرسمية كمثال لمشروع SDK الخاص بك.

معاينة#

المُنشئ#

يجب أن يأخذ المُنشئ logtoConfig كمدخل. هذا يوفر جميع التكوينات الضرورية التي ستحتاج إليها لإقامة اتصال مصادق من خلاله هذا SDK.

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

تهيئة مصادقة المستخدم#

قبل إنشاء رابط طلب المصادقة، من الضروري إكمال عدة خطوات تجهيز لضمان عملية آمنة.

الحصول على تكوينات OIDC من خادم التفويض#

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

مولد PKCE#

تدفق تحقق PKCE(Proof Key for Code Exchange) ضروري لجميع تدفقات تبادل رمز العميل العام. وهو يخفف من خطر اعتراض رمز التفويض. لذلك، هناك حاجة إلى code_challenge و code_verifier لجميع طلبات تفويض التطبيق العامة (مثل التطبيق الأصلي و SPA).

طرق التنفيذ قد تختلف اعتمادًا على اللغات والأطر التي تستخدمها. يرجى الرجوع إلى code_challenge و code_verifier للتعريفات المفصلة.

إنشاء معامل الحالة#

في تدفق التفويض، يعد معامل الحالة قيمة يتم توليدها عشوائيًا ويتم تضمينها في طلب التفويض الذي يرسله العميل. ويعمل كإجراء أمني لمنع هجمات تزوير الطلبات بين المواقع (CSRF).

تخزين معلومات الجلسة الوسيطة#

هناك عدة عوامل تحتاج إلى الاحتفاظ بها في التخزين لأغراض التحقق بعد أن يحصل المستخدم على المصادقة ويعاد توجيهه إلى الجانب العميل. نحن بصدد تنفيذ طريقة لتعيين هذه العوامل الوسيطة إلى التخزين.

تسجيل الدخول#

دعونا نلخص كل ما تم تنفيذه أعلاه، حدد طريقة توليد عنوان URL لدخول المستخدم وإعادة توجيه المستخدم إلى خادم التفويض للحصول على المصادقة.

التعامل مع إرجاع تسجيل الدخول#

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

استخراج والتحقق من صحة عنوان URL للإرجاع#

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

ثم التحقق من معلمات عنوان URL للإرجاع قبل إرسال طلب تبادل الرمز.

• استخدام redirectUri المحفوظة مسبقًا للتحقق مما إذا كانت callbackUri هي نفسها التي أرسلناها إلى خادم التفويض.
• استخدام state المحفوظة مسبقًا للتحقق مما إذا كانت الدولة المعادة هي نفسها التي أرسلناها إلى خادم التفويض.
• تحقق مما إذا كان هناك خطأ يتم إعادته بواسطة خادم التفويض
• تحقق من وجود authorization_code المرتجع

إرسال طلب تبادل الرمز#

كخطوة نهائية لتدفق مصادقة المستخدم، سنستخدم authorization_code المرتجع لإرسال طلب تبادل الرمز والحصول على الرموز اللازمة للتفويض. لمزيد من التفاصيل حول تعريفات معلمات الطلب، يرجى الرجوع إلى مواصفات تبادل الرمز.

• code: authorization_code الذي تلقيناه من callbackUri
• clientId: معرف التطبيق
• redirectUri: نفس القيمة المستخدمة عند إنشاء عنوان URL لتسجيل الدخول للمستخدم.
• codeVerifier: محقق كود PKCE. مثل redirectUri، سيقارن خادم التفويض هذه القيمة بما سبق أن أرسلناه، مما يضمن صحة طلب تبادل الرمز القادم.

التعامل مع إرجاع تسجيل الدخول#

لنلخص كل ما لدينا. دعونا نبني طريقة التعامل مع إرجاع تسجيل الدخول (signInCallback):

وبذلك، ستعيد طلب تبادل الرمز الرموز التالية:

• id_token: idToken OIDC، JSON Web Token (JWT) تحتوي على معلومات الهوية حول المستخدم المصدق. id_token يمكن أن تستخدم أيضًا كمصدر الحقائق الوحيد لحالة مصادقة المستخدم.
• access_token: رمز التفويض الافتراضي الذي يعيده خادم التفويض. يمكن استخدامه لاستدعاء نقطة النهاية معلومات المستخدم وإسترجاع معلومات المستخدم المصدق.
• refresh_token: (إذا كان نطاق offline_access موجود في طلب التفويض): يتيح هذا الرمز ال refresh للتطبيق العميل الحصول على رمز وصول جديد دون الحاجة إلى إعادة مصادقة المستخدم، مما يمنح الوصول طويل الأجل إلى الموارد.
• expires_in: مدة الوقت، بالثواني، التي يكون فيها رمز الوصول صالحًا قبل انتهاء صلاحيته.

تحقق من رمز المعرف (ID token)#

يعد التحقق واستخراج المطالبات من id_token خطوة حاسمة في عملية المصادقة لضمان أصالة وشمولية الرمز. فيما يلي الخطوات الرئيسية المشاركة في التحقق من idToken.

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

يتم إرجاع id_token كـ JSON Web Token (JWT) قياسي. بناءً على الإطار الذي تستخدمه، يمكن أن تجد مجموعة متنوعة من المكونات الإضافية تحقق من صحة JWT لتساعد في فك تشفير والتحقق من الرمز. في هذا المثال، سنستخدم jose في SDK الجافا سكريبت الخاص بنا لتسهيل التحقق من الرمز وفك تشفيره.

الحصول على معلومات المستخدم#

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

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

الحصول على access token لتفويض المورد المحمي#

في معظم الحالات، لا يحتاج تطبيق العميل إلى مصادقة المستخدم فحسب، بل يحتاج أيضًا إلى تفويض الوصول إلى موارد معينة محمية أو نقاط نهاية API. هنا، سنستخدم refresh_token الذي تم الحصول عليه أثناء تسجيل الدخول للحصول على access_token(s) المحدد الممنوح لإدارة موارد معينة. يُتيح لنا ذلك الحصول على الوصول إلى تلك APIs المحمية.

الخلاصة#

لقد قدمنا عمليات تنفيذ الأساليب الأساسية لمصادقة وتفويض المستخدم لتطبيق جانب العميل. بناءً على السيناريو المحدد لديك، يمكنك تنظيم وتحسين منطق SDK وفقًا لذلك. يرجى ملاحظة أنه قد توجد اختلافات بسبب المنصات والأطر المختلفة.

لمزيد من التفاصيل، استعرض حزم SDK المقدمة من Logto. نشجع المزيد من المستخدمين على الانضمام إلى التطوير والمشاركة في المناقشات معنا. يتم تقييم ملاحظاتك ومساهماتك بشدة بينما نستمر في تحسين وتوسيع قدرات SDK.

المُلحق#

النطاقات المحجوزة#

نطاقات Logto المحجوزة التي ستحتاج إلى تمريرها أثناء طلب التوثيق الأولي. هذه النطاقات إما محجوزة لـ OIDC أو محجوزة لـ Logto كقواعد أساسية لإكمال تدفق التفويض بنجاح.

اسم النطاق	الوصف
openid	مطلوب لمنح id_token بعد مصادقة ناجحة.
offline-access	مطلوب لمنح refresh_token الذي يسمح لتطبيق العميل الخاص بك بتبادل وتجديد access_token بدون ظهور.
profile	مطلوب للوصول إلى المعلومات الأساسية للمستخدم

إعداد Logto#

اسم الخاصية	النوع	مطلوب	الوصف	القيمة الافتراضية
appId	string	true	معرف التطبيق الفريد. تم إنشاؤه من قبل خادم التفويض لتحديد تطبيق العميل.
appSecret	string		سر التطبيق مستخدم، إلى جانب معرف التطبيق، للتحقق من هوية الطالب. إنه مطلوب للعملاء السريين مثل تطبيقات الويب Go أو Next.js، واختياري للعملاء العموميين مثل التطبيقات الأصلية أو التطبيقات ذات الصفحة الواحدة (SPAs)
endpoint	string	true	نقطة النهاية الجذرية لخادم التفويض الخاص بك. سيتم استخدام هذه الخاصية على نطاق واسع لإنشاء طلبات التفويض.endpoint.
scopes	string list		يشير إلى جميع نطاقات الموارد الضرورية التي قد يحتاجها المستخدم ليكون معطى للوصول إلى أي موارد محمية معينة.	[reservedScopes]
resources	string list		جميع مؤشرات الموارد المحمية التي قد يطلب المستخدم الوصول إليها

طرق المساعدة#

generateRandomString#