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

تتيح مكتبة 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. في وضع النافذة المنبثقة، يمكنك تحديد معالج callback لـ JavaScript الذي يُرسِل رمز التفويض إلى خادمك. يمكن استخدام وضع النافذة المنبثقة لتوفير تجربة مستخدم سلسة بدون أن يحتاج الزوّار إلى مغادرة موقعك الإلكتروني.

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

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

  • مسار تجربة المستخدم في النافذة المنبثقة، اضبط ux_mode على popup، وقيمة callback على اسم الدالة التي ستستخدمها لإرسال رموز التفويض إلى منصتك.

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

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

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

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

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

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: "https://your.domain/code_callback_endpoint",
  state: "YOUR_BINDING_VALUE"
});

يمكنك بدء عملية إعداد عميل يتلقّى متصفح المستخدم رمز مصادقة من Google ويرسله إلى خادمك.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', code_receiver_uri, 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 الذي يعمل في browser المستخدِم رمز التفويض إلى نقطة نهاية تستضيفها منصّتك.

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

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

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

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

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

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

مثال على طلب 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

يمكنك اختياريًا استخدام ميزة "إدارة الخدمات المتكاملة للمسؤولين عن تكنولوجيا المعلومات" لحماية حسابات المستخدمين من خلال ميزة "حماية حسابات متعددة".

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