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

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

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

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

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

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

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

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

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

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

הנחיות עיצוב

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

איור שמראה את השלבים שמשתמש צריך לבצע כדי לקשר את חשבון Google שלו למערכת האימות שלכם. צילום המסך הראשון מציג קישור שמתחיל בפלטפורמה שלכם. בתמונה השנייה מוצגת כניסת משתמש ל-Google, ובתמונה השלישית מוצגים הסכמת המשתמש ואישור הקישור של חשבון Google שלו לאפליקציה שלכם. בצילום המסך האחרון מוצג חשבון משתמש שקשור בהצלחה באפליקציית Google.
איור 1. קישור החשבון מאפשר למשתמשים להיכנס ל-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, אפשר לעיין במאמר בנושא לוגו וסימנים מסחריים.

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

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

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

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

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

תהליך קישור חשבון 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

n

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

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

קישור של חשבון Google: תהליך מרומז של OAuth

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

משתמש אפליקציית Google / דפדפן נקודת הקצה של האימות ‫1. המשתמש יוזם את הקישור 2. הפניה לנקודת הקצה של אימות (GET) client_id, redirect_uri, state, scope 3. הצגת מסך הכניסה ומסך בקשת ההסכמה 4. המשתמש מאמת את עצמו ומעניק הסכמה 5. הפניה חזרה אל Google עם טוקן (GET) access_token, state 6. שמירת טוקנים של משתמשים בחנות 7. גישה למשאבים של משתמשים
איור 1. רצף האירועים בזרם הענקת גישה משתמע של OAuth 2.0 לקישור של חשבון Google.

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

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

המשתמש / הרכיב תפקיד ב-GAL תחומי אחריות
אפליקציית Google / שרת לקוח OAuth מתחיל את התהליך, מקבל את אסימון הגישה באמצעות הפניה אוטומטית בדפדפן, ומאחסן אותו בצורה מאובטחת כדי לגשת לממשקי ה-API של השירות.
נקודת הקצה להרשאה שרת הרשאות השירות מאמת את המשתמשים, מקבל את ההסכמה שלהם ומנפיק אסימוני גישה לטווח ארוך ישירות ל-Google.
‫URI של הפניה לכתובת אחרת ב-Google נקודת קצה של קריאה חוזרת (callback) מקבל את ההפניה האוטומטית של המשתמש משירות ההרשאה עם הערכים access_token ו-state בקטע של כתובת ה-URL.

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

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

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

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

פרמטרים של נקודת קצה להרשאה
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 של ההפניה האוטומטית מסוג OAuth 2.0 של Google מקבל את טוקן הגישה ומאשר שהערך של state לא השתנה. אחרי ש-Google מקבלת אסימון גישה לשירות שלכם, היא מצרפת את האסימון לקריאות הבאות לממשקי ה-API של השירות.

Handle userinfo requests

The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:

After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.

userinfo endpoint request headers
Authorization header The access token of type Bearer.

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

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

For your userinfo endpoint to handle requests, do the following steps:

  1. Extract access token from the Authorization header and return information for the user associated with the access token.
  2. If the access token is invalid, return an HTTP 401 Unauthorized error with using the WWW-Authenticate Response Header. Below is an example of a userinfo error response: 
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.

  3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response: 

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
     If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

    userinfo endpoint response
    sub A unique ID that identifies the user in your system.
    email Email address of the user.
    given_name Optional: First name of the user.
    family_name Optional: Last name of the user.
    name Optional: Full name of the user.
    picture Optional: Profile picture of the user.

אימות ההטמעה

כדי לאמת את ההטמעה, אפשר להשתמש בכלי OAuth 2.0 Playground.

בכלי, מבצעים את השלבים הבאים:

  1. לוחצים על Configuration (הגדרה) כדי לפתוח את חלון ההגדרה של 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. מוודאים שמופנים לפלטפורמה שלכם.