קישור יעיל באמצעות 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,‏ create ו-get.

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

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

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

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

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

מתכון להטמעה

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

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

Check for an existing user account (check intent)

Google calls your token exchange endpoint to verify if the Google user exists in your system. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the check intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type (must be urn:ietf:params:oauth:grant-type:jwt-bearer).
   • Validate the assertion (JWT) using the criteria in JWT Validation.

2. Lookup user:

   • Check if the Google Account ID (sub) or email address in the JWT matches a user in your database.

3. Respond:

   • If found: Return HTTP 200 OK with {"account_found": "true"}.
   • If not found: Return HTTP 404 Not Found with {"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 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 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 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 מורשים.

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

   הערה: דוגמה ל-Client-ID:

   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.