קישור יעיל באמצעות OAuth וכניסה באמצעות חשבון Google

סקירה כללית

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

כדי לבצע קישור חשבונות באמצעות OAuth וכניסה באמצעות חשבון Google, פועלים לפי השלבים הכלליים הבאים:

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

איור 1. קישור חשבון בטלפון של משתמש באמצעות קישור פשוט

קישור יעיל: OAuth + תהליך כניסה באמצעות חשבון Google

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

.

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

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

המשתמש / הרכיב	תפקיד ב-GAL	תחומי אחריות
אפליקציית Google / שרת	לקוח OAuth	מקבל את הסכמת המשתמש לכניסה באמצעות חשבון Google, מעביר הצהרות זהות (JWT) לשרת שלכם ושומר בצורה מאובטחת את הטוקנים שמתקבלים.
נקודת הקצה של חילופי הטוקנים	ספק זהויות / שרת הרשאות	מאמת את הצהרות הזהות, בודק אם יש חשבונות קיימים, מטפל בכוונה הנדרשת לקישור חשבונות (check, get) ובכוונה האופציונלית create, ומנפיק טוקנים על סמך הכוונות המבוקשות.
Your Service API	שרת משאבים	מאפשר גישה לנתוני משתמש כשמוצג אסימון גישה תקין.

הדרישות לקישור פשוט

• מטמיעים את תהליך הקישור הבסיסי באמצעות OAuth. השירות שלכם צריך לתמוך בנקודות קצה של הרשאה והחלפת אסימונים שתואמות ל-OAuth 2.0.
• נקודת הקצה של החלפת האסימונים חייבת לתמוך בהצהרות של JSON Web Token ‏ (JWT) וליישם את הכוונות הנדרשות check ו-get, ואופציונלית את הכוונה create.

• רושמים את מזהה הלקוח ב-Google API.

לוגיקת ההחלטה לקישור פשוט

הלוגיקה הבאה קובעת איך מתבצעת קריאה לכוונות במהלך תהליך הקישור הפשוט:

1. האם למשתמש יש חשבון במערכת האימות שלכם? (המשתמש מחליט אם לבחור באפשרות YES או NO)
   1. YES : האם המשתמש משתמש בכתובת האימייל שמשויכת לחשבון Google שלו כדי להיכנס לפלטפורמה שלך? (המשתמש מחליט אם לבחור באפשרות 'כן' או 'לא')
      1. כן : האם למשתמש יש חשבון תואם במערכת האימות שלכם? (מתבצעת שיחה עם check intent כדי לאשר)
         1. כן : מתבצעת קריאה לget intent והחשבון מקושר אם הפונקציה get intent מחזירה ערך בהצלחה.
         2. לא : ליצור חשבון חדש? (המשתמש מחליט אם ליצור חשבון על ידי בחירה באפשרות 'כן' או 'לא'; רלוונטי רק אם השירות תומך ביצירת חשבון)
            1. כן : מתבצעת קריאה אל create intent והחשבון מקושר אם הפעולה create intent מסתיימת בהצלחה.
            2. לא : מופעל תהליך הקישור באמצעות OAuth, המשתמש מועבר לדפדפן שלו ומוצגת לו האפשרות לקשר חשבון עם כתובת אימייל אחרת.
      2. לא : מופעל תהליך הקישור באמצעות OAuth, המשתמש מועבר לדפדפן ומוצגת לו האפשרות לקשר כתובת אימייל אחרת.
   2. לא : האם למשתמש יש חשבון תואם במערכת האימות שלך? (מתבצעת שיחה עם check intent כדי לאשר)
      1. כן : מתבצעת קריאה אל get intent והחשבון מקושר אם הפונקציה get intent מחזירה ערך בהצלחה.
      2. לא : אם השירות תומך ביצירת חשבון, מתבצעת קריאה אל create הכוונה והחשבון מקושר אם הכוונה ליצירת חשבון מוחזרת בהצלחה. אם יצירת חשבון לא נתמכת, נקודת הקצה צריכה להחזיר שגיאת קישור HTTP 401 כדי להפעיל את תהליך הקישור החלופי של OAuth.

מתכון להטמעה

נקודת הקצה של החלפת הטוקנים צריכה להטמיע את כוונות check ו-get הנדרשות, ואם רוצים לתמוך בקישור פשוט, גם את כוונת create.

כדי לטפל בכוונה שונה:

בדיקה אם קיים חשבון משתמש (בדיקת כוונות)

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

מתכון להטמעה

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

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

   • אימות של client_id,‏ client_secret ו-grant_type (חובה urn:ietf:params:oauth:grant-type:jwt-bearer).
   • מאמתים את assertion (JWT) לפי הקריטריונים שמפורטים במאמר אימות JWT.

2. חיפוש משתמש:

   • בודקים אם מזהה חשבון Google ‏ (sub) או כתובת האימייל ב-JWT תואמים למשתמש במסד הנתונים.

3. שליחת תשובה:

   • אם נמצא: מחזירים HTTP 200 OK עם {"account_found": "true"}.
   • אם לא נמצא: מחזירים HTTP 404 Not Found עם {"account_found": "false"}.

Handle automatic linking (get intent)

If the account exists, Google calls your endpoint with intent=get to retrieve tokens. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the required get intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Lookup user:

   • Verify the user exists using the sub or email claim.

3. Respond:

   • If successful: Generate and return access_token, refresh_token, and expires_in in a JSON response (HTTP 200 OK).
   • If linking fails: Return HTTP 401 Unauthorized with {"error": "linking_error"} and an optional login_hint to fall back to standard OAuth linking.

Handle account creation using Sign in with Google (create intent)

If your service supports account creation and no account exists, Google calls your endpoint with intent=create to create a new user. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the optional create intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Verify user does not exist:

   • Check if the sub or email is already in your database.
   • If the user does exist: Return HTTP 401 Unauthorized with {"error": "linking_error", "login_hint": "USER_EMAIL"} to force fallback to OAuth linking.

3. Create account:

   • Use the sub, email, name, and picture claims from the JWT to create a new user record.

4. Respond:

   • Generate and return tokens in a JSON response (HTTP 200 OK).

איך מקבלים את מזהה הלקוח ב-Google API

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

1. עוברים אל דף הלקוחות.

2. יוצרים פרויקט ב-Google APIs או בוחרים פרויקט קיים.

   אם בפרויקט שלכם אין מזהה לקוח מסוג אפליקציית אינטרנט, לוחצים על יצירת לקוח כדי ליצור אחד. חשוב להוסיף את הדומיין של האתר לתיבה מקורות מורשים של JavaScript. כשמבצעים בדיקות מקומיות או פיתוח, צריך להוסיף את http://localhost ואת http://localhost:<port_number> לשדה מקורות JavaScript מורשים.

אימות ההטמעה

כדי לאמת את ההטמעה, אפשר להשתמש בכלי 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. מוודאים שמופנים לפלטפורמה שלכם.