מדריך להעברת זרם מחוץ למסגרת (OOB)

סקירה כללית

ב-16 בפברואר 2022, הכרזנו על תוכניות להפוך את האינטראקציות של OAuth ל-Google לבטוחות יותר באמצעות תהליכי OAuth מאובטחים יותר. המדריך הזה יעזור לך להבין את השינויים והשלבים הנחוצים כדי להעביר בהצלחה את תהליך ה-OAuth מחוץ למסגרת (OOB) אל החלופות הנתמכות.

זהו אמצעי הגנה מפני מתקפות פישינג והתחזות לאפליקציות במהלך אינטראקציות עם נקודות הקצה של הרשאות OAuth 2.0 של Google.

מה זה OOB?

מחוץ למסגרת (OOB) של OAuth, שנקראת גם אפשרות העתקה/הדבקה ידנית, הוא תהליך מדור קודם שפותח לתמיכה בלקוחות מקומיים שאין להם 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.

הערה: כדי לקבל תזכורות והתראות מ-Google לגבי ההוצאה משימוש, חשוב לוודא שהגדרת בצורה נכונה את הפרטים ליצירת קשר עם האפליקציה. לשם כך, צריך לבדוק את כתובות האימייל לתמיכה וליצירת קשר עם הפרויקט באמצעות OAuth Consent Screen page Google API Console.

יש שני שלבים עיקריים להשלמת תהליך ההעברה:

1. בדקו אם אתם מושפעים מהמצב.
2. אם זה רלוונטי, כדאי לעבור לחלופה מאובטחת יותר.

איך בודקים אם אתם מושפעים

ההוצאה משימוש רלוונטית רק לאפליקציות בסביבת ייצור (כלומר אפליקציות שסטטוס הפרסום שלהן מוגדר במצב ייצור. התהליך ימשיך לפעול באפליקציות שיש להן בדיקה של סטטוס הפרסום.

הערה: ההוצאה משימוש חלה גם על אפליקציות פנימיות וגם על אפליקציות חיצוניות בסביבת הייצור.

צריך לבדוק את סטטוס הפרסום ב-OAuth Consent Screen pageמתוך Google API Console , ולהמשיך לשלב הבא אם משתמשים ב תהליך ה-OOB בפרויקט עם סטטוס הפרסום 'בייצור'.

איך לקבוע אם האפליקציה משתמשת בתהליך ה-OOB

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

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

גישה ל-Google APIs ב-Android

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

הדוגמה הבאה ממחישה איך נכנסים ל-Google APIs בצד השרת ב-Android.

הערה: כדי להשתמש במצב הגישה בצד השרת (אופליין), צריך להציג שרת ולהיות נקודת קצה (endpoint) שזמינה לכולם כדי לקבל את קוד ההרשאה.

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()
}

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

במדריך לגישה מצד הלקוח מוסבר איך ניגשים ל-Google APIs בצד הלקוח. לגבי אופן הגישה ל-Google APIs בצד הלקוח.

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

הדוגמה הבאה ממחישה איך לגשת ל-Google APIs בצד השרת כדי לתמוך בלקוח iOS.

הערה : כדי להשתמש במצב הגישה בצד השרת (אופליין), צריך ליצור שרת ולהגדיר נקודת קצה (endpoint) שזמינה לכולם כדי לקבל את קוד ההרשאה.

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)
    });
   });
 });
};

מידע נוסף על גישה לאימות משתמשים והפעלת נקודות קצה של Google באמצעות Chrome Identity API זמין במדריך ל-Chrome Identity API.

אפליקציית אינטרנט

אם גילית שהאפליקציה שלך משתמשת בתהליך ה-OOB באפליקציית אינטרנט, עליך לעבור להשתמש באחת מספריות הלקוח של Google API. אפשר למצוא כאן ספריות לקוח לשפות התכנות השונות.

הספריות מאפשרות לגשת בקלות ל-Google APIs ולטפל בכל הקריאות לנקודות הקצה של Google.

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

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

• צריך להציב שרת ולהגדיר נקודת קצה (endpoint) נגישה לציבור (ה-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 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).

הערה: כדי לבצע את ההטמעה הזו צריך להאזין בשרת אינטרנט מקומי (לדוגמה, באמצעות שרת ה-HTTP Apache) כדי לקבל את קוד ההרשאה.