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

تساعدك مكتبة JavaScript google.accounts.oauth2 في طلب موافقة المستخدم والحصول على رمز مميّز للوصول إلى بيانات المستخدم. تستند هذه الطريقة إلى مسار منح الإذن الضمني في OAuth 2.0، وهي مصمَّمة للسماح لك إما بطلب بيانات من Google APIs مباشرةً باستخدام REST وCORS، أو باستخدام مكتبة برامج Google APIs للغة JavaScript (المعروفة أيضًا باسم gapi.client) للوصول بسهولة ومرونة إلى واجهات برمجة التطبيقات الأكثر تعقيدًا.

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

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

ننصحك باتّباع الأسلوب الموضّح هنا بدلاً من التقنيات التي يغطيها الدليل القديم OAuth 2.0 لتطبيقات الويب من جهة العميل.

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

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

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

اتّصِل بـ initTokenClient() لتهيئة عميل رمز مميّز جديد باستخدام معرّف العميل الخاص بتطبيق الويب، ويجب تضمين قائمة بنطاق واحد أو أكثر scopes يحتاج المستخدم إلى الوصول إليه:

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (response) => {
    ...
  },
});

بدء مسار رمز OAuth 2.0 المميز

استخدِم طريقة requestAccessToken() لتفعيل سير عمل تجربة المستخدم الخاصة بالرمز المميز والحصول على رمز مميز للوصول. تطلب Google من المستخدم ما يلي:

  • اختَر حساب الطفل،
  • تسجيل الدخول إلى حساب Google إذا لم يسبق لك ذلك
  • منح الموافقة لتطبيق الويب الخاص بك على الوصول إلى كل نطاق مطلوب

يؤدي إجراء من المستخدم إلى بدء عملية الحصول على الرمز المميّز: <button onclick="client.requestAccessToken();">Authorize me</button>

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

يمكن للمستخدمين إغلاق نافذة اختيار الحساب أو نافذة تسجيل الدخول، وفي هذه الحالة، لن يتم استدعاء دالة معاودة الاتصال.

يجب تنفيذ تصميم تطبيقك وتجربة المستخدم فيه بعد مراجعة سياسات OAuth 2.0 من Google بدقة. وتشمل هذه السياسات العمل مع نطاقات متعدّدة، وتحديد وقت وكيفية التعامل مع موافقة المستخدم، وغير ذلك.

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

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

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

لمزيد من المعلومات التفصيلية، يُرجى الاطّلاع على كيفية التعامل مع الأذونات الدقيقة.

تفويض تدريجي

بالنسبة إلى تطبيقات الويب، يوضّح السيناريوهان التاليان على المستوى العالي عملية منح الأذونات بشكل تدريجي باستخدام:

  • تطبيق Ajax من صفحة واحدة، وغالبًا ما يستخدم XMLHttpRequest مع إمكانية الوصول الديناميكي إلى الموارد.
  • صفحات ويب متعددة، ويتم فصل الموارد وإدارتها على أساس كل صفحة.

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

Ajax

أضِف إمكانية منح الأذونات بشكل تدريجي إلى تطبيقك من خلال إجراء طلبات متعددة إلى requestAccessToken() واستخدام المَعلمة scope الخاصة بالكائن OverridableTokenClientConfig لطلب نطاقات فردية عند الحاجة إليها وفقط عند الضرورة. في هذا المثال، سيتم طلب الموارد وعرضها فقط بعد أن يوسّع المستخدم قسم المحتوى المصغّر.

تطبيق Ajax
إعداد عميل الرمز المميّز عند تحميل الصفحة: 
        const client = google.accounts.oauth2.initTokenClient({
          client_id: 'YOUR_GOOGLE_CLIENT_ID',
          callback: "onTokenResponse",
        });
طلب الموافقة والحصول على رموز الدخول من خلال إيماءات المستخدم، انقر على علامة `+` لفتح:

مستندات للقراءة

عرض المستندات الحديثة

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/documents.readonly'
             })
           );

الأحداث القادمة

عرض معلومات التقويم

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/calendar.readonly'
             })
           );

عرض الصور

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
             })
           );

يؤدي كل طلب إلى requestAccessToken إلى ظهور لحظة طلب موافقة المستخدم، ولن يتمكّن تطبيقك من الوصول إلا إلى الموارد التي يتطلّبها القسم الذي يختار المستخدم توسيعه، ما يحدّ من مشاركة الموارد من خلال اختيار المستخدم.

صفحات ويب متعدّدة

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

تطبيق من صفحات متعدّدة
صفحة ويب الرمز
الصفحة 1 مستندات للقراءة 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
الصفحة 2. الفعاليات القادمة 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/calendar.readonly',
  });
  client.requestAccessToken();
الصفحة 3. مجموعة صور 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/photoslibrary.readonly',
  });
  client.requestAccessToken();

