استخدام OAuth 2.0 لتطبيقات الويب JavaScript

نقاط نهاية OAuth 2.0

أنشئ عنوان URL لطلب الوصول من نقطة نهاية OAuth 2.0 في Google على الرابط https://accounts.google.com/o/oauth2/v2/auth. يمكن الوصول إلى نقطة النهاية هذه من خلال بروتوكول HTTPS، ويتم رفض اتصالات HTTP العادية.

يتيح خادم التفويض في Google مَعلمات سلسلة الطلب التالية لتطبيقات خادم الويب:

نموذج إعادة توجيه إلى خادم التفويض في Google

يطلب نموذج عنوان URL أدناه الوصول بلا إنترنت (access_type=offline) إلى نطاق يسمح بالوصول لعرض حساب المستخدم على YouTube. ويستخدم هذا الإجراء تفويضًا متزايدًا لضمان أن يشمل رمز الوصول الجديد أي نطاقات منحها المستخدم سابقًا للتطبيق. يحدّد عنوان URL أيضًا قيمًا للمَعلمات المطلوبة redirect_uri وresponse_type و client_id بالإضافة إلى المَعلمة state. يحتوي عنوان URL على فواصل أسطر ومسافات لتسهيل القراءة.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

بعد إنشاء عنوان URL للطلب، أعِد توجيه المستخدم إليه.

رمز JavaScript النموذجي

يوضِّح المقتطف التالي من JavaScript كيفية بدء عملية التفويض في JavaScript بدون استخدام مكتبة Google APIs Client Library لـ JavaScript. بما أنّ نقطة نهاية OAuth 2.0 هذه لا تتيح مشاركة الموارد المتعدّدة المصادر (CORS)، ينشئ المقتطف نموذجًا يفتح الطلب إلى نقطة النهاية هذه.

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/youtube.force-ssl',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

نقاط نهاية OAuth 2.0

يُرسِل خادم OAuth 2.0 استجابة إلى redirect_uri المحدّد في طلب رمز الوصول.

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

• استجابة رمز الدخول:

  https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600

  بالإضافة إلى المَعلمة access_token، تحتوي سلسلة المقتطف أيضًا على المَعلمة token_type التي يتم ضبطها دائمًا على Bearer، والمَعلمة expires_in التي تحدّد مدة صلاحية الرمز المميّز بالثواني. إذا تم تحديد المَعلمة state في طلب الرمز المميّز للوصول، يتم أيضًا تضمين قيمتها في الاستجابة.

• استجابة خطأ:

  https://oauth2.example.com/callback#error=access_denied

نموذج استجابة خادم OAuth 2.0

يمكنك اختبار هذه العملية من خلال النقر على نموذج عنوان URL التالي الذي يطلب فسحة وصول قراءة فقط لعرض البيانات الوصفية للملفات في Google Drive وفسحة وصول قراءة فقط لعرض أحداث "تقويم Google":

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

بعد إكمال مسار OAuth 2.0، ستتم إعادة توجيهك إلى http://localhost/oauth2callback. سيؤدي عنوان URL هذا إلى 404 NOT FOUND خطأ ما لم يعرض جهازك الملف على هذا العنوان. تقدّم الخطوة التالية مزيدًا من التفاصيل حول المعلومات التي يتم عرضها في عنوان URI عند إعادة توجيه المستخدم إلى تطبيقك.

نقاط نهاية OAuth 2.0

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

على سبيل المثال، يشير نموذج ردّ رمز الوصول التالي إلى أنّ المستخدم قد منح تطبيقك إذنًا بالاطّلاع على فيديوهات المستخدم على YouTube وتقييماته وتعليقاته وترجماته وتعديلها وحذفها نهائيًا:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

نقاط نهاية OAuth 2.0

بعد أن يحصل تطبيقك على رمز مميّز للوصول، يمكنك استخدام الرمز المميّز لإجراء طلبات إلى واجهة برمجة تطبيقات Google نيابةً عن حساب مستخدم معيّن إذا تم منح نطاق الوصول المطلوب من واجهة برمجة التطبيقات. لإجراء ذلك، أدرِج رمز access_token Bearer access_token ��Authorization يُفضّل استخدام عنوان HTTP كلما أمكن، لأنّ سلاسل طلبات البحث غالبًا ما تكون مرئية في سجلات الخادم. في معظم الحالات، يمكنك استخدام مكتبة عملاء لإعداد طلبات البيانات من واجهات برمجة تطبيقات Google (على سبيل المثال، عند طلب البيانات من YouTube Data API).

تجدر الإشارة إلى أنّ YouTube Data API لا تتيح استخدام حسابات الخدمة إلا لمالكي محتوى YouTube الذين يملكون قنوات متعدّدة على YouTube ويديرونها، مثل شركات الإنتاج وشركات التسجيل.

يمكنك تجربة جميع واجهات برمجة تطبيقات Google والاطّلاع على نطاقات الوصول إليها على مساحة بروتوكول OAuth 2.0.

