קישור יעיל עם OAuth וכניסה באמצעות חשבון Google

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

סקירה כללית

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

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

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

איור 1. קישור חשבונות בטלפון של משתמש עם קישור בעיצוב נקי

דרישות לקישור פשוט

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

נקודת הקצה של החלפת אסימונים חייבת לתמוך באובייקטים של check, create ו-get. השלבים הבאים מציגים את השלבים שהושלמו בתהליך קישור החשבון, ומציינים מתי קריאות שונות לכוונות:

  1. האם למשתמש יש חשבון במערכת האימות שלך? (המשתמש מחליט: 'כן' או 'לא')
    1. כן : האם המשתמש משתמש בכתובת האימייל המשויכת לחשבון Google שלו כדי להיכנס לפלטפורמה? (המשתמש מחליט: 'כן' או 'לא')
      1. כן : האם למשתמש יש חשבון תואם במערכת האימות שלך? (check intent יתקשר כדי לאשר)
        1. כן: התקבלה שיחה אל get intent והחשבון יקושר אם בקשת ההחזרה תגיע בהצלחה.
        2. לא : ליצור חשבון חדש? (המשתמש מחליט: 'כן' או 'לא')
          1. כן : התקבלה שיחה מ-create intent, והחשבון יקושר אם כוונת הרכישה תשוחזר.
          2. לא : תהליך ה-OAuth באינטרנט מופעל, המשתמש מופנה לדפדפן שלו, והמשתמש מקבל אפשרות לקשר עם כתובת אימייל אחרת.
      2. לא : זרימת ה-OAuth מופעלת, המשתמש מופנה לדפדפן, והמשתמש מקבל אפשרות לקשר עם כתובת אימייל אחרת.
    2. לא : האם למשתמש יש חשבון תואם במערכת האימות שלך? (check intent יתקשר כדי לאשר)
      1. כן : התקבלה שיחה אל get intent והחשבון יקושר אם בקשת ההחזרה תגיע בהצלחה.
      2. לא : בוצעה קריאה ל-create intent והחשבון מקושר אם כוונת הרכישה חוזרת בהצלחה.

חיפוש חשבון משתמש קיים (בדיקת כוונת רכישה)

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

אם חשבון Google המתאים כבר קיים במערכת האימות, נקודת הקצה של אסימון האסימון מגיבה ל-account_found=true. אם חשבון Google לא תואם למשתמש קיים, נקודת הקצה של החלפת האסימון מחזירה שגיאת HTTP 404 לא נמצא עם account_found=false.

הבקשה כוללת את הטופס הבא:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

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

פרמטרים של נקודת קצה לאסימון
intent עבור הבקשות האלה, הערך של הפרמטר הזה הוא check.
grant_type סוג האסימון שיוחלף. לבקשות האלה, הפרמטר הזה כולל את הערך urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion אסימון Web JSON (JWT) המספק הצהרה חתומה של זהות המשתמש של Google. ה-JWT מכיל מידע שכולל את מזהה החשבון, השם וכתובת האימייל של המשתמש ב-Google.
client_id מספר הלקוח שהקצית ל-Google.
client_secret סוד הלקוח שהקצית ל-Google.

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

  • אימות ופענוח של הצהרת JWT.
  • בודקים אם חשבון Google כבר קיים במערכת האימות.
אמת ותפענח את קביעת JWT

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

כאשר מפוענח, קביעת JWT נראית כמו הדוגמה הבאה:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

בנוסף לאימות חתימת האסימון, וודא שמנפיק הטענה (שדה ה- iss ) הוא https://accounts.google.com , שהקהל (שדה aud ) הוא מספר הלקוח שהוקצה לך ושהאסימון לא פג ( exp שדה).

באמצעות שדות email , email_verified email ו- hd תוכלו לקבוע אם גוגל מארחת וסמכותית לכתובת דוא"ל. במקרים בהם גוגל סמכותית ידוע כי המשתמש הוא כיום בעל החשבון הלגיטימי ואתה יכול לדלג על סיסמה או על שיטות אתגרים אחרות. אחרת, ניתן להשתמש בשיטות אלה לאימות החשבון לפני הקישור.

מקרים בהם Google סמכותית:

  • email יש סיומת @gmail.com , זהו חשבון Gmail.
  • email_verified נכון ו- hd מוגדר, זהו חשבון G Suite.

