מדריך להעברת זרם מחוץ למסגרת (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 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>

בדיקה של השיחה היוצאת ברשת

השיטה לבדיקה של קריאות לרשת משתנה בהתאם לסוג הלקוח של האפליקציה.
כשבודקים קריאות רשת, צריך לחפש בקשות שנשלחו ל נקודות הקצה (endpoint) של 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 ולטפל בכל הקריאות לנקודות הקצה של Google ל-OAuth 2.0.

קישורי התיעוד הבאים מספקים מידע על השימוש בערכות ה-SDK של Google לכניסה כדי לגשת ל-Google APIs מבלי להשתמש ב-URI של הפניה אוטומטית מ-OOB.

גישה לממשקי Google API ב-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 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()
}

צריך להשתמש באסימון הגישה כדי להפעיל את ה-API. כדי לעשות זאת, יש לכלול את אסימון הגישה בכותרת של בקשת REST או gRPC (Authorization: Bearer ACCESS_TOKEN), או באמצעות הגורם המאשר אחזור (GTMFetcherAuthorizationProtocol) עם ספריית הלקוח של Google APIs עבור Objective-C ל-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, עליך לעבור להשתמש ב- API של Chrome Identity.

הדוגמה הבאה מראה איך ניתן להשיג את כל אנשי הקשר של המשתמש ללא שימוש ב-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.

גישה בצד השרת (אופליין)
במצב הגישה בצד השרת (אופליין) צריך:

קטע הקוד שלמטה מציג דוגמה של 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 בצד השרת.

גישה מצד הלקוח

קטע הקוד הבא ב-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).