שימוש במודל הקוד

הספרייה של Google Identity Services מאפשרת למשתמשים לבקש קוד הרשאה מ-Google באמצעות חלון קופץ מבוסס-דפדפן או זרימת חוויית משתמש של הפניה אוטומטית. הפעולה הזו מתחילה תהליך מאובטח של OAuth 2.0 ומסתיימת באסימון גישה שמשמש להפעלת ממשקי Google API מטעם המשתמש.

סיכום של תהליך הרשאה באמצעות קוד OAuth 2.0:

• מדפדפן, באמצעות תנועה כמו לחיצה על לחצן, הבעלים של חשבון Google מבקש קוד הרשאה מ-Google.
• ‫Google מגיבה ושולחת קוד הרשאה ייחודי או לקריאה חוזרת באפליקציית האינטרנט של JavaScript שפועלת בדפדפן של המשתמש, או שמפעילה ישירות את נקודת הקצה של קוד ההרשאה באמצעות הפניה אוטומטית בדפדפן.
• פלטפורמת ה-Backend מארחת נקודת קצה של קוד הרשאה ומקבלת את הקוד. אחרי האימות, הפלטפורמה מחליפה את הקוד הזה באסימוני גישה ורענון לכל משתמש באמצעות בקשה לנקודת הקצה של Google לאסימונים.
• ‫Google מאמתת את קוד ההרשאה, מוודאת שהבקשה הגיעה מהפלטפורמה המאובטחת שלכם, מנפיקה אסימוני גישה ורענון ומחזירה את האסימונים על ידי קריאה לנקודת הקצה של ההתחברות שמתארחת בפלטפורמה שלכם.
• נקודת הקצה (endpoint) של הכניסה מקבלת את אסימוני הגישה והרענון, ומאחסנת בצורה מאובטחת את אסימון הרענון לשימוש מאוחר יותר.

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

דרישות מוקדמות

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

אתחול של לקוח Code

השיטה google.accounts.oauth2.initCodeClient() מאתחלת לקוח קוד.

מצב חלון קופץ או הפניה אוטומטית

אפשר לבחור לשתף קוד אימות באמצעות זרימת המשתמש במצב הפניה אוטומטית או במצב חלון קופץ. במצב Redirect, אתם מארחים נקודת קצה של הרשאת OAuth2 בשרת שלכם, ו-Google מפנה את סוכן המשתמש לנקודת הקצה הזו, ומשתפת את קוד האימות כפרמטר של כתובת URL. במצב חלון קופץ, מגדירים פונקציית callback של JavaScript ששולחת את קוד ההרשאה לשרת. אתם יכולים להשתמש במצב חלון קופץ כדי לספק חוויית משתמש חלקה בלי שהמבקרים יצטרכו לצאת מהאתר.

כדי לאתחל לקוח בשביל:

• מגדירים את ux_mode ל-redirect, ואת הערך של redirect_uri לנקודת הקצה של קוד ההרשאה בפלטפורמה. הערך צריך להיות זהה בדיוק לאחד מכתובות ה-URI המורשות להפניה אוטומטית של לקוח OAuth 2.0 שהגדרתם ב-Google Cloud Console. הוא צריך גם לעמוד בכללים לאימות URI של הפניה.

• תהליך חוויית המשתמש בחלון קופץ, מגדירים את ux_mode ל-popup ואת הערך של callback לשם הפונקציה שבה תשתמשו כדי לשלוח קודי הרשאה לפלטפורמה שלכם. ערך ברירת המחדל של redirect_uri הוא המקור של הדף שקורא ל-initCodeClient. הערך הזה ישמש בהמשך התהליך כשמחליפים את קוד האימות באסימון גישה או באסימון רענון. לדוגמה, אם https://www.example.com/index.html מתקשר אל initCodeClient והמקור: https://www.example.com הוא הערך של redirect_url.

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

הגנה מפני מתקפות CSRF

בתהליכי חוויית המשתמש במצב הפניה אוטומטית ובמצב חלון קופץ נעשה שימוש בטכניקות שונות במקצת כדי למנוע תקיפות של זיוף בקשות חוצות אתרים (CSRF). במצב 'הפניה אוטומטית', צריך להשתמש בפרמטר state של OAuth 2.0. מידע נוסף על יצירה ואימות של הפרמטר state זמין בסעיף 10.12 ב-RFC6749 בנושא זיוף בקשות חוצות אתרים. במצב חלון קופץ, מוסיפים כותרת HTTP מותאמת אישית לבקשות, ואז בשרת מאשרים שהיא תואמת לערך ולמקור הצפויים.

בוחרים מצב UX כדי לראות קטע קוד שבו מוצגים קוד האימות וטיפול ב-CSRF:

מצב הפניה אוטומטית

מאתחלים לקוח שבו Google מפנה את הדפדפן של המשתמש לנקודת הקצה של האימות, ומשתפת את קוד ההרשאה כפרמטר של כתובת URL.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: 'https://oauth2.example.com/code',
  state: 'YOUR_BINDING_VALUE'
});

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

מצב חלון קופץ

מאחלים אתחול של לקוח שבו המשתמש מתחיל את תהליך ההרשאה בתיבת דו-שיח קופצת. אחרי שהמשתמש מביע הסכמה, Google מחזירה את קוד ההרשאה לדפדפן של המשתמש באמצעות פונקציית קריאה חוזרת. בקשת POST ממטפל הקריאות החוזרות של JS מעבירה את קוד האימות לנקודת קצה בשרת העורפי, שבו מאמתים אותו ואז משלימים את שאר תהליך OAuth.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', "https://oauth2.example.com/code", true);
    xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    // Set custom header for CRSF
    xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
    xhr.onload = function() {
      console.log('Auth code response: ' + xhr.responseText);
    };
    xhr.send('code=' + response.code);
  },
});

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

הפעלת תהליך קוד OAuth 2.0

מתקשרים לשיטה requestCode() של לקוח הקוד כדי להפעיל את תהליך המשתמש:

<button onclick="client.requestCode();">Authorize with Google</button>

המשתמש יצטרך להיכנס לחשבון Google ולהסכים לשיתוף של היקפי הרשאות ספציפיים לפני שיוחזר קוד הרשאה לנקודת הקצה להפניה או ל-callback handler.

טיפול בקוד אימות

‫Google יוצרת קוד הרשאה ייחודי לכל משתמש, שאתם מקבלים ומאמתים בשרת העורפי שלכם.

במצב חלון קופץ, ה-handler שצוין על ידי callback, שפועל בדפדפן של המשתמש, מעביר את קוד ההרשאה לנקודת קצה שמתארחת בפלטפורמה שלכם.

במצב הפניה אוטומטית, Google שולחת בקשת GET לנקודת הקצה שצוינה על ידי redirect_uri, ומשתפת את קוד ההרשאה בפרמטר code של כתובת ה-URL. כדי לקבל את קוד ההרשאה:

• יוצרים נקודת קצה חדשה להרשאה אם אין לכם הטמעה קיימת, או

• מעדכנים את נקודת הקצה הקיימת כדי לקבל בקשות GET ופרמטרים של כתובת URL. בעבר, Google שלחה בקשת PUT עם ערך קוד ההרשאה במטען הייעודי (payload).

נקודת קצה להרשאה

נקודת הקצה של קוד ההרשאה צריכה לטפל בבקשות מסוג GET עם הפרמטרים הבאים של מחרוזת השאילתה של כתובת ה-URL:

שם	ערך
authuser	בקשה לאימות של כניסת משתמש
קוד	קוד הרשאה ל-OAuth2 שנוצר על ידי Google
hd	הדומיין המתארח של חשבון המשתמש
הנחיה	תיבת דו-שיח להבעת הסכמה של משתמשים
היקף	רשימה מופרדת ברווחים של היקפי OAuth2 אחד או יותר שיש לאשר
הסמוי הסופי	משתנה מצב CRSF

דוגמה לבקשת GET עם פרמטרים של כתובת URL לנקודת קצה בשם auth-code שמתארחת בכתובת example.com:

Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent

כשמתחילים את תהליך קבלת קוד ההרשאה באמצעות ספריות JavaScript קודמות, או באמצעות ביצוע קריאות ישירות לנקודות הקצה של Google OAuth 2.0, ‏ Google שולחת בקשת POST.

דוגמה לבקשת POST שמכילה את קוד ההרשאה כמטען ייעודי (payload) בגוף בקשת ה-HTTP:

Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw

חשוב: בעבר, נעשה שימוש ב-POST לבקשות. כדי להמשיך להשתמש בספריות JS ישנות יותר או לקרוא ישירות לנקודות הקצה של Google OAuth 2.0 בזמן השימוש בספרייה של Google Identity Services, צריך לעדכן את ה-handler כך שיקבל בקשות של GET ושל POST, או לשקול לארח שתי נקודות קצה שונות.

אימות הבקשה

כדי להימנע ממתקפות CSRF, צריך לבצע את הפעולות הבאות בשרת.

בודקים את הערך של הפרמטר state במצב הפניה אוטומטית.

מאשרים שהכותרת X-Requested-With: XmlHttpRequest מופיעה במצב חלון קופץ.

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

קבלת אסימוני גישה ורענון

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

פועלים לפי ההוראות החל משלב 5: החלפת קוד ההרשאה באסימוני רענון וגישה במדריך שימוש ב-OAuth 2.0 לאפליקציות אינטרנט.

הערה: כשמשתמשים במצב חלון קופץ, הערך redirect_uri שבו משתמשים בשלב 5 ובשלבים הבאים הוא המקור של הדף שממנו מתבצעת הקריאה. לדוגמה, אם https://www.example.com/index.html הוא שם השיטה initCodeClient והמקור: https://www.example.com הוא הערך של redirect_url.

ניהול טוקנים

הפלטפורמה שלכם מאחסנת באופן מאובטח את טוקני הרענון. צריך למחוק את אסימוני הרענון המאוחסנים כשמסירים חשבונות משתמשים, או כשמשתמש מבטל את ההסכמה באמצעות google.accounts.oauth2.revoke או ישירות מכתובת https://myaccount.google.com/permissions.

אפשר גם להשתמש ב-RISC כדי להגן על חשבונות משתמשים באמצעות הגנה על חשבונות שונים.

בדרך כלל, פלטפורמת ה-Backend שלכם תפעיל ממשקי Google API באמצעות אסימון גישה. אם אפליקציית האינטרנט שלכם תפעיל גם קריאות ישירות לממשקי Google API מהדפדפן של המשתמש, תצטרכו להטמיע דרך לשיתוף אסימון הגישה עם אפליקציית האינטרנט. ההסבר על כך לא נכלל במדריך הזה. כשמשתמשים בגישה הזו ובספריית הלקוח של Google API ל-JavaScript, משתמשים ב-gapi.client.SetToken() כדי לאחסן באופן זמני את אסימון הגישה בזיכרון של הדפדפן, וכך מאפשרים לספרייה לקרוא ל-Google APIs.