استخدام نموذج رمز

تتيح مكتبة Google Identity Services للمستخدمين طلب رمز تفويض من Google باستخدام إطار منبثق مستند إلى المتصفّح أو مسار تجربة المستخدم لإعادة التوجيه. يبدأ ذلك مسار OAuth 2.0 آمنًا ويؤدي إلى الحصول على رمز مميز للوصول يُستخدَم لاستدعاء Google APIs بالنيابة عن المستخدم.

ملخّص لمسار رمز التفويض في OAuth 2.0:

• من خلال متصفّح، وباستخدام إيماءة مثل النقر على زر، يطلب صاحب حساب Google رمز تفويض من Google.
• تستجيب Google بإرسال رمز تفويض فريد إما إلى دالة رد الاتصال في تطبيق الويب المستند إلى JavaScript الذي يتم تشغيله في متصفّح المستخدم، أو تستدعي مباشرةً نقطة نهاية رمز التفويض باستخدام عملية إعادة توجيه في المتصفّح.
• تستضيف منصة الخلفية نقطة نهاية لرمز التفويض وتتلقّى الرمز. بعد التحقّق من صحة الرمز، تستبدل منصتك هذا الرمز لكل مستخدم برموز الدخول ورموز التحديث من خلال إرسال طلب إلى نقطة نهاية الرمز المميز في Google.
• تتحقّق Google من صحة رمز التفويض، وتؤكّد أنّ الطلب صادر من منصتك الآمنة، وتصدر رموز الدخول ورموز إعادة التحميل، وتعرض الرموز من خلال طلب نقطة نهاية تسجيل الدخول المستضافة على منصتك.
• تتلقّى نقطة نهاية تسجيل الدخول رموز الدخول وإعادة التحميل، وتخزِّن رمز إعادة التحميل بشكل آمن لاستخدامه لاحقًا.

المتطلبات الأساسية

اتّبِع الخطوات الموضّحة في الإعداد لضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth والحصول على معرّف عميل وتحميل مكتبة العميل.

إعداد برنامج Code Client

تُهيئ الطريقة google.accounts.oauth2.initCodeClient() برنامجًا للتعامل مع الرموز.

وضع النافذة المنبثقة أو إعادة التوجيه

يمكنك اختيار مشاركة رمز مصادقة باستخدام مسار المستخدم في وضع إعادة التوجيه أو النافذة المنبثقة. في "وضع إعادة التوجيه"، تستضيف نقطة نهاية مصادقة OAuth2 على خادمك، وتعيد Google توجيه وكيل المستخدم إلى نقطة النهاية هذه، وتشارك رمز المصادقة كمَعلمة عنوان URL. بالنسبة إلى وضع النافذة المنبثقة، عليك تحديد معالج معاودة الاتصال JavaScript، الذي يرسل رمز التفويض إلى خادمك. يمكنك استخدام "وضع النوافذ المنبثقة" لتوفير تجربة مستخدم سلسة بدون أن يضطر الزوّار إلى مغادرة موقعك الإلكتروني.

لإعداد عميل من أجل:

• عدِّل مسار تجربة المستخدم لإعادة التوجيه، واضبط ux_mode على redirect، واضبط قيمة redirect_uri على نقطة نهاية رمز التفويض في منصتك. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المعتمدة لإعادة التوجيه الخاصة بعميل OAuth 2.0 الذي أعددته في Google Cloud Console. يجب أيضًا أن يتوافق مع قواعد التحقّق من معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه.

• بالنسبة إلى مسار تجربة المستخدم في النوافذ المنبثقة، اضبط قيمة ux_mode على popup، وقيمة callback على اسم الدالة التي ستستخدمها لإرسال رموز التفويض إلى منصتك. تكون القيمة التلقائية لـ redirect_uri هي مصدر الصفحة التي تستدعي initCodeClient. يستخدم المسار هذه القيمة لاحقًا عند استبدال رمز المصادقة برمز مميز للوصول أو رمز مميز لإعادة التحميل. على سبيل المثال، https://www.example.com/index.html هي عدد المكالمات initCodeClient والمصدر: https://www.example.com هو قيمة redirect_url.

الحماية من هجمات CSRF

تستخدم مسارات تجربة المستخدم في وضعَي "إعادة التوجيه" و"النوافذ المنبثقة" تقنيات مختلفة بعض الشيء للمساعدة في منع هجمات تزوير الطلبات عبر المواقع الإلكترونية (CSRF). بالنسبة إلى وضع Redirect، استخدِم مَعلمة الحالة في بروتوكول OAuth 2.0. يمكنك الاطّلاع على القسم 10.12 من RFC6749 Cross-Site Request Forgery لمزيد من المعلومات حول إنشاء المَعلمة state والتحقّق من صحتها. باستخدام "وضع النافذة المنبثقة"، يمكنك إضافة عنوان HTTP مخصّص إلى طلباتك، ثم التأكّد على خادمك من أنّه يتطابق مع القيمة والمصدر المتوقّعَين.

