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

סקירה כללית

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

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

מה זה 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, תוצג הודעת האימייל לתמיכה שרשמתם.

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

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

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

קביעה אם אתם מושפעים

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

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

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

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

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

הערה: מומלץ לבדוק גם את קובצי התצורה של האפליקציה (כמו קובצי .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 ל-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)
    });
   });
 });
};

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

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

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

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