أمثلة على طلبات HTTP GET

قد تبدو طلبًا موجّهًا إلى نقطة نهاية youtube.channels (YouTube Data API) باستخدام عنوان HTTPAuthorization: Bearer على النحو التالي. يُرجى العِلم أنّك بحاجة إلى تحديد رمز الدخول الخاص بك:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

في ما يلي طلب بيانات من واجهة برمجة التطبيقات نفسها للمستخدم الذي تمّت مصادقة بياناته باستخدام مَعلمة سلسلة طلب البحث access_token:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

أمثلة على curl

يمكنك اختبار هذه الأوامر باستخدام تطبيق سطر الأوامر curl. في ما يلي مثال يستخدم خيار عنوان HTTP (الخيار المفضّل):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

أو يمكنك بدلاً من ذلك استخدام خيار مَعلمة سلسلة الطلب:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

رمز JavaScript النموذجي

يوضّح مقتطف الرمز البرمجي أدناه كيفية استخدام مشاركة الموارد المتعددة المصادر (CORS) لإرسال طلب إلى Google API. لا يستخدم هذا المثال "مكتبة برامج Google APIs" لبرنامج JavaScript. ومع ذلك، حتى إذا لم تكن تستخدِم مكتبة العميل، من المرجّح أن يساعدك دليل إتاحة بروتوكول مشاركة الموارد المشتركة المنشأ (CORS) في مستندات هذه المكتبة على فهم هذه الطلبات بشكل أفضل.

في مقتطف التعليمات البرمجية هذا، يمثّل المتغيّر access_token الرمز المميّز الذي حصلت عليه لإجراء طلبات واجهة برمجة التطبيقات نيابةً عن المستخدم المفوَّض. يوضّح المثال الكامل كيفية تخزين هذا الرمز المميّز في مساحة التخزين التلقائية للمتصفّح واسترداده عند إجراء طلب بيانات من واجهة برمجة التطبيقات.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

نقاط نهاية OAuth 2.0

يوضّح نموذج الرمز البرمجي هذا كيفية إكمال عملية OAuth 2.0 في JavaScript بدون استخدام مكتبة Google APIs Client Library لـ JavaScript. هذا الرمز مخصّص لصفحة HTML تعرِض زرًا لمحاولة إرسال طلب إلى واجهة برمجة التطبيقات. في حال النقر على الزر، يتحقّق الرمز من ما إذا كانت الصفحة قد حفظت رمز علامة مميّزة للوصول إلى واجهة برمجة التطبيقات في مساحة التخزين المؤقتة للمتصفّح. وفي حال كان الأمر كذلك، يتم تنفيذ طلب البيانات من واجهة برمجة التطبيقات. وبخلاف ذلك، يبدأ مسار OAuth 2.0.

بالنسبة إلى مسار OAuth 2.0، تتّبع الصفحة الخطوات التالية:

1. ويوجّه المستخدم إلى خادم OAuth 2.0 من Google الذي يطلب الوصول إلى نطاق https://www.googleapis.com/auth/youtube.force-ssl.
2. بعد منح إذن الوصول (أو رفضه) إلى نطاق واحد أو أكثر من النطاقات المطلوبة، تتم إعادة توجيه المستخدم إلى الصفحة الأصلية التي تُحلِّل رمز الوصول من سلسلة معرّف المقتطف.
3. تتحقّق الصفحة من النطاقات التي منحها المستخدم للوصول إلى التطبيق.

4. إذا منح المستخدم إذن الوصول إلى النطاقات المطلوبة، تستخدم الصفحة رمز الدخول لتقديم طلب واجهة برمجة التطبيقات النموذجي.

   يطلب طلب واجهة برمجة التطبيقات هذا استخدام channels.list في YouTube Data API لاسترداد بيانات عن قناة المستخدم المفوَّض على YouTube.

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

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

لتشغيل هذا الرمز على الجهاز، عليك ضبط قيم للمتغيّرين YOUR_CLIENT_ID و YOUR_REDIRECT_URI تتوافق مع بيانات اعتماد التفويض. يجب ضبط المتغيّر YOUR_REDIRECT_URI على عنوان URL نفسه الذي يتم عرض الصفحة عليه. يجب أن تتطابق القيمة تمامًا مع أحد عناوين URL المعتمَدة لإعادة التوجيه لعميل OAuth 2.0، والذي أعددته في API Console Credentials page. إذا كانت هذه القيمة لا تتطابق مع عنوان URL مفوَّض، ستظهر لك رسالة خطأ redirect_uri_mismatch. يجب أيضًا أن يكون قد تم تفعيل واجهة برمجة التطبيقات المناسبة لهذا الطلب في مشروعك.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var fragmentString = location.hash.substring(1);
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0 && params['state']) {
    if (params['state'] == localStorage.getItem('state')) {
      localStorage.setItem('oauth2-test-params', JSON.stringify(params) );

      trySampleRequest();
    } else {
      console.log('State mismatch. Possible CSRF attack');
    }
  }

  // Function to generate a random state value
  function generateCryptoRandomState() {
    const randomValues = new Uint32Array(2);
    window.crypto.getRandomValues(randomValues);

    // Encode as UTF-8
    const utf8Encoder = new TextEncoder();
    const utf8Array = utf8Encoder.encode(
      String.fromCharCode.apply(null, randomValues)
    );

    // Base64 encode the UTF-8 data
    return btoa(String.fromCharCode.apply(null, utf8Array))
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=+$/, '');
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) { 
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
          'access_token=' + params['access_token']);
      xhr.onreadystatechange = function (e) {
        if (xhr.readyState === 4 && xhr.status === 200) {
          console.log(xhr.response);
        } else if (xhr.readyState === 4 && xhr.status === 401) {
          // Token invalid, so prompt for user permission.
          oauth2SignIn();
        }
      };
      xhr.send(null); 
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // create random state value and store in local storage
    var state = generateCryptoRandomState();
    localStorage.setItem('state', state);

    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/youtube.force-ssl',
                  'state': state,
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

