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

تتيح مكتبة 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، والذي يتم تشغيله في متصفّح المستخدم، توجيه رمز التفويض إلى نقطة نهاية تستضيفها منصّتك.

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

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

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

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

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

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