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

הספרייה של 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() מאתחלת לקוח קוד.

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

אפשר לשתף קוד הרשאה באמצעות זרימת המשתמש במצב הפניה אוטומטית או במצב חלון קופץ. במצב 'הפניה אוטומטית', אתם מארחים נקודת קצה של הרשאת 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

בהתאם ל-RFC 6749, הלקוחות חייבים להתעלם מפרמטרים של תגובה שלא מזוהים, בלי קשר לשאלה אם הם מופיעים בטבלה הקודמת.

דוגמה לבקשת 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.