نقاط نهاية OAuth 2.0

في هذا المثال، يطلب التطبيق المُرسِل إذن الوصول لاسترداد data العميل في "إحصاءات YouTube" بالإضافة إلى أي إذن وصول آخر قد منحه العميل للتطبيق.

لإضافة نطاقات إلى رمز وصول حالي، أدرِج المَعلمة include_granted_scopes في طلبك المُرسَل إلى خادم OAuth 2.0 في Google.

يوضّح مقتطف الرمز البرمجي التالي كيفية إجراء ذلك. يفترض المقتطف أنّك قد حفظت النطاقات التي يكون فيها معرّف المرور صالحًا في مساحة التخزين المحلية للمتصفّح. (يخزِّن المثال الكامل قائمة بالنطاقات التي يكون فيها رمز المرور صالحًا من خلال ضبط السمة oauth2-test-params.scope في مساحة التخزين المحلية للمتصفّح).

تقارن المقتطف النطاقات التي يكون فيها رمز الوصول صالحًا بالنطاق الذي تريد استخدامه لطلب بحث معيّن. إذا لم يشمل رمز الوصول هذا النطاق، تبدأ عملية OAuth 2.0. هنا، تكون الدالة oauth2SignIn هي نفسها الدالة التي تم تقديمها في الخطوة 2 (والتي يتم تقديمها لاحقًا في مثال كامل).

var SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl';
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));

var current_scope_granted = false;
if (params.hasOwnProperty('scope')) {
  var scopes = params['scope'].split(' ');
  for (var s = 0; s < scopes.length; s++) {
    if (SCOPE == scopes[s]) {
      current_scope_granted = true;
    }
  }
}

if (!current_scope_granted) {
  oauth2SignIn(); // This function is defined elsewhere in this document.
} else {
  // Since you already have access, you can proceed with the API request.
}

نقاط نهاية OAuth 2.0

لإبطال رمز مميّز آليًا، يُرسِل تطبيقك طلبًا إلى https://oauth2.googleapis.com/revoke ويُدرِج الرمز المميّز كمَعلمة:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

يمكن أن يكون الرمز المميّز رمز دخول أو رمزًا مميزًا لإعادة التحميل. إذا كان الرمز المميّز هو رمز دخول وكان لديه رمز مميّز مقابل لإعادة التحميل، سيتم أيضًا إلغاء رمز إعادة التحميل.

إذا تمت معالجة الإبطال بنجاح، يكون رمز حالة HTTP للاستجابة هو 200. في حالات الخطأ، يتم عرض رمز حالة HTTP 400 مع رمز خطأ.

يوضِّح المقتطف التالي من JavaScript كيفية إبطال رمز مميّز في JavaScript بدون استخدام مكتبة Google APIs Client Library لـ JavaScript. بما أنّ نقطة نهاية OAuth 2.0 من Google لإبطال الرموز المميزة لا تتوافق مع سياسة مشاركة الموارد المتعدّدة المصادر (CORS)، ينشئ الرمز نموذجًا ويُرسِل النموذج إلى نقطة النهاية بدلاً من استخدام طريقة XMLHttpRequest() لنشر الطلب.

function revokeAccess(accessToken) {
  // Google's OAuth 2.0 endpoint for revoking access tokens.
  var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';

  // Create <form> element to use to POST data to the OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'post');
  form.setAttribute('action', revokeTokenEndpoint);

  // Add access token to the form so it is set as value of 'token' parameter.
  // This corresponds to the sample curl request, where the URL is:
  //      https://oauth2.googleapis.com/revoke?token={token}
  var tokenField = document.createElement('input');
  tokenField.setAttribute('type', 'hidden');
  tokenField.setAttribute('name', 'token');
  tokenField.setAttribute('value', accessToken);
  form.appendChild(tokenField);

  // Add form to page and submit it to actually revoke the token.
  document.body.appendChild(form);
  form.submit();
}