اختَر وضع تجربة المستخدم لعرض مقتطف رمز يعرض رمز المصادقة ومعالجة طلبات CSRF:

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: 'https://oauth2.example.com/code',
  state: 'YOUR_BINDING_VALUE'
});

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', "https://oauth2.example.com/code", true);
    xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    // Set custom header for CRSF
    xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
    xhr.onload = function() {
      console.log('Auth code response: ' + xhr.responseText);
    };
    xhr.send('code=' + response.code);
  },
});

بدء مسار رمز المصادقة في OAuth 2.0

استدعِ طريقة requestCode() لبرنامج العميل لتفعيل مسار المستخدم:

<button onclick="client.requestCode();">Authorize with Google</button>

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

معالجة رمز المصادقة

تنشئ Google رمز تفويض فريدًا لكل مستخدم، وتتلقّاه وتتحقّق منه على خادم الخلفية.

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

في "وضع إعادة التوجيه"، ترسل Google طلب GET إلى نقطة النهاية المحدّدة من خلال redirect_uri، وتشارك رمز التفويض في المَعلمة code الخاصة بعنوان URL. للحصول على رمز التفويض، اتّبِع الخطوات التالية:

• أنشئ نقطة نهاية تفويض جديدة إذا لم يكن لديك تنفيذ حالي، أو

• عدِّل نقطة النهاية الحالية لقبول طلبات GET ومَعلمات عناوين URL. في السابق، كانت Google ترسل طلب PUT مع قيمة رمز التفويض في الحمولة.

نقطة نهاية التفويض

يجب أن تتعامل نقطة نهاية رمز التفويض مع طلبات GET التي تتضمّن مَعلمات سلسلة طلب البحث في عنوان URL التالية:

وفقًا للمعيار RFC 6749، على العملاء تجاهل مَعلمات الردّ غير المعروفة، بغض النظر عمّا إذا كانت مدرَجة في الجدول السابق.

مثال على طلب GET مع مَعلمات عنوان URL لنقطة نهاية باسم auth-code ومستضافة على example.com:

Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent

عند بدء عملية تدفق رمز التفويض باستخدام مكتبات JavaScript القديمة أو من خلال إجراء طلبات مباشرة إلى نقاط نهاية Google OAuth 2.0، ترسل Google طلب POST.

مثال على طلب POST يحتوي على رمز التفويض كحمولة في نص طلب HTTP:

Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw

التحقّق من صحة الطلب

على الخادم، اتّبِع الخطوات التالية للمساعدة في تجنُّب هجمات CSRF.

تحقَّق من قيمة المَعلمة state في وضع إعادة التوجيه.

تأكَّد من توفّر العنوان X-Requested-With: XmlHttpRequest لوضع النافذة المنبثقة.

بعد ذلك، يجب المتابعة للحصول على رموز مميزة لإعادة التحميل ورموز دخول من Google فقط إذا تم أولاً إثبات صحة طلب رمز المصادقة بنجاح.

الحصول على رموز الدخول وإعادة التحميل

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

اتّبِع التعليمات بدءًا من الخطوة 5: استبدال رمز التفويض برموز مميزة لإعادة التحميل والوصول في دليل استخدام OAuth 2.0 لتطبيقات خادم الويب.

إدارة الرموز المميزة

تخزّن منصتك رموز إعادة التحميل بأمان. احذف رموز الدخول المميزة المخزّنة عند إزالة حسابات المستخدمين أو عندما يلغي المستخدم موافقته من خلال google.accounts.oauth2.revoke أو مباشرةً من https://myaccount.google.com/permissions.

يمكنك أيضًا استخدام RISC لحماية حسابات المستخدمين من خلال ميزة "الحماية من خلال حسابات متعددة".

عادةً، تستدعي منصة الخلفية واجهات Google APIs باستخدام رمز مميّز للوصول. إذا كان تطبيقك على الويب سيطلب أيضًا بيانات من واجهات برمجة تطبيقات Google مباشرةً من متصفّح المستخدم، عليك توفير طريقة لمشاركة رمز الدخول مع تطبيقك على الويب، ولكنّ هذه العملية خارج نطاق هذا الدليل. عند اتّباع هذا النهج واستخدام مكتبة برامج Google API للغة JavaScript، استخدِم gapi.client.SetToken() لتخزين رمز الدخول مؤقتًا في ذاكرة المتصفّح، وفعِّل المكتبة لتتمكّن من طلب بيانات من واجهات Google API.