دليل نقل البيانات خارج النطاق (OOB)

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

نظرة عامة

في 16 شباط (فبراير) 2022، تم الإعلان عن خطط لجعل تفاعلات Google OAuth أكثر أمانًا من خلال استخدام مسارات OAuth أكثر أمانًا. يساعدك هذا الدليل في فهم التغييرات والخطوات اللازمة لنقل البيانات بنجاح من تدفق OAuth خارج النطاق (OOB) إلى البدائل المتوافقة.

وتُعدّ هذه الجهود إجراء وقائي ضد التصيّد الاحتيالي وهجمات انتحال هوية التطبيقات أثناء التفاعل مع نقاط نهاية تفويض OAuth 2.0 في Google.

ما المقصود ببروتوكول OOB؟

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

يتم إيقاف مسار OOB لجميع أنواع البرامج، مثل تطبيقات الويب وتطبيقات Android وiOS وUniversal Windows Platform (UWP) وتطبيقات Chrome وأجهزة التلفزيون والأجهزة ذات الإدخال المحدود والتطبيقات المتوافقة مع أجهزة كمبيوتر سطح المكتب.

تواريخ الامتثال الرئيسية

  • 28 شباط (فبراير) 2022: تم حظر استخدام بروتوكول OAuth الجديد لتدفق OOB.
  • 5 أيلول (سبتمبر) 2022: قد يتم عرض رسالة تحذير تظهر للمستخدم على طلبات OAuth غير المتوافقة.
  • 3 تشرين الأول (أكتوبر) 2022: تم إيقاف مسار OOB لعملاء OAuth الذين تم إنشاؤهم قبل 28 شباط (فبراير) 2022.
  • 31 كانون الثاني (يناير) 2023: يتم حظر جميع العملاء الحاليين (بما في ذلك العملاء المعفاة). ويمكن للعملاء طلب تمديد لمرة واحدة لمواصلة استخدام مسار OOB حتى 31 كانون الثاني (يناير) 2023، وفقًا للإرشادات الواردة في الرسالة الإلكترونية التي تم إرسالها إلى العملاء المتأثرين.

وقد يتم عرض رسالة تحذير للمستخدم بسبب الطلبات غير المتوافقة قبل شهر واحد، أي 5 أيلول (سبتمبر) 2022، وقد تم إيقاف مسار OOB بالكامل. ستُعلِم الرسالة المستخدمين بأنه قد يتم حظر التطبيق قريبًا أثناء عرض رسالة الدعم الإلكترونية التي سجّلتها في شاشة موافقة OAuth في وحدة تحكُّم Google API.

يمكنك الإقرار برسالة التحذير التي تظهر للمستخدم ومنعها من خلال تمرير معلَمة طلب بحث في طلب التفويض على النحو الموضّح أدناه:
  • انتقِل إلى الرمز في تطبيقك الذي ترسل الطلبات إلى نقطة نهاية تفويض OAuth 2.0 من Google.
  • أضِف معلَمة ack_oob_shutdown مع قيمة تاريخ التنفيذ: 2022-10-03 إلى طلب مسار إعادة التوجيه. مثال:
    ack_oob_shutdown=2022-10-03
هناك خطوتان أساسيتان لإكمال عملية نقل البيانات:
  1. حدِّد ما إذا كنت متأثرًا بالمشكلة.
  2. نقل البيانات إلى خيار بديل أكثر أمانًا في حال تأثّرك بهذه المشكلة

تحديد ما إذا كنت متأثرًا بالمشكلة

لا ينطبق هذا الإيقاف إلا على تطبيقات الإنتاج (أي التطبيقات التي تم ضبط حالة النشر على في مرحلة الإنتاج). وستستمر العملية في العمل للتطبيقات التي تحمل حالة اختبار النشر.

راجِع حالة النشر في OAuth Consent Screen page من Google API Console وانتقِل إلى الخطوة التالية في حال استخدام مسار OOB في مشروع يحمل حالة النشر "قيد الإنتاج".

كيفية تحديد ما إذا كان تطبيقك يستخدم مسار OOB

افحص رمز تطبيقك أو مكالمة الشبكة الصادرة (في حال استخدام تطبيقك لمكتب OAuth) لتحديد ما إذا كان طلب تفويض Google OAuth يستخدم تطبيقك قيمة معرّف الموارد المنتظم (URI) لإعادة التوجيه OOB.

فحص رمز التطبيق

