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

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

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

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

إعداد برنامج رمز برمجي

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

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

لإعداد برنامج لما يلي:

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

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

منع هجمات CSRF

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

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

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

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

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

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

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

الاسم القيمة
جهة المصادقة طلب مصادقة تسجيل دخول المستخدم
رمز رمز تفويض 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: 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.