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

סקירה כללית

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

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

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

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

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

רוצים לדעת אם אתם מושפעים מהמצב?

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

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

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

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

בודקים את קוד האפליקציה או את שיחת הרשת היוצאת (אם האפליקציה משתמשת בספריית OAuth) כדי להבין אם בקשת ההרשאה של Google OAuth, שנשלחת על ידי האפליקציה, משתמשת בערך 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
  • מסמנים את התיבה מצב פיתוח בפינה השמאלית העליונה של דף התוסף
  • בחירת התוסף שברצונך לעקוב אחריו
  • לוחצים על הקישור לדף הרקע בקטע בדיקת תצוגות בדף התוסף
  • ייפתח חלון קופץ של Developer Tools, שבו אפשר לעקוב אחר התנועה ברשת דרך הכרטיסייה Network (רשת).
• 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 ומטפל בכל הקריאות לנקודות הקצה (endpoint) של 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)
    });
   });
 });
};

כדי לקבל מידע נוסף על גישה לאימות משתמשים ולקריאה לנקודות קצה ב-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) כדי לקבל את קוד ההרשאה.