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

نظرة عامة

في 16 شباط (فبراير) 2022، أعلنّا عن خطط لجعل تفاعلات Google 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: يتم حظر جميع العملاء الحاليين (بما في ذلك العملاء المعفيون)

سيتم عرض رسالة خطأ موجَّهة للمستخدمين الذين يواجهون طلبات غير متوافقة. ستبلغ الرسالة المستخدمين بأن التطبيق محظور أثناء عرض البريد الإلكتروني للدعم الذي سجّلته في شاشة موافقة OAuth في "وحدة تحكُّم Google API".

ملاحظة: إذا أردت تلقّي تذكيرات وإشعارات من Google حول هذا الإيقاف النهائي، يجب التأكّد من أنّه تم ضبط معلومات الاتصال بشكل مناسب في تطبيقك من خلال مراجعة عناوين البريد الإلكتروني الخاصة بفريق الدعم والتواصل في مشروع OAuth Consent Screen page على Google API Console.

هناك خطوتَان رئيسيتَان لإكمال عملية نقل البيانات:

1. حدِّد ما إذا كنت متأثرًا بذلك.
2. نقل البيانات إلى بديل أكثر أمانًا إذا كنت متأثرًا بهذه المشكلة.

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

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

ملاحظة: يسري الإيقاف على كلٍّ من التطبيقات الداخلية والخارجية في مرحلة الإنتاج.

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

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

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

ملاحظة: إذا كنت تستخدم مكتبة للتعامل مع تدفقات المصادقة / التفويض، ننصحك أيضًا بفحص مكالمة الشبكة لأنّ بعض المكتبات تزيل استخدام قيمة 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>

ملاحظة: عليك أيضًا التحقّق من ملفات إعداد التطبيق (مثل ملفات .env) لأنّه عادةً ما يتم إعداد قيم redirect_uri لتختلف حسب البيئة التي يتم فيها تشغيل التطبيق.

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

تختلف طريقة فحص المكالمات من الشبكة وفقًا لنوع برنامج العميل.

• تطبيق الويب - فحص نشاط الشبكة على Chrome
• Android: افحص حركة بيانات الشبكة باستخدام أداة فحص الشبكة.
• تطبيقات Chrome
  • انتقِل إلى صفحة إضافات Chrome.
  • ضَع علامة في مربّع الاختيار وضع مطوّر البرامج في أعلى يسار صفحة الإضافة.
  • اختيار الإضافة التي تريد مراقبتها
  • انقر على رابط صفحة الخلفية في قسم فحص الملفات الشخصية من صفحة الإضافة.
  • ستظهر نافذة منبثقة بعنوان أدوات المطوّرين، حيث يمكنك مراقبة حركة بيانات الشبكة في علامة التبويب الشبكة.
• iOS - تحليل زيارات HTTP باستخدام الأدوات
• Universal Windows Platform (UWP) - افحص حركة بيانات الشبكة في Visual Studio
• تطبيقات الكمبيوتر المكتبي - استخدام أداة لتسجيل الشبكة متاحة لنظام التشغيل الذي تم تطوير التطبيق له

أثناء فحص مكالمات الشبكة، ابحث عن الطلبات المُرسَلة إلى نقاط نهاية التفويض في 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 أو iOS، عليك نقل البيانات باستخدام حزمة تطوير البرامج (SDK) لتسجيل الدخول إلى مواقع Google المتوافقة مع الأجهزة الجوّالة (لنظامي التشغيل Android وiOS).

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

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

الوصول إلى واجهات Google API على نظام التشغيل Android

الوصول من جهة الخادم (بلا إنترنت)

يوضّح المثال أدناه كيفية الوصول إلى واجهات Google API على جانب الخادم على أجهزة 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 API في تطبيق iOS

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

يوضّح المثال التالي كيفية الوصول إلى واجهات Google API من جهة العميل على نظام التشغيل 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 API من جهة العميل. حول كيفية الوصول إلى واجهات Google API من جهة العميل

الوصول من جهة الخادم (بلا إنترنت)

يوضّح المثال التالي كيفية الوصول إلى واجهات Google API من جهة الخادم لإتاحة برنامج 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 API للحصول على مزيد من المعلومات حول كيفية الوصول إلى مصادقة المستخدمين وطلب نقاط النهاية من Google باستخدام واجهة برمجة التطبيقات Chrome Identity API.

تطبيق الويب

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

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

الوصول من جهة الخادم (بلا إنترنت)

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

• أوقِف خادمًا وحدِّد نقطة نهاية متاحة للجميع (معرّف الموارد المنتظم (URI) لإعادة التوجيه) لتلقّي رمز التفويض.
• اضبط معرّف الموارد المنتظم (URI) لإعادة التوجيه في Credentials page من Google API Console

يعرض مقتطف الرمز التالي مثالاً على NodeJS لاستخدام Google Drive API لإدراج ملفات 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 API من جهة الخادم.

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

يعرض مقتطف الرمز التالي، في 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 API من جهة العميل.

برنامج كمبيوتر مكتبي

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

ملاحظة: يتطلب هذا التنفيذ الاستماع إلى خادم ويب محلي (على سبيل المثال، باستخدام خادم Apache HTTP) لتلقّي رمز التفويض.