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

סקירה כללית

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

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

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

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

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

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

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

איור 2. רצף האירועים בתהליך הקישור המשופר

.

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

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

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

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

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

הערה: צריך להטמיע את הכוונות האלה באותו נקודת קצה של החלפת טוקנים שיצרתם לתהליך הקישור הבסיסי באמצעות OAuth. אל תיצרו נקודת קצה אחרת לטיפול בכוונות האלה.

• רושמים את מזהה הלקוח ב-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"}.

טיפול בקישור אוטומטי (קבלת כוונת המשתמש)

אם החשבון קיים, Google מתקשרת לנקודת הקצה עם intent=get כדי לאחזר טוקנים. פרטים על הפרמטרים זמינים במאמר קישור יעיל של כוונות.

מתכון להטמעה

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

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

   • מאמתים את client_id,‏ client_secret וgrant_type.
   • מאמתים את assertion (JWT).

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

   • מוודאים שהמשתמש קיים באמצעות הטענה sub או email.

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

   • אם הפעולה הצליחה: ייווצר ויוחזר access_token, refresh_token ו-expires_in בתגובת JSON (HTTP 200 OK).
   • אם הקישור נכשל: מחזירים HTTP 401 Unauthorized עם {"error": "linking_error"} ואפשרות להוסיף login_hint כדי לחזור לקישור OAuth רגיל.

טיפול ביצירת חשבון באמצעות "כניסה באמצעות חשבון Google" (יצירת כוונת משתמש)

הערה: התמיכה בכוונת המשתמש create היא אופציונלית. הכוונה הנדרשת לקישור פשוט היא check ו-get.

אם השירות תומך ביצירת חשבון ולא קיים חשבון, Google מתקשרת לנקודת הקצה עם intent=create כדי ליצור משתמש חדש. פרטים על הפרמטרים זמינים במאמר קישור יעיל של כוונות.

מתכון להטמעה

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

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

   • מאמתים את client_id,‏ client_secret וgrant_type.
   • מאמתים את assertion (JWT).

2. מוודאים שהמשתמש לא קיים:

   • בודקים אם sub או email כבר נמצאים במסד הנתונים.
   • אם המשתמש קיים: מחזירים HTTP 401 Unauthorized עם {"error": "linking_error", "login_hint": "USER_EMAIL"} כדי לאלץ חזרה לקישור OAuth.

3. יצירת חשבון:

   • משתמשים בהצהרות sub, email, name ו-picture מתוך ה-JWT כדי ליצור רשומה חדשה של משתמש.

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

   • יצירה והחזרה של טוקנים בתגובת JSON‏ (HTTP 200 OK).

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

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

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

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

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

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

   הערה: מזהה לקוח נראה כמו בדוגמה הבאה:

   1234567890-abc123def456.apps.googleusercontent.com
   

אימות ההטמעה

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

1. Click Configuration to open the OAuth 2.0 Configuration window.
2. In the OAuth flow field, select Client-side.
3. In the OAuth Endpoints field, select Custom.
4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

1. Click the Sign in with Google button.
2. Choose the account you'd like to link.
3. Enter the service ID.
4. Optionally enter one or more scopes that you will request access for.
5. Click Start Demo.
6. When prompted, confirm that you may consent and deny the linking request.
7. Confirm that you are redirected to your platform.