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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הפעלת זרימה מרומזת טיפוסית של OAuth 2.0 שיזמה Google כוללת את הזרימה הבאה:

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

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

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

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

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

    להלן דוגמא של האתר שמתקבל:

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

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

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

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

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

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

לדוגמה, אם שלך הסיום UserInfo זמין בכתובת https://myservice.example.com/userinfo , בקשה עשוי להיראות כך:

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

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

  1. חלץ אסימון גישה מכותרת ההרשאה והחזר מידע עבור המשתמש המשויך לאסימון הגישה.
  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",
}
    אם מחזיר הסיום UserInfo שלך לתגובה הצלחה HTTP 200, את לאחזר אסימון ותביעות רשומים נגד המשתמשים של גוגל חֶשְׁבּוֹן.

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