כניסה בטלוויזיות ובמכשירי קלט מוגבלים

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

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

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

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

קבלת מזהה לקוח וסוד לקוח

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

כדי לאתר את מזהה הלקוח וסוד הלקוח של הפרויקט, יש לבצע את הפעולות הבאות:

1. בוחרים פרטי כניסה קיימים ב-OAuth 2.0 או פותחים את הדף Credentials.
2. יוצרים את פרטי הכניסה ל-OAuth 2.0 לפרויקט, אם עוד לא עשיתם זאת. כדי לעשות זאת, לוחצים על Create credentials > OAuth client ID ומציינים את המידע הדרוש ליצירת פרטי הכניסה.
3. מחפשים את Client-ID בקטע OAuth 2.0 client ID (מזהי לקוח ב-OAuth 2.0). לפרטים, לוחצים על מזהה הלקוח.

אם יוצרים מזהה לקוח חדש, בוחרים את סוג האפליקציה טלוויזיות ומכשירי קלט מוגבלים.

קבלת קוד משתמש וכתובת URL לאימות

לאחר שמשתמש מבקש להיכנס באמצעות חשבון Google, אתם מקבלים קוד משתמש וכתובת URL לאימות על ידי שליחת בקשת HTTP POST לנקודת הקצה של המכשיר ב-OAuth 2.0, https://oauth2.googleapis.com/device/code. עליכם לכלול את מזהה הלקוח ורשימה של היקפי ההרשאות הנדרשים לבקשה. אם אתם רוצים להכניס משתמשים רק באמצעות חשבונות Google שלהם, אתם צריכים לבקש רק את ההיקפים profile ו-email. לחלופין, אם אתם רוצים לבקש הרשאה להפעיל API נתמך בשם משתמשים, תצטרכו לבקש את ההיקפים הנדרשים בנוסף להיקפים profile ו-email.

לפניכם בקשה לדוגמה לקוד משתמש:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_GOOGLE_CLIENT_ID&scope=email%20profile

באמצעות curl:

curl -d "client_id=YOUR_GOOGLE_CLIENT_ID&scope=email profile" https://oauth2.googleapis.com/device/code

התשובה תוחזר כאובייקט JSON:

 {
  "device_code" : "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code" : "GQVQ-JKEC",
  "verification_url" : "https://www.google.com/device",
  "expires_in" : 1800,
  "interval" : 5
}

האפליקציה מציגה למשתמש את הערכים user_code ו-verification_url, ובו-זמנית היא מבצעת סקר של נקודת הקצה לכניסה בכתובת interval שצוינה, עד שהמשתמש נכנס לחשבון או עד שהזמן שהוגדר ב-expires_in יחלוף.

הצגת קוד המשתמש וכתובת URL לאימות

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

הערכים של verification_url ושל user_code עשויים להשתנות. חשוב לעצב את ממשק המשתמש כך שיעמוד במגבלות הבאות:

• הערך של user_code צריך להיות בשדה רחב מספיק כדי להתמודד עם 15 תווים בגודל W.
• צריך להציג את verification_url בשדה רחב מספיק כדי לטפל במחרוזת של כתובת URL באורך של 40 תווים.

שתי המחרוזות יכולות להכיל כל תו שניתן להדפסה ממערכת התווים US-ASCII.

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

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

כשהמשתמש מנווט לכתובת ה-URL לאימות, הוא רואה דף שדומה לזה:

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

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

קבלת אסימון מזהה ואסימון רענון

לאחר שהאפליקציה תציג את קוד המשתמש ואת כתובת ה-URL לאימות, תוכלו להתחיל לדגום את נקודת הקצה של האסימון (https://oauth2.googleapis.com/token) באמצעות קוד המכשיר שקיבלתם מנקודת הקצה של המכשיר. תשאול את נקודת הקצה של האסימון במרווחי זמן, בשניות, כפי שמצוין בערך interval.

לפניכם בקשה לדוגמה:

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

client_id=YOUR_GOOGLE_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0

באמצעות curl:

curl -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0" https://oauth2.googleapis.com/token

אם המשתמש עדיין לא אישר את הבקשה, התגובה תהיה:

{
  "error" : "authorization_pending"
}

קצב החזרה על הבקשות האלה לא יחרוג מ-interval. אם האפליקציה מבצעת סקר מהר מדי, התגובה תהיה:

{
  "error" : "slow_down"
}

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

{
  "access_token": "ya29.AHES6ZSuY8f6WFLswSv0HZLP2J4cCvFSj-8GiZM0Pr6cgXU",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "1/551G1yXUqgkDGnkfFk6ZbjMMMDIMxo3JFc8lY8CAR-Q",
  "id_token": "eyJhbGciOiJSUzI..."
}

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

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

קבלת פרטי פרופיל משתמש מאסימון המזהה

תוכלו לקבל את פרטי הפרופיל של המשתמש המחובר על ידי פענוח אסימון המזהה באמצעות כל ספריית פענוח JWT. לדוגמה, באמצעות ספריית ה-JavaScript jwt-decode Auth0:

var user_profile = jwt_decode(<var>id_token</var>);

// The "sub" field is available on all ID tokens. This value is unique for each
// Google account and can be used to identify the user. (But do not send this
// value to your server; instead, send the whole ID token so its authenticity
// can be verified.)
var user_id = user_profile["sub"];

// These values are available when you request the "profile" and "email" scopes.
var user_email = user_profile["email"];
var email_verified = user_profile["email_verified"];
var user_name = user_profile["name"];
var user_photo_url = user_profile["picture"];
var user_given_name = user_profile["given_name"];
var user_family_name = user_profile["family_name"];
var user_locale = user_profile["locale"];

מידע נוסף

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