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

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

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

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

אתחול לקוח קוד

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

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

כדי לאתחל לקוח עבור:

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

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

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

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

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

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

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

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: "https://your.domain/code_callback_endpoint",
  state: "YOUR_BINDING_VALUE"
});

מפעילים לקוח במקום שבו הדפדפן של המשתמש מקבל קוד הרשאה מ-Google ושולח אותו לשרת שלכם.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', code_receiver_uri, 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 ולהסכים לשתף היקפים נפרדים לפני החזרת קוד ההרשאה לנקודת הקצה להפניה אוטומטית או ל-handler של הקריאה החוזרת (callback).

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

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

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

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

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

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

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

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

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

בקשת GET לדוגמה עם פרמטרים של כתובת אתר לנקודת קצה בשם 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 קודמות, או על ידי קריאות ישירות לנקודות קצה של OAuth 2.0 של Google, נעשה שימוש בבקשת 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 אסימוני רענון וגישה רק אם אימתתם קודם את הבקשה לקוד ההרשאה.

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

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

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

ניהול אסימונים

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

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

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