משתמשים רשומים להירשם לחשבונות Google מבלי להשתמש ב- Gmail או ב- G Suite. כאשר email אינו מכיל סיומת @gmail.com ו- hd נעדר Google אינה סמכותית ומומלצות לסיסמה או לשיטות אתגר אחרות לאימות המשתמש. email_verfied יכול להיות נכון גם מכיוון שגוגל אימתה בתחילה את המשתמש בעת שנוצר חשבון Google, אולם הבעלות על חשבון הדוא"ל של צד שלישי עשויה להשתנות מאז.

בדיקה אם חשבון Google כבר קיים במערכת האימות

בודקים אם אחד מהתנאים הבאים מתקיים:

  • מספר חשבון Google נמצא בשדה sub'
  • כתובת האימייל שבביטוי תואמת למשתמש במסד הנתונים של המשתמש.

אם אחד מהתנאים מתקיים, המשתמש כבר נרשם. במקרה כזה, יש להחזיר תגובה כמו:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

אם מזהה חשבון Google וכתובת האימייל שצוינו בהצהרה אינם תואמים למשתמש במסד הנתונים שלך, המשתמש עדיין לא נרשם. במקרה כזה, נקודת הקצה של החלפת האסימון צריכה להגיב עם שגיאת HTTP 404 שמציינת את "account_found": "false", כמו בדוגמה הבאה:

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}

Handle automatic linking (get intent)

After the user gives consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.

If the corresponding Google Account is already present in your authentication system, your token exchange endpoint returns a token for the user. If the Google Account doesn't match an existing user, your token exchange endpoint returns a linking_error error and optional login_hint.

The request has the following form:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

Your token exchange endpoint must be able to handle the following parameters:

Token endpoint parameters
intent For these requests, the value of this parameter is get.
grant_type The type of token being exchanged. For these requests, this parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.
scope Optional: Any scopes that you've configured Google to request from users.
client_id The client ID you assigned to Google.
client_secret The client secret you assigned to Google.

To respond to the get intent requests, your token exchange endpoint must perform the following steps:

  • Validate and decode the JWT assertion.
  • Check if the Google account is already present in your authentication system.
אמת ותפענח את קביעת JWT

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

כאשר מפוענח, קביעת JWT נראית כמו הדוגמה הבאה:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

בנוסף לאימות חתימת האסימון, וודא שמנפיק הטענה (שדה ה- iss ) הוא https://accounts.google.com , שהקהל (שדה aud ) הוא מספר הלקוח שהוקצה לך ושהאסימון לא פג ( exp שדה).

באמצעות שדות email , email_verified email ו- hd תוכלו לקבוע אם גוגל מארחת וסמכותית לכתובת דוא"ל. במקרים בהם גוגל סמכותית ידוע כי המשתמש הוא כיום בעל החשבון הלגיטימי ואתה יכול לדלג על סיסמה או על שיטות אתגרים אחרות. אחרת, ניתן להשתמש בשיטות אלה לאימות החשבון לפני הקישור.

מקרים בהם Google סמכותית:

  • email יש סיומת @gmail.com , זהו חשבון Gmail.
  • email_verified נכון ו- hd מוגדר, זהו חשבון G Suite.

משתמשים רשומים להירשם לחשבונות Google מבלי להשתמש ב- Gmail או ב- G Suite. כאשר email אינו מכיל סיומת @gmail.com ו- hd נעדר Google אינה סמכותית ומומלצות לסיסמה או לשיטות אתגר אחרות לאימות המשתמש. email_verfied יכול להיות נכון גם מכיוון שגוגל אימתה בתחילה את המשתמש בעת שנוצר חשבון Google, אולם הבעלות על חשבון הדוא"ל של צד שלישי עשויה להשתנות מאז.

Check if the Google account is already present in your authentication system

Check whether either of the following conditions are true:

  • The Google Account ID, found in the assertion's sub field, is in your user database.
  • The email address in the assertion matches a user in your user database.

If an account is found for the user, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "refresh_token": "REFRESH_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

In some cases, account linking based on ID token might fail for the user. If it does so for any reason, your token exchange endpoint needs to reply with a HTTP 401 error that specifies error=linking_error, as the following example shows:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

When Google receives a 401 error response with linking_error, Google sends the user to your authorization endpoint with login_hint as a parameter. The user completes account linking using the OAuth linking flow in their browser.

ניהול יצירת החשבון באמצעות כניסה באמצעות חשבון Google (יצירת כוונה)

כאשר משתמש צריך ליצור חשבון בשירות שלך, Google שולחת בקשה לנקודת הקצה של החלפת אסימונים המציינת את intent=create.

הבקשה כוללת את הטופס הבא:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

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

פרמטרים של נקודת קצה לאסימון
intent עבור הבקשות האלה, ערך הפרמטר הזה הוא create.
grant_type סוג האסימון שיוחלף. לבקשות האלה, הפרמטר הזה כולל את הערך urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion אסימון Web JSON (JWT) המספק הצהרה חתומה של זהות המשתמש של Google. ה-JWT מכיל מידע שכולל את מזהה החשבון, השם וכתובת האימייל של המשתמש ב-Google.
client_id מספר הלקוח שהקצית ל-Google.
client_secret סוד הלקוח שהקצית ל-Google.

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

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

  • אימות ופענוח של הצהרת JWT.
  • לאמת את פרטי המשתמש וליצור חשבון חדש.
אמת ותפענח את קביעת JWT

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

כאשר מפוענח, קביעת JWT נראית כמו הדוגמה הבאה:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

בנוסף לאימות חתימת האסימון, וודא שמנפיק הטענה (שדה ה- iss ) הוא https://accounts.google.com , שהקהל (שדה aud ) הוא מספר הלקוח שהוקצה לך ושהאסימון לא פג ( exp שדה).

באמצעות שדות email , email_verified email ו- hd תוכלו לקבוע אם גוגל מארחת וסמכותית לכתובת דוא"ל. במקרים בהם גוגל סמכותית ידוע כי המשתמש הוא כיום בעל החשבון הלגיטימי ואתה יכול לדלג על סיסמה או על שיטות אתגרים אחרות. אחרת, ניתן להשתמש בשיטות אלה לאימות החשבון לפני הקישור.

מקרים בהם Google סמכותית:

  • email יש סיומת @gmail.com , זהו חשבון Gmail.
  • email_verified נכון ו- hd מוגדר, זהו חשבון G Suite.

משתמשים רשומים להירשם לחשבונות Google מבלי להשתמש ב- Gmail או ב- G Suite. כאשר email אינו מכיל סיומת @gmail.com ו- hd נעדר Google אינה סמכותית ומומלצות לסיסמה או לשיטות אתגר אחרות לאימות המשתמש. email_verfied יכול להיות נכון גם מכיוון שגוגל אימתה בתחילה את המשתמש בעת שנוצר חשבון Google, אולם הבעלות על חשבון הדוא"ל של צד שלישי עשויה להשתנות מאז.

אימות פרטי משתמש ויצירת חשבון חדש

בודקים אם אחד מהתנאים הבאים מתקיים:

  • מספר חשבון Google נמצא בשדה sub'
  • כתובת האימייל שבביטוי תואמת למשתמש במסד הנתונים של המשתמש.

אם אחד מהתנאים מתקיים, מבקשים מהמשתמש לקשר את החשבון הקיים לחשבון Google שלו. לשם כך, יש להגיב לבקשה עם שגיאת HTTP 401 המציינת את error=linking_error ומספקת את כתובת האימייל של המשתמש כ-login_hint. לפניכם תשובה לדוגמה:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

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

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

בסיום היצירה, יש להנפיק אסימון גישה ולרענן אסימון ולהחזיר את הערכים באובייקט JSON בגוף תגובת ה-HTTPS, כמו בדוגמה הבאה:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "refresh_token": "REFRESH_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

קבלת מספר הלקוח של Google API

תצטרכו לספק את מספר הלקוח שלכם ב-Google API בתהליך ההרשמה לקישור.

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

  1. פותחים את הדף פרטי הכניסה במסוף Google API.
  2. יוצרים או בוחרים פרויקט ב-Google APIs.

    אם לפרויקט שלך אין Client-ID לסוג אפליקציית האינטרנט, לוחצים על יצירת פרטי כניסה ו-gt; מזהה לקוח ב-OAuth כדי ליצור מזהה. הקפידו לכלול את הדומיין של האתר שלכם בתיבה מקורות JavaScript מורשים. כשמבצעים בדיקות או פיתוח מקומיים, צריך להוסיף את http://localhost וגם את http://localhost:<port_number> לשדה מקורות JavaScript מורשים.

אימות ההטמעה

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