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

تتيح مكتبة 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 على نقطة نهاية رمز التفويض على النظام الأساسي. يجب أن تتطابق القيمة تمامًا مع أحد معرِّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه لعميل 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.