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

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

‫OAuth 2.1 ו-PKCE לסוכנים

מומלץ לאכוף את OAuth 2.1 עבור סוכני AI חסרי מצב ופייפליינים מולטי-מודאליים.

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

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

בתהליך המשתמע, 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

אימות ההטמעה

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