راجِع قسم رمز التطبيق الذي تُجري فيه عمليات استدعاء نقاط نهاية تفويض Google OAuth وحدِّد ما إذا كانت المعلَمة redirect_uri تحتوي على أيٍّ من القيم التالية:
  • redirect_uri=urn:ietf:wg:oauth:2.0:oob
  • redirect_uri=urn:ietf:wg:oauth:2.0:oob:auto
  • redirect_uri=oob
سيظهر نموذج طلب إعادة توجيه OOB على النحو التالي:
https://accounts.google.com/o/oauth2/v2/auth?
response_type=code&
scope=<SCOPES>&
state=<STATE>&
redirect_uri=urn:ietf:wg:oauth:2.0:oob&
client_id=<CLIENT_ID>

فحص المكالمات الصادرة عبر الشبكة

تختلف طريقة فحص اتصالات الشبكة حسب نوع برنامج التطبيق.
أثناء فحص طلبات الشبكة، ابحث عن الطلبات المُرسَلة إلى نقاط نهاية التفويض في Google OAuth وحدِّد ما إذا كانت المعلّمة redirect_uri تحتوي على أي من القيم التالية:
  • redirect_uri=urn:ietf:wg:oauth:2.0:oob
  • redirect_uri=urn:ietf:wg:oauth:2.0:oob:auto
  • redirect_uri=oob
سيظهر نموذج طلب إعادة توجيه OOB على النحو التالي:
https://accounts.google.com/o/oauth2/v2/auth?
response_type=code&
scope=<SCOPES>&
state=<STATE>&
redirect_uri=urn:ietf:wg:oauth:2.0:oob&
client_id=<CLIENT_ID>

نقل البيانات إلى بديل آمن

برامج الأجهزة الجوّالة (Android / iOS)

إذا تبيّن لك أنّ تطبيقك يستخدم مسار OOB مع نوع عميل يستخدم بروتوكول OAuth أو Android ، عليك نقل البيانات إلى حزم تطوير البرامج (SDK) المخصّصة لتسجيل الدخول إلى Google على الأجهزة الجوّالة (Android أو iOS).

تُسهّل حزمة تطوير البرامج (SDK) الوصول إلى Google APIs وتعالج جميع المكالمات إلى نقاط نهاية تفويض OAuth 2.0 من Google.

توفّر روابط المستندات أدناه معلومات حول كيفية استخدام حزم تطوير البرامج (SDK) لتسجيل الدخول بحساب Google للوصول إلى Google APIs بدون استخدام معرّف الموارد المنتظم (URI) لإعادة التوجيه OOB.

الوصول إلى Google APIs على Android

الوصول من جهة الخادم (بلا اتصال بالإنترنت)
يوضح المثال أدناه كيفية الوصول إلى Google APIs على جانب الخادم على نظام Android.
Task<GoogleSignInAccount> task = GoogleSignIn.getSignedInAccountFromIntent(data);
try {
  GoogleSignInAccount account = task.getResult(ApiException.class);
  
  // request a one-time authorization code that your server exchanges for an
  // access token and sometimes refresh token
  String authCode = account.getServerAuthCode();
  
  // Show signed-in UI
  updateUI(account);

  // TODO(developer): send code to server and exchange for access/refresh/ID tokens
} catch (ApiException e) {
  Log.w(TAG, "Sign-in failed", e);
  updateUI(null);
}

راجِع دليل الوصول من جهة الخادم حول كيفية الوصول إلى Google APIs من جهة الخادم.

الوصول إلى Google APIs في تطبيق iOS

الوصول من جهة العميل

يوضح المثال أدناه كيفية الوصول إلى Google APIs من جانب العميل على نظام التشغيل iOS.

user.authentication.do { authentication, error in
  guard error == nil else { return }
  guard let authentication = authentication else { return }
  
  // Get the access token to attach it to a REST or gRPC request.
  let accessToken = authentication.accessToken
  
  // Or, get an object that conforms to GTMFetcherAuthorizationProtocol for
  // use with GTMAppAuth and the Google APIs client library.
  let authorizer = authentication.fetcherAuthorizer()
}

استخدِم رمز الدخول لاستدعاء واجهة برمجة التطبيقات، من خلال تضمين رمز الدخول في عنوان طلب REST أو gRPC (Authorization: Bearer ACCESS_TOKEN)، أو من خلال استخدام الجهة الاسترجاعية (GTMFetcherAuthorizationProtocol) مع مكتبة برامج Google APIs لـ Purpose-C for REST.

