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

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

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

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

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

ضبط إعدادات الجهاز

ابحث عن معرِّف عميل أو أنشئ معرِّفًا من خلال اتّباع الخطوات الموضّحة في دليل الحصول على معرِّف عميل واجهة برمجة التطبيقات من Google. بعد ذلك، أضِف مكتبة العميل إلى الصفحات على موقعك الإلكتروني التي ستستدعي Google APIs. أخيرًا، عليك إعداد العميل للرمز المميّز. يتم ذلك عادةً في معالج 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 يحتوي على رمز دخول وقائمة بحدود التفويض التي منحها المستخدم للوصول إلى التطبيق، أو خطأ، إلى معالِج طلب إعادة الاتصال.

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

كيفية التعامل مع الموافقة

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

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

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

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

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

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

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

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

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

Ajax

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

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

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

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

  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
          

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

  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 في عناصر إعدادات "عميل الرموز المميّزة".

العمل مع الرموز

في نموذج الرمز المميّز، لا يخزِّن نظام التشغيل أو المتصفّح رمز الوصول، وبدلاً من ذلك، يتم أولاً الحصول على رمز مميّز جديد في وقت تحميل الصفحة، أو لاحقًا من خلال بدء 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

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