دليل نقل التدفق خارج النطاق (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: تم حظر جميع العملاء الحاليين (بما في ذلك العملاء المعفيون).

ستظهر رسالة خطأ موجَّهة للمستخدمين للطلبات غير المتوافقة مع السياسة. ستنقل الرسالة إلى المستخدمين تفيد بأنّه تم حظر التطبيق أثناء عرض الرسالة الإلكترونية للدعم التي سجّلتها في شاشة موافقة 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: فحص حركة بيانات الشبكة باستخدام Network Inspector (أداة فحص الشبكة)
• تطبيقات Chrome
  • انتقِل إلى صفحة إضافات Chrome.
  • ضَع علامة في مربّع الاختيار وضع مطوّر البرامج في أعلى يسار صفحة الإضافات.
  • اختيار الإضافة التي تريد مراقبتها
  • انقر على رابط صفحة الخلفية في قسم فحص الملفات الشخصية في صفحة الإضافة.
  • ستظهر نافذة منبثقة باسم أدوات المطوّرين (Developer Tools) من أجل مساعدتك في رصد حركة بيانات الشبكة في علامة التبويب "الشبكة".
• 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 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 لـ Objective-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 API للاطّلاع على مزيد من المعلومات حول كيفية الوصول إلى مصادقة المستخدمين وطلب نقاط نهاية Google باستخدام Chrome Identity API.

تطبيق الويب

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

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

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

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

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

يعرض مقتطف الرمز أدناه مثال 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).

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