راجِع دليل الوصول من جهة العميل حول كيفية الوصول إلى Google APIs من جهة العميل. عن كيفية الوصول إلى Google APIs من جهة العميل.

الوصول من جهة الخادم (بلا إنترنت)
يوضح المثال أدناه كيفية الوصول إلى Google APIs من جهة الخادم لدعم برنامج iOS.
GIDSignIn.sharedInstance.signIn(with: signInConfig, presenting: self) { user, error in
  guard error == nil else { return }
  guard let user = user else { return }
  
  // request a one-time authorization code that your server exchanges for
  // an access token and refresh token
  let authCode = user.serverAuthCode
}

راجِع دليل الوصول من جهة الخادم حول كيفية الوصول إلى Google APIs من جهة الخادم.

عميل تطبيق Chrome

إذا تبيّن لك أنّ تطبيقك يستخدم مسار OOB في برنامج تطبيق Chrome، عليك نقل البيانات باستخدام Chrome Identity API.

يوضح المثال أدناه كيفية الحصول على جميع جهات اتصال المستخدمين بدون استخدام معرّف موارد منتظم (URI) لإعادة تشغيل OOB.

window.onload = function() {
  document.querySelector('button').addEventListener('click', function() {

  
  // retrieve access token
  chrome.identity.getAuthToken({interactive: true}, function(token) {
  
  // ..........


  // the example below shows how to use a retrieved access token with an appropriate scope
  // to call the Google People API contactGroups.get endpoint

  fetch(
    'https://people.googleapis.com/v1/contactGroups/all?maxMembers=20&key=API_KEY',
    init)
    .then((response) => response.json())
    .then(function(data) {
      console.log(data)
    });
   });
 });
};

راجِع دليل واجهة برمجة تطبيقات Chrome Identity للحصول على مزيد من المعلومات عن كيفية الوصول إلى مصادقة المستخدمين واستدعاء نقاط نهاية Google باستخدام واجهة برمجة تطبيقات Chrome Identity.

تطبيق الويب

إذا تبيّن لك أن تطبيقك يستخدم مسار OOB لتطبيق ويب، عليك نقل البيانات إلى إحدى مكتبات عملاء Google API. يتم إدراج مكتبات العملاء لمختلف لغات البرمجة هنا.

تُسهّل المكتبات الوصول إلى واجهات Google API وتتعامل مع جميع الطلبات إلى نقاط نهاية Google.

الوصول من جهة الخادم (بلا إنترنت)
يتطلّب وضع الوصول من جهة الخادم (بلا اتصال بالإنترنت) إجراء ما يلي:

يُظهر مقتطف الرمز التالي مثالاً على استخدام NodeJS لواجهة برمجة تطبيقات Google Drive لإدراج ملفات المستخدم على Google Drive من جهة الخادم بدون استخدام معرف موارد منتظم (URI) لـ OOB.

async function main() {
  const server = http.createServer(async function (req, res) {

  if (req.url.startsWith('/oauth2callback')) {
    let q = url.parse(req.url, true).query;

    if (q.error) {
      console.log('Error:' + q.error);
    } else {
      
      // Get access and refresh tokens (if access_type is offline)
      let { tokens } = await oauth2Client.getToken(q.code);
      oauth2Client.setCredentials(tokens);

      // Example of using Google Drive API to list filenames in user's Drive.
      const drive = google.drive('v3');
      drive.files.list({
        auth: oauth2Client,
        pageSize: 10,
        fields: 'nextPageToken, files(id, name)',
      }, (err1, res1) => {
        // TODO(developer): Handle response / error.
      });
    }
  }
}

راجِع دليل تطبيق الويب من جهة الخادم حول طريقة الوصول إلى Google APIs من جهة الخادم.

الوصول من جهة العميل

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


// initTokenClient() initializes a new token client with your
// web app's client ID and the scope you need access to

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  
  // callback function to handle the token response
  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(...);
}

راجِع دليل تطبيقات الويب من جهة العميل حول كيفية الوصول إلى Google APIs من جهة العميل.

برنامج سطح المكتب

إذا تبيّن لك أنّ تطبيقك يستخدم مسار OOB على برنامج كمبيوتر مكتبي، عليك نقل البيانات إلى الموقع الإلكتروني باستخدام تدفق عنوان IP (localhost أو 127.0.0.1).