קישור חשבון Google באמצעות OAuth

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

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

סשן של הרשאה באמצעות קוד ב-OAuth 2.0 שהופעל על ידי Google מתנהל באופן הבא:

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

מתכון להטמעה

כדי להטמיע את תהליך אישור הגישה באמצעות קוד הרשאה, פועלים לפי השלבים הבאים.

שלב 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 הוא code.

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

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

3. יצירת קוד הרשאה:

   • יצירת קוד הרשאה ייחודי שאי אפשר לנחש אותו, שמשויך למשתמש וללקוח.
   • מגדירים את תוקף הקוד ל-10 דקות בערך.

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

   • מפנים את הדפדפן לכתובת ה-URL שמופיעה ב-redirect_uri.
   • הוספת פרמטרים לשאילתה:
     • ‫code: קוד ההרשאה שיצרתם.
     • ‫state: ערך הסטטוס שלא שונה שהתקבל מ-Google.

שלב 2: טיפול בבקשות להחלפת טוקנים

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

א. המרת קודי הרשאה לאסימונים

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

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

   • מאמתים את client_id ואת client_secret.
   • מוודאים שקוד ההרשאה תקין ושלא פג התוקף שלו.
   • מוודאים שהערך redirect_uri זהה לערך שבו השתמשתם בשלב 1.
   • אם האימות נכשל, מחזירים HTTP 400 Bad Request עם {"error": "invalid_grant"}.

2. הנפקת טוקנים:

   • יצירת refresh_token לטווח ארוך וaccess_token לטווח קצר (בדרך כלל לשעה).
   • החזרת HTTP 200 OK עם תגובת אסימון JSON רגילה.

ב. רענון טוקנים של גישה

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

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

   • מאמתים את client_id,‏ client_secret וrefresh_token.
   • אם האימות נכשל, מחזירים HTTP 400 Bad Request עם {"error": "invalid_grant"}.

2. הנפקת אסימון גישה חדש:

   • יוצרים access_token חדש לזמן קצר.
   • מחזירים קוד HTTP‏ 200 OK עם תגובת אסימון JSON (אפשר לכלול גם אסימון רענון חדש).

טיפול בבקשות למידע על משתמשים

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

• כניסה לחשבון המקושר באמצעות Google One Tap.
• מינוי פשוט וקל ב-AndroidTV.

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

לדוגמה, אם נקודת הקצה של 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	אופציונלי: תמונת פרופיל של המשתמש.

אימות ההטמעה

כדי לאמת את ההטמעה, אפשר להשתמש בכלי OAuth 2.0 Playground.

בכלי, מבצעים את השלבים הבאים:

1. לוחצים על Configuration (הגדרה) settings כדי לפתוח את חלון ההגדרה של OAuth 2.0.
2. בשדה OAuth flow (תהליך OAuth), בוחרים באפשרות Client-side (בצד הלקוח).
3. בשדה OAuth Endpoints (נקודות קצה של OAuth), בוחרים באפשרות Custom (מותאם אישית).
4. בשדות המתאימים, מציינים את נקודת הקצה של OAuth 2.0 ואת מזהה הלקוח שהקציתם ל-Google.
5. בקטע Step 1, לא בוחרים אף היקף של Google. במקום זאת, משאירים את השדה הזה ריק או מקלידים היקף הרשאות שתקף לשרת (או מחרוזת שרירותית אם לא משתמשים בהיקפי הרשאות OAuth). בסיום, לוחצים על הרשאת ממשקי API.
6. בקטעים שלב 2 ושלב 3, עוברים על תהליך ההרשאה באמצעות OAuth 2.0 ומוודאים שכל שלב פועל כמו שצריך.

כדי לאמת את ההטמעה, אפשר להשתמש בכלי Google Account Linking Demo.

בכלי, מבצעים את השלבים הבאים:

1. לוחצים על הכפתור כניסה באמצעות חשבון Google.
2. בוחרים את החשבון שרוצים לקשר.
3. מזינים את מזהה השירות.
4. אפשר להזין היקף אחד או יותר שרוצים לבקש גישה אליהם.
5. לוחצים על התחלת ההדגמה.
6. כשמופיעה הבקשה, מאשרים שרוצים להסכים לבקשת הקישור או לדחות אותה.
7. מוודאים שמופנים לפלטפורמה שלכם.