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

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

סיכום זרימה של קוד הרשאה ב-OAuth 2.0:

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

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

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

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

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

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

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

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

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

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

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

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

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

מצב הפניה לכתובת URL אחרת

לאתחל לקוח שבו 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

אימות הבקשה

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

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

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

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

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

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

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

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

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

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

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