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

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

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

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

ملاحظة مهمة: على خادم الخلفية، يمكنك تبديل رمز التفويض بـ رموز إعادة التحميل ورموز الدخول من خلال استدعاء نقطة نهاية الرمز المميز في Google.

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

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

إعداد عميل رمز

تُعدّ طريقة 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). بالنسبة إلى وضع إعادة التوجيه، استخدِم مَعلمة state في OAuth 2.0. لمزيد من المعلومات حول إنشاء مَعلمة state والتحقق من صحتها، اطّلِع على القسم RFC6749 section 10.12 تزوير الطلبات من مواقع إلكترونية أخرى. في وضع النافذة المنبثقة، يمكنك إضافة عنوان HTTP مخصّص إلى طلباتك، ثم التأكد على خادمك من أنّه يتطابق مع القيمة والمصدر المتوقّعَين.

اختَر وضع تجربة مستخدم لعرض مقتطف رمز يعرض رمز التفويض ومعالجة هجمات تزوير الطلبات من مواقع إلكترونية أخرى:

وضع إعادة التوجيه

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

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'
});

ملاحظة مهمة: تتلقّى نقطة نهاية على خادم الخلفية رمز التفويض وتتحقق من صحته ، وتبدّله بـ رموز الدخول وإعادة التحميل.

وضع النافذة المنبثقة

يمكنك إعداد عميل يبدأ المستخدم من خلاله مسار التفويض في مربّع حوار منبثق. بعد الحصول على الموافقة، تعرض Google رمز التفويض في متصفّح المستخدم باستخدام دالة معاودة الاتصال. يرسل طلب POST من معالج معاودة الاتصال في JavaScript رمز التفويض إلى نقطة نهاية على خادم الخلفية، حيث تتحقق أولاً من صحته ثم تُكمل باقي مسار OAuth.

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 هذه:

الاسم	القيمة
authuser	طلب مصادقة تسجيل دخول المستخدم
code	رمز تفويض OAuth2 تنشئه Google
hd	النطاق المستضاف لحساب المستخدم
prompt	مربّع إفادة موافقة المستخدم
scope	قائمة مفصولة بمسافات تضم نطاقًا واحدًا أو أكثر من نطاقات OAuth2 التي سيتم تفويضها
state	متغيّر حالة تزوير الطلبات من مواقع إلكترونية أخرى

وفقًا لـ 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

ملاحظة مهمة: في السابق، كان يتم استخدام POST للطلبات. عدِّل المعالج لقبول طلبات GET وPOST أو فكِّر في استضافة نقطتَي نهاية مختلفتَين إذا كنت تخطط لمواصلة استخدام مكتبات JS القديمة أو استدعاء نقاط نهاية Google OAuth 2.0 مباشرةً أثناء استخدام مكتبة Google Identity Services.

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

على خادمك، اتّبِع الخطوات التالية للمساعدة في تجنُّب هجمات تزوير الطلبات من مواقع إلكترونية أخرى.

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

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

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

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

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

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

ملاحظة: عند استخدام وضع النافذة المنبثقة، تكون قيمة redirect_uri التي تستخدمها في الخطوة 5 و الخطوات اللاحقة هي مصدر الصفحة التي تستدعي `initCodeClient`. على سبيل المثال، https://www.example.com/index.html يستدعي initCodeClient والمصدر: https://www.example.com هو قيمة redirect_url.

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

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

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

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