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

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

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

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

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

تؤدي الطريقة google.accounts.oauth2.initCodeClient() إلى إعداد برنامج ترميز.

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

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

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

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

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

منع هجمات CSRF

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

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

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

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

بالنسبة إلى وضع "إعادة التوجيه"، يتم إرسال طلب GET إلى نقطة النهاية المحدّدة من خلال redirect_url، مع مشاركة رمز التفويض في المَعلمة 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: رمز تفويض Exchange لرموز إعادة التحميل والوصول الخاصة بدليل استخدام OAuth 2.0 لتطبيقات خادم الويب.

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

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

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

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