تطلب كل صفحة النطاق اللازم وتحصل على رمز مميّز للوصول من خلال استدعاء initTokenClient() وrequestAccessToken() عند وقت التحميل. في هذا السيناريو، يتم استخدام صفحات ويب فردية لفصل وظائف المستخدمين والموارد حسب النطاق بوضوح. في سيناريو واقعي، قد تطلب الصفحات الفردية نطاقات متعددة ذات صلة.

الأذونات الدقيقة

يتم التعامل مع الأذونات الدقيقة بالطريقة نفسها في جميع السيناريوهات، فبعد أن تستدعي requestAccessToken() دالة معاودة الاتصال ويتم عرض رمز دخول، تأكَّد من أنّ المستخدم وافق على النطاقات المطلوبة باستخدام hasGrantedAllScopes() أو hasGrantedAnyScope(). على سبيل المثال:

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly \
          https://www.googleapis.com/auth/documents.readonly \
          https://www.googleapis.com/auth/photoslibrary.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      if (google.accounts.oauth2.hasGrantedAnyScope(tokenResponse,
          'https://www.googleapis.com/auth/photoslibrary.readonly')) {
        // Look at pictures
        ...
      }
      if (google.accounts.oauth2.hasGrantedAllScopes(tokenResponse,
          'https://www.googleapis.com/auth/calendar.readonly',
          'https://www.googleapis.com/auth/documents.readonly')) {
        // Meeting planning and review documents
        ...
      }
    }
  },
});

سيتم أيضًا تضمين أي أذونات تم قبولها سابقًا من جلسات أو طلبات سابقة في الرد. يتم الاحتفاظ بسجلّ لموافقة المستخدم لكل مستخدم ولكل رقم تعريف عميل، ويظلّ هذا السجلّ متاحًا على مستوى طلبات متعدّدة إلى initTokenClient() أو requestAccessToken(). بشكلٍ تلقائي، لا تكون موافقة المستخدم ضرورية إلا في المرة الأولى التي يزور فيها موقعك الإلكتروني ويطلب نطاقًا جديدًا، ولكن يمكن طلبها عند كل عملية تحميل للصفحة باستخدام prompt=consent في عناصر إعدادات Token Client.

العمل باستخدام الرموز المميزة

في نموذج الرمز المميّز، لا يتم تخزين رمز مميّز للوصول بواسطة نظام التشغيل أو المتصفّح، بل يتم الحصول على رمز مميّز جديد أولاً عند تحميل الصفحة، أو لاحقًا من خلال إرسال طلب إلى requestAccessToken() عبر إجراء من المستخدم، مثل الضغط على زر.

استخدام REST وCORS مع Google APIs

يمكن استخدام رمز الدخول لإرسال طلبات مصادَق عليها إلى Google APIs باستخدام REST وCORS. يتيح ذلك للمستخدمين تسجيل الدخول ومنح الموافقة، كما يتيح لـ Google إصدار رمز مميّز للوصول إلى البيانات، ويتيح لموقعك الإلكتروني العمل مع بيانات المستخدم.

في هذا المثال، يمكنك عرض أحداث التقويم القادمة للمستخدمين الذين سجّلوا الدخول باستخدام رمز الدخول الذي تعرضه tokenRequest():

var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://www.googleapis.com/calendar/v3/calendars/primary/events');
xhr.setRequestHeader('Authorization', 'Bearer ' + tokenResponse.access_token);
xhr.send();

لمزيد من المعلومات، اطّلِع على كيفية استخدام CORS للوصول إلى Google APIs.

يتناول القسم التالي كيفية الدمج بسهولة مع واجهات برمجة التطبيقات الأكثر تعقيدًا.

العمل باستخدام مكتبة JavaScript الخاصة بواجهات Google API

يعمل عميل الرمز المميز مع مكتبة برامج Google API للغة JavaScript. اطّلِع على مقتطف الرمز البرمجي أدناه.

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      gapi.client.setApiKey('YOUR_API_KEY');
      gapi.client.load('calendar', 'v3', listUpcomingEvents);
    }
  },
});

function listUpcomingEvents() {
  gapi.client.calendar.events.list(...);
}

انتهاء صلاحية الرمز المميز

تم تصميم رموز الدخول ليكون لها مدة صلاحية قصيرة. إذا انتهت صلاحية رمز الدخول قبل نهاية جلسة المستخدم، احصل على رمز جديد من خلال استدعاء requestAccessToken() من حدث ناتج عن إجراء من المستخدم، مثل الضغط على زر.

استدعِ طريقة google.accounts.oauth2.revoke لإزالة موافقة المستخدم وإمكانية الوصول إلى الموارد لجميع النطاقات التي تم منحها لتطبيقك. يجب توفّر رمز دخول صالح لإبطال هذا الإذن:

google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
    console.log(done);
    console.log(done.successful);
    console.log(done.error);
    console.log(done.error_description);
  });