راهنمای مهاجرت جریان خارج از باند (OOB).

نمای کلی

در ۱۶ فوریه ۲۰۲۲، برنامه‌هایی را برای ایمن‌تر کردن تعاملات Google OAuth با استفاده از جریان‌های OAuth امن‌تر اعلام کردیم . این راهنما به شما کمک می کند تا تغییرات و مراحل لازم برای انتقال موفقیت آمیز از جریان OAuth خارج از باند (OOB) به جایگزین های پشتیبانی شده را درک کنید.

این تلاش یک اقدام محافظتی در برابر حملات فیشینگ و جعل هویت برنامه در طول تعامل با نقاط پایانی مجوز OAuth 2.0 Google است.

OOB چیست؟

OAuth خارج از باند (OOB) که به آن گزینه کپی/پیست دستی نیز می‌گویند، یک جریان قدیمی است که برای پشتیبانی از کلاینت‌های بومی توسعه یافته است که پس از تأیید یک درخواست رضایت OAuth، URI تغییر مسیر برای پذیرش اعتبارنامه‌ها ندارند. جریان 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 Console ثبت کرده‌اید، به کاربران اطلاع می‌دهد که برنامه مسدود شده است.

دو مرحله اصلی برای تکمیل فرآیند مهاجرت وجود دارد:
  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>

به یک جایگزین امن مهاجرت کنید

مشتریان موبایل (اندروید / iOS)

اگر تشخیص می‌دهید که برنامه شما از جریان OOB با نوع کلاینت OAuth Android یا iOS استفاده می‌کند، باید به استفاده از SDK‌های تلفن همراه ورود به سیستم Google ( Android ، iOS ) مهاجرت کنید.

SDK دسترسی به API های Google را آسان می کند و همه تماس ها با نقاط پایانی مجوز OAuth 2.0 Google را مدیریت می کند.

پیوندهای اسناد زیر اطلاعاتی در مورد نحوه استفاده از Google Sign-In SDK برای دسترسی به APIهای Google بدون استفاده از URI تغییر مسیر OOB ارائه می دهد.

دسترسی به APIهای Google در Android

دسترسی سمت سرور (آفلاین).
مثال زیر نحوه دسترسی به APIهای Google در سمت سرور در 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 API از سمت سرور مرور کنید.

دسترسی به Google API در یک برنامه iOS

دسترسی سمت مشتری

مثال زیر نحوه دسترسی به APIهای Google در سمت سرویس گیرنده در 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()
}

از نشانه دسترسی برای فراخوانی API استفاده کنید، با گنجاندن رمز دسترسی در سرصفحه درخواست REST یا gRPC ( Authorization: Bearer ACCESS_TOKEN )، یا با استفاده از مجوز واکشی ( GTMFetcherAuthorizationProtocol ) با کتابخانه سرویس گیرنده Google APIs برای Objective-C. برای استراحت

راهنمای دسترسی سمت سرویس گیرنده را در مورد نحوه دسترسی به APIهای Google در سمت مشتری مرور کنید. در مورد نحوه دسترسی به API های Google در سمت مشتری.

دسترسی سمت سرور (آفلاین).
مثال زیر نحوه دسترسی به APIهای Google در سمت سرور برای پشتیبانی از کلاینت 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 API از سمت سرور مرور کنید.

سرویس گیرنده برنامه 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 ما مهاجرت کنید. کتابخانه های مشتری برای زبان های برنامه نویسی مختلف در اینجا فهرست شده اند.

کتابخانه‌ها دسترسی به APIهای Google و رسیدگی به همه تماس‌ها با نقاط پایانی 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 از سمت سرور مرور کنید.

دسترسی سمت مشتری

قطعه کد زیر، در جاوا اسکریپت، نمونه ای از استفاده از 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 ) مهاجرت کنید.