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

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

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

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

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

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

    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, אפשר לעיין במאמר סמלי לוגו וסימנים מסחריים.

Create the project

To create your project to use account linking:

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 של השירותים שלכם.

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, בוחרים באפשרות צד הלקוח.
  3. בשדה נקודות קצה של OAuth, בוחרים באפשרות בהתאמה אישית.
  4. מציינים את נקודת הקצה (endpoint) של OAuth 2.0 ואת מזהה הלקוח שהקציתם ל-Google בשדות המתאימים.
  5. בקטע שלב 1, לא בוחרים היקפי גישה של Google. במקום זאת, צריך להשאיר את השדה הזה ריק או להקליד היקף תקין לשרת (או מחרוזת שרירותית אם לא משתמשים בהיקפים של OAuth). בסיום, לוחצים על Authorize API.
  6. בקטעים שלב 2 ושלב 3, מבצעים את התהליך OAuth 2.0 ומוודאים שכל שלב פועל כמו שצריך.

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

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

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