راهنمای انتقال جریان «خارج باند» (OOB)

نمای کلی

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

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

OOB چیست؟

OAuth خارج از باند (OOB)، که به آن گزینه کپی و جای‌گذاری دستی نیز گفته می‌شود، یک جریان قدیمی است که برای پشتیبانی از کارخواه‌های نصب‌شده‌ای توسعه یافته است که پس‌از تأیید درخواست رضایت OAuth توسط کاربر، URI هدایت برای پذیرش اعتبارنامه ندارند. جریان OOB خطر رمزگیری از راه دور را به‌همراه دارد و مشتریان باید به روش جایگزینی مهاجرت کنند تا دربرابر این آسیب‌پذیری محافظت شوند.

جریان OOB برای همه انواع برنامه‌ها منسوخ می‌شود—یعنی برنامه‌های وب، Android،‏ iOS،‏ Universal Windows Platform (UWP)، برنامه‌های Chrome، تلویزیون‌ها و دستگاه‌های ورودی محدود، برنامه‌های رایانه.

تاریخ‌های کلیدی برای رعایت خط‌مشی‌ها

  • ۲۸ فوریه ۲۰۲۲ - استفاده جدید از OAuth برای جریان OOB مسدود شد
  • ۵ سپتامبر ۲۰۲۲ - ممکن است پیام هشدار سَمت کاربر برای درخواست‌های OAuth ناسازگار نمایش داده شود
  • ۳ اکتبر ۲۰۲۲ - جریان OOB برای کارخواه‌های OAuth ایجادشده قبل‌از ۲۸ فوریه ۲۰۲۲ منسوخ می‌شود
  • ۳۱ ژانویه ۲۰۲۳ - همه مشتریان موجود مسدود می‌شوند (ازجمله مشتریان معاف‌شده)

برای درخواست‌های غیرمنطبق، پیام خطای سَمت کاربر نمایش داده خواهد شد. این پیام به کاربران اطلاع می‌دهد که برنامه مسدود شده است و ایمیل پشتیبانی را که در صفحه رضایت OAuth در کنسول Google Cloud ثبت کرده‌اید نمایش می‌دهد.

دو مرحله اصلی برای تکمیل فرایند انتقال وجود دارد:

  1. ببینید آیا تحت‌تأثیر قرار گرفته‌اید یا نه.
  2. اگر تحت تأثیر قرار گرفته‌اید، به یک جایگزین امن‌تر مهاجرت کنید.

تعیین اینکه آیا تحت‌تأثیر قرار گرفته‌اید یا نه

این منسوخ شدن فقط برای برنامه‌های تولید (یعنی برنامه‌هایی که وضعیت انتشار آن‌ها روی در تولید تنظیم شده است) اعمال می‌شود. این جریان همچنان برای برنامه‌هایی که وضعیت انتشار آزمایشی دارند کار خواهد کرد.

وضعیت انتشار خود را در OAuth صفحه نمانام‌سازی از Google Cloud 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 یا iOS استفاده می‌کند، باید به استفاده از کیت‌های توسعه نرم‌افزار توصیه‌شده (Android، iOS) مهاجرت کنید.

کیت توسعه نرم‌افزار به شما کمک می‌کند به Google APIs دسترسی پیدا کنید و همه فراخوانی‌ها به نقطه‌های پایانی مجوز OAuth 2.0 Google را مدیریت می‌کند.

پیوندهای اسناد زیر اطلاعاتی درباره نحوه استفاده از کیت‌های توسعه نرم‌افزار توصیه‌شده برای دسترسی به Google API بدون استفاده از URI تغییرمسیر OOB ارائه می‌دهند.

دسترسی به Google APIs در Android

دسترسی سمت کارخواه

مثال زیر نشان می‌دهد که چگونه بااستفاده از «کتابخانه Android سرویس‌های مدیریت هویت‌سنجی Google» توصیه‌شده، در سمت کارخواه در Android به Google APIs دسترسی پیدا کنید.

List<Scopes> requestedScopes = Arrays.asList(DriveScopes.DRIVE_APPDATA);
AuthorizationRequest authorizationRequest =
    AuthorizationRequest.builder()
        .setRequestedScopes(requestedScopes)
        .build();
Identity.getAuthorizationClient(activity)
    .authorize(authorizationRequest)
    .addOnSuccessListener(
        authorizationResult -> {
          if (authorizationResult.hasResolution()) {
            // Access needs to be granted by the user
            PendingIntent pendingIntent =
                authorizationResult.getPendingIntent();
            try {
              startIntentSenderForResult(
                  pendingIntent.getIntentSender(),
                  REQUEST_AUTHORIZE, null, 0, 0, 0, null);
            } catch (IntentSender.SendIntentException e) {
              Log.e(
                  TAG,
                  "Couldn't start Authorization UI: "
                      + e.getLocalizedMessage());
            }
          } else {
            // Access already granted, continue with user action
            saveToDriveAppFolder(authorizationResult);
          }
        })
    .addOnFailureListener(e -> Log.e(TAG, "Failed to authorize", e));

authorizationResult را به روش تعریف‌شده‌تان منتقل کنید تا محتوا در پوشه Drive کاربر ذخیره شود. authorizationResult دارای روش getAccessToken() است که کد دسترسی را برمی‌گرداند.

دسترسی سمت سرور (آفلاین)

مثال زیر نحوه دسترسی به Google API در سمت سرور در Android را نشان می‌دهد.

List<Scopes> requestedScopes = Arrays.asList(DriveScopes.DRIVE_APPDATA);
AuthorizationRequest authorizationRequest =
    AuthorizationRequest.builder()
        .requestOfflineAccess(webClientId)
        .setRequestedScopes(requestedScopes)
        .build();
Identity.getAuthorizationClient(activity)
    .authorize(authorizationRequest)
    .addOnSuccessListener(
        authorizationResult -> {
          if (authorizationResult.hasResolution()) {
            // Access needs to be granted by the user
            PendingIntent pendingIntent =
                authorizationResult.getPendingIntent();
            try {
              startIntentSenderForResult(
                  pendingIntent.getIntentSender(),
                  REQUEST_AUTHORIZE, null, 0, 0, 0, null);
            } catch (IntentSender.SendIntentException e) {
              Log.e(
                  TAG,
                  "Couldn't start Authorization UI: "
                      + e.getLocalizedMessage());
            }
          } else {
            String authCode =
                authorizationResult.getServerAuthCode();
          }
        })
    .addOnFailureListener(e -> Log.e(TAG, "Failed to authorize", e));

authorizationResult دارای روش getServerAuthCode() است که کد مجوز را برمی‌گرداند و می‌توانید آن را به پسای خود ارسال کنید تا ژتون دسترسی و بازآوری را دریافت کنید.

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

دسترسی سمت کارخواه

مثال زیر نشان می‌دهد که چگونه می‌توان در سمت کارخواه در iOS به Google API دسترسی پیدا کرد.

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 <var>ACCESS_TOKEN</var>)، یا بااستفاده از صادرکننده مجوز واکشی (GTMFetcherAuthorizationProtocol) با کتابخانه کارخواه Google APIs برای Objective-C برای REST.

راهنمای دسترسی سمت کارخواه را درباره نحوه دسترسی به 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 following example 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)
    });
   });
 });
};

برای اطلاعات بیشتر درباره نحوه دسترسی به اصالت‌سنجی کاربران و فراخوانی نقاط پایانی Google با Chrome Identity API، راهنمای Chrome Identity API را مرور کنید.

برنامه وب

اگر تشخیص دادید که برنامه‌تان از جریان OOB برای برنامه وب استفاده می‌کند، باید به استفاده از یکی از کتابخانه‌های کارخواه Google API ما مهاجرت کنید. فهرست کتابخانه‌های کارخواه Google API را برای زبان‌های برنامه‌نویسی مختلف ببینید.

کتابخانه‌ها دسترسی به Google API را ساده می‌کنند و همه فراخوانی‌ها به نقاط پایانی Google را مدیریت می‌کنند.

دسترسی سمت سرور (آفلاین)

حالت دسترسی سمت سرور (آفلاین) مستلزم این است که کارهای زیر را انجام دهید :

  • سروری راه‌اندازی کنید و نقطه پایانی با دسترسی عمومی (URI هدایت) برای دریافت کد مجوز تعریف کنید.
  • URI هدایت را در صفحه کارخواه‌ها در Google Cloud 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 APIs از سمت سرور مرور کنید.

دسترسی سمت کارخواه

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