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

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

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

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

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

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

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

  1. פותחים את הדף OAuth consent screen במסוף Google APIs.
  2. אם מתבקשים, בוחרים את הפרויקט שיצרתם.

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

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

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

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

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

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

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

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

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

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

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

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

אימות ההטמעה

אפשר לאמת את ההטמעה באמצעות הכלי 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. מוודאים שאתם מופנים מחדש לפלטפורמה שלכם.