استخدام 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 for 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 في عنوان HTTP Authorization. عند الإمكان، من الأفضل استخدام عنوان HTTP لأنّ سلاسل طلب البحث تكون عادةً مرئية في سجلات الخادم. في معظم الحالات، يمكنك استخدام مكتبة برامج لإعداد طلباتك إلى واجهات Google API (على سبيل المثال، عند استدعاء YouTube Data API).

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

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

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

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

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 Client Library for 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 للغة 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 نفسه الذي يتم عرض الصفحة عليه. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المسموح بها لإعادة التوجيه الخاصة بعميل OAuth 2.0 الذي تم إعداده في . إذا لم تتطابق هذه القيمة مع معرّف URI معتمَد، سيظهر لك الخطأ 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

في هذا المثال، يطلب تطبيق الاتصال إذنًا بالوصول إلى بيانات "إحصاءات 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 for 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();
}