קישור של חשבון Google באמצעות OAuth (זרם הענקת גישה משתמע – בארכיון)

כדי לתמוך בתהליך המשתמע של OAuth 2.0, השירות שלכם צריך לספק נקודת קצה להרשאה באמצעות HTTPS. נקודת הקצה הזו אחראית לאימות ולקבלת הסכמה מהמשתמשים לגישה לנתונים. נקודת הקצה של ההרשאה מציגה למשתמשים שלא מחוברים כבר ממשק משתמש לכניסה, ומתעדת את ההסכמה לגישה המבוקשת.

כשיישום של Google צריך לשלוח קריאה לאחד מממשקי ה-API המורשים של השירות שלכם, Google משתמשת בנקודת הקצה הזו כדי לקבל מהמשתמשים שלכם הרשאה לשלוח קריאות לממשקי ה-API האלה בשמם.

קישור של חשבון Google: תהליך מרומז של OAuth

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

משתמש אפליקציית Google / דפדפן נקודת הקצה של האימות ‫1. המשתמש יוזם את הקישור 2. הפניה לנקודת הקצה של אימות (GET) client_id, redirect_uri, state, scope 3. הצגת מסך הכניסה ומסך בקשת ההסכמה 4. המשתמש מאמת את עצמו ומעניק הסכמה 5. הפניה חזרה אל Google עם טוקן (GET) access_token, state 6. אחסון טוקנים של משתמשים בחנות 7. גישה למשאבים של משתמשים
איור 1. רצף האירועים בזרם הענקת גישה משתמע של OAuth 2.0 לקישור של חשבון Google.

תפקידים ותחומי אחריות

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

המשתמש / הרכיב תפקיד ב-GAL תחומי אחריות
אפליקציית Google / שרת לקוח OAuth מתחיל את התהליך, מקבל את אסימון הגישה באמצעות הפניה אוטומטית בדפדפן, ומאחסן אותו בצורה מאובטחת כדי לגשת לממשקי ה-API של השירות.
נקודת הקצה להרשאה שרת הרשאות השירות מאמת את המשתמשים, מקבל את ההסכמה שלהם ומנפיק אסימוני גישה לטווח ארוך ישירות ל-Google.
‫URI של הפניה לכתובת אחרת ב-Google נקודת קצה של קריאה חוזרת (callback) מקבל את ההפניה האוטומטית של המשתמש משירות ההרשאה עם הערכים access_token ו-state בקטע של כתובת ה-URL.

סשן טיפוסי של זרם הענקת גישה משתמע באמצעות OAuth 2.0 שמופעל על ידי Google כולל את התהליך הבא:

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

מתכון להטמעה

כדי להטמיע את זרם הענקת גישה משתמע:

שלב 1: טיפול בבקשות הרשאה

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

כדי לטפל בבקשה, מבצעים את הפעולות הבאות:

  1. אימות הבקשה:

    • מוודאים שהערך client_id זהה למזהה הלקוח שהוקצה ל-Google.
    • מוודאים שכתובת ה-URL של ההפניה האוטומטית של Google שמופיעה ב-redirect_uri זהה לכתובת ה-URL הצפויה: none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
    • מוודאים ש-response_type הוא token.

  2. מאמתים את המשתמש:

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

  3. יצירת אסימון גישה:

    • יצירת טוקן גישה ייחודי שאי אפשר לנחש, שמשויך למשתמש וללקוח.

  4. הפניה חזרה אל Google:

    • מפנים את הדפדפן לכתובת ה-URL שמופיעה ב-redirect_uri.
    • מוסיפים את הפרמטרים הבאים בפרגמנט URL (hash):
      • ‫access_token: אסימון הגישה שיצרתם.
      • token_type: צריך להיות bearer.
      • ‫state: ערך הסטטוס שלא שונה שהתקבל מ-Google.
טיפול בבקשות למידע על משתמשים

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

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

כותרות של בקשות של נקודות קצה של userinfo
Authorization header אסימון הגישה מסוג נושא.

לדוגמה, אם נקודת הקצה של Userinfo זמינה https://myservice.example.com/userinfo, בקשה עשויה להיראות כך:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

כדי שנקודת הקצה של userinfo תטפל בבקשות, מבצעים את השלבים הבאים:

  1. מחלצים את אסימון הגישה מהכותרת Authorization ומחזירים מידע עבור המשתמש שמשויך לאסימון הגישה.
  2. אם אסימון הגישה לא חוקי, צריך להחזיר שגיאה מסוג HTTP 401 מאושר עם שימוש בכותרת התגובה WWW-Authenticate. דוגמה לתגובה עם שגיאה של userinfo: 
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    אם מתקבלת תגובה מסוג '401' ללא הרשאה, או כל תגובה אחרת של שגיאה שנכשלה במהלך תהליך הקישור, לא ניתן לשחזר את השגיאה, האסימון שאוחזר יימחק והמשתמש יצטרך להתחיל מחדש את תהליך הקישור.

  3. אם אסימון הגישה תקין, מוחזר ותגובת HTTP 200 עם אובייקט ה-JSON הבא בגוף ה-HTTPS תגובה: 

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
     אם נקודת הקצה (endpoint) של userinfo מחזירה תגובה מוצלחת מסוג HTTP 200, האסימון שאוחזר וההצהרות על זכויות יוצרים יירשמו בחשבון Google של המשתמש.

    תגובה של נקודת הקצה של userinfo
    sub מזהה ייחודי שמזהה את המשתמש במערכת שלכם.
    email כתובת האימייל של המשתמש.
    given_name אופציונלי: השם הפרטי של המשתמש.
    family_name אופציונלי: שם המשפחה של המשתמש.
    name אופציונלי: השם המלא של המשתמש.
    picture אופציונלי: תמונת פרופיל של המשתמש.