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

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

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

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

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

الإعداد

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

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

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

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 وظيفة معاودة الاتصال لعرض رمز الدخول ورمز النطاقات التي وافق عليها المستخدم. بعد ذلك، يتعامل تطبيقك بأمان مع النتائج المختلفة المختلفة التي يمكن الحصول عليها باستخدام أذونات دقيقة.

التفويض المتزايد

بالنسبة إلى تطبيقات الويب، يوضّح السيناريوان الرئيسيان التاليان التفويض المتزايد باستخدام:

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

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

أياكس

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

تطبيق 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 APIs

يعمل عميل الرمز المميّز مع مكتبة برامج 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);
  });