קישור חשבון Google עם OAuth

חשבונות מקושרים באמצעות תהליך המשתמע וקוד הרשאה רגיל של OAuth 2.0. השירות חייב לתמוך בנקודות קצה (endpoint) מסוג הרשאה ו-Token Exchange התואמות ל-OAuth 2.0.

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

בתהליך קוד ההרשאה צריך שתי נקודות קצה:

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

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

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

בחירת זרימת OAuth 2.0

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

הערה: יש להשתמש בלחצנים הבאים כדי לבחור את תהליך OAuth 2.0 שרוצים להטמיע. במידת הצורך, התוכן במדריך הזה ייטען מחדש בהתאם לבחירה שלכם.

תהליך מרומז קוד הרשאה

הנחיות עיצוב

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

איור 1. החשבון שמקשרים את המשתמשים נכנסים ל-Google ולמסכי ההסכמה.

דרישות

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

המלצות

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

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

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

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

4. יכולת לבטל. למשתמשים תהיה אפשרות לחזור אחורה או לבטל את המינוי אם הם יבחרו שלא לקשר.

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

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

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

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

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

איור 2. הנחיות העיצוב לגבי כניסה של משתמש למסכי Google

Create the project

Note: You can reuse an existing project and do not need to create a new project primarily for account linking.

To create your project to use account linking:

1. Go to the Google API Console.
2. לחץ על צור פרויקט .
3. הזן שם או קבל את ההצעה שנוצרה.
4. אשר או ערוך את כל השדות שנותרו.
5. לחץ על צור .

לצפייה במזהה הפרוייקט שלך:

1. Go to the Google API Console.
2. מצא את הפרוייקט שלך בטבלה בדף הנחיתה. מזהה הפרויקט מופיע בעמודה מזהה .

Configure your OAuth Consent Screen

The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.

1. Open the OAuth consent screen page of the Google APIs console.
2. If prompted, select the project you just created.

3. On the "OAuth consent screen" page, fill out the form and click the “Save” button.

   Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.

   Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings

   Support email: For users to contact you with questions about their consent.

   Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.

   Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.

   Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.

   Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.

   Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.

   

   Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery

4. Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.

הטמעה של שרת ה-OAuth

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

כאשר אפליקציה של Google צריכה לשלוח קריאה לאחד מממשקי ה-API המורשים של השירות שלכם: Google משתמשת בנקודת הקצה הזו כדי לקבל מהמשתמשים הרשאה לקרוא לממשקי ה-API האלה בשמם.

בסשן זרם הענקת גישה משתמע ב-OAuth 2.0 ש-Google יזמה, התהליך הבא:

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

טיפול בבקשות הרשאה

כשאפליקציה של Google צריכה לבצע קישור חשבונות דרך OAuth 2.0 זרם הענקת גישה משתמע, Google שולחת את המשתמש לנקודת הקצה (endpoint) של ההרשאה עם בקשה שכוללת את הפרמטרים הבאים:

פרמטרים של נקודת קצה להרשאה
client_id	מזהה הלקוח שהקצית ל-Google.
redirect_uri	כתובת ה-URL שאליה שולחים את התגובה לבקשה הזו.
state	ערך של ניהול חשבונות שמועבר אל Google ללא שינוי URI להפניה אוטומטית.
response_type	סוג הערך שיוחזר בתשובה. ל-OAuth 2.0 משתמע סוג התגובה הוא תמיד token.
user_locale	הגדרת השפה בחשבון Google בקטע RFC5646 שמשמש להתאמה לשוק המקומי של התוכן בשפה המועדפת על המשתמש.

לדוגמה, אם נקודת הקצה להרשאה זמינה ב- https://myservice.example.com/auth, בקשה עשויה להיראות כך:

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

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

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

   • צריך לוודא שה-client_id תואם למזהה הלקוח שהוקצו ל-Google.
   • מוודאים שכתובת ה-URL שצוינה ב-redirect_uri נראה כך:

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

2. לבדוק אם המשתמש נכנס לשירות. אם המשתמש לא חתום להשלים את תהליך הכניסה או ההרשמה לשירות.

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

4. לשלוח תגובת HTTP שמפנה מחדש את דפדפן המשתמש לכתובת ה-URL צוין על ידי הפרמטר redirect_uri. יש לכלול את כל את הפרמטרים הבאים בקטע של כתובת ה-URL:

   • access_token: אסימון הגישה שיצרתם כרגע
   • token_type: המחרוזת bearer
   • state: ערך המצב ללא שינוי מהמקור בקשה

   הדוגמה הבאה היא של כתובת ה-URL שתתקבל:

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

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

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

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

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

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

כותרות של בקשות של נקודות קצה של userinfo
Authorization header	אסימון הגישה מסוג נושא.

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

אימות ההטמעה

אתה יכול לאמת את הביצוע שלך באמצעות מגרש 2.0 OAuth הכלי.

בצע את הפעולות הבאות בכלי:

1. לחץ תצורת כדי לפתוח את חלון תצורת 2.0 OAuth.
2. בתחום זרימת OAuth, בחר בצד הלקוח.
3. בתחום נקודות קצה OAuth, בחר Custom.
4. ציין את נקודת הקצה של OAuth 2.0 ואת מזהה הלקוח שהקצית ל- Google בשדות המתאימים.
5. במקטע שלב 1, לא יבחר אף היקפי Google. במקום זאת, השאר שדה זה ריק או הקלד טווח תקף עבור השרת שלך (או מחרוזת שרירותית אם אינך משתמש בהיקפי OAuth). כשתסיים, לחץ על הרשה APIs.
6. בסעיפים שלב 2 ושלב 3, לעבור את זרימת 2.0 OAuth ולוודא כי כל צעד עובד כמתוכנן.

אתה יכול לאמת את הביצוע שלך באמצעות קישור הדגמת חשבון Google הכלי.

בצע את הפעולות הבאות בכלי:

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