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

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

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

בתהליך הרשאה באמצעות קוד, נדרשים שני נקודות קצה:

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

• נקודת הקצה החלפת אסימונים, שאחראית לשני סוגים של החלפות:

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

בחירת תהליך OAuth 2.0

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

הנחיות עיצוב

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

דרישות

1. עליך לציין שחשבון המשתמש יקושר ל-Google, לא למוצר ספציפי של Google, כמו Google Home או Google Assistant.

המלצות

מומלץ לבצע את הפעולות הבאות:

1. הצגת מדיניות הפרטיות של Google צריך לכלול קישור למדיניות הפרטיות של Google במסך ההסכמה.

2. נתונים לשיתוף. חשוב להשתמש בשפה ברורה ותמציתית כדי להסביר למשתמשים אילו נתונים Google צריכה מהם ולמה.

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

4. אפשרות לבטל צריך לספק למשתמשים אפשרות לחזור אחורה או לבטל, אם הם בוחרים לא לקשר.

5. תהליך כניסה נקי. חשוב לוודא שלמשתמשים יש שיטה ברורה לכניסה לחשבון Google, כמו שדות של שם המשתמש והסיסמה או כניסה באמצעות חשבון Google.

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

7. יכולת לשנות את חשבון המשתמש כדאי להציע למשתמשים שיטה להחלפת החשבונות. האפשרות הזו שימושית במיוחד אם למשתמשים יש כמה חשבונות.

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

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

יצירת הפרויקט

כדי ליצור את הפרויקט לשימוש בקישור לחשבון:

2. לוחצים על יצירת פרויקט.
3. מזינים שם או מאשרים את ההצעה שנוצרה.
4. מאשרים או עורכים את השדות שנותרו.
5. לוחצים על יצירה.

כדי לראות את מזהה הפרויקט:

2. מחפשים את הפרויקט בטבלה בדף הנחיתה. מזהה הפרויקט מופיע בעמודה ID.

הגדרת מסך ההסכמה של OAuth

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

1. פותחים את הדף מסך ההסכמה ל-OAuth ב-Google APIs Console.
2. אם מתבקשים, בוחרים את הפרויקט שיצרתם.

3. בדף 'מסך הסכמה ל-OAuth', ממלאים את הטופס ולוחצים על הלחצן 'שמירה'.

   שם האפליקציה: שם האפליקציה שמבקשת הסכמה. השם צריך לשקף במדויק את האפליקציה שלכם ולהיות זהה לשם האפליקציה שמוצג למשתמשים במקומות אחרים. שם האפליקציה יוצג במסך ההסכמה לקישור החשבון.

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

   כתובת אימייל לתמיכה: כדי שהמשתמשים יוכלו ליצור איתכם קשר עם שאלות לגבי הסכמתם.

   היקפים של ממשקי Google API: היקפים מאפשרים לאפליקציה שלכם לגשת לנתונים פרטיים של המשתמשים ב-Google. במקרה השימוש של קישור חשבון Google, היקף ברירת המחדל (אימייל, פרופיל, openid) מספיק, ואין צורך להוסיף היקפים רגישים. בדרך כלל מומלץ לבקש היקפי הרשאה באופן מצטבר, בזמן שנדרשת גישה, ולא מראש. מידע נוסף

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

   קישור לדף הבית של האפליקציה: דף הבית של האפליקציה. הן חייבות להתארח בדומיין מורשה.

   קישור למדיניות הפרטיות של האפליקציה: מוצג במסך ההסכמה לקישור חשבון Google. הן חייבות להתארח בדומיין מורשה.

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

   

   איור 1. מסך הסכמה לקישור חשבון Google לאפליקציה פיקטיבית, Tunery

4. בודקים את 'סטטוס האימות'. אם האפליקציה שלכם צריכה אימות, לוחצים על הלחצן 'שליחה לאימות' כדי לשלוח את האפליקציה לאימות. פרטים נוספים זמינים במאמר בנושא דרישות האימות של OAuth.

הטמעת שרת OAuth

To support the OAuth 2.0 implicit flow, your service makes an authorization endpoint available by HTTPS. This endpoint is responsible for authentication and obtaining consent from users for data access. The authorization endpoint presents a sign-in UI to your users that aren't already signed in and records consent to the requested access.

When a Google application needs to call one of your service's authorized APIs, Google uses this endpoint to get permission from your users to call these APIs on their behalf.

A typical OAuth 2.0 implicit flow session initiated by Google has the following flow:

1. Google opens your authorization endpoint in the user's browser. The user signs in, if not signed in already, and grants Google permission to access their data with your API, if they haven't already granted permission.
2. Your service creates an access token and returns it to Google. To do so, redirect the user's browser back to Google with the access token attached to the request.
3. Google calls your service's APIs and attaches the access token with each request. Your service verifies that the access token grants Google authorization to access the API and then completes the API call.

Handle authorization requests

When a Google application needs to perform account linking via an OAuth 2.0 implicit flow, Google sends the user to your authorization endpoint with a request that includes the following parameters:

For example, if your authorization endpoint is available at https://myservice.example.com/auth, a request might look like the following:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

For your authorization endpoint to handle sign-in requests, do the following steps:

1. Verify the client_id and redirect_uri values to prevent granting access to unintended or misconfigured client apps:

   • Confirm that the client_id matches the client ID you assigned to Google.
   • Confirm that the URL specified by the redirect_uri parameter has the following form:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
     https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
     

2. Check if the user is signed in to your service. If the user isn't signed in, complete your service's sign-in or sign-up flow.

3. Generate an access token for Google to use to access your API. The access token can be any string value, but it must uniquely represent the user and the client the token is for and must not be guessable.

4. Send an HTTP response that redirects the user's browser to the URL specified by the redirect_uri parameter. Include all of the following parameters in the URL fragment:

   • access_token: The access token you just generated
   • token_type: The string bearer
   • state: The unmodified state value from the original request

   The following is an example of the resulting URL:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Google's OAuth 2.0 redirect handler receives the access token and confirms that the state value hasn't changed. After Google has obtained an access token for your service, Google attaches the token to subsequent calls to your service APIs.

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

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

אימות ההטמעה

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

In the tool, do the following steps:

1. Click Configuration settings 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.