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

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

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

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

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

פועלים לפי השלבים שמתוארים בקטע הגדרה כדי להגדיר את מסך ההסכמה ל-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), נעשה שימוש בטכניקות שונות במקצת בתהליכי חוויית המשתמש של מצבי ההפניה האוטומטית והחלון הקופץ. במצב Redirect, נעשה שימוש בפרמטר state של OAuth 2.0. מידע נוסף על יצירה ואימות של הפרמטר state זמין בסעיף 10.12 ב-RFC6749 בנושא זיוף בקשות חוצות אתרים. במצב חלון קופץ, מוסיפים כותרת HTTP מותאמת אישית לבקשות, ואז בשרת מאשרים שהיא תואמת לערך ולמקור הצפויים.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

דוגמה לבקשת 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, נעשה שימוש בבקשת POST.

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

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

אימות הבקשה

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

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

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

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

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

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

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

ניהול טוקנים

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

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

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