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

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

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

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

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

אחזור של מזהה לקוח וסוד לקוח

כדי לשלוח בקשות לנקודות הקצה (endpoint) של הכניסה לאפליקציה, נדרשים מזהה לקוח מסוג OAuth 2.0 וסוד לקוח.

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

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

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

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

אחרי שמשתמש מבקש להיכנס באמצעות חשבון Google, שולחים בקשת POST ב-HTTP לנקודת הקצה של המכשיר ב-OAuth 2.0‏, https://oauth2.googleapis.com/device/code, כדי לקבל קוד משתמש וכתובת URL לאימות. יש לכלול בבקשה את מזהה הלקוח ואת רשימת ההיקפים הנדרשים. אם אתם רוצים רק לאפשר למשתמשים להיכנס באמצעות חשבונות 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 מסך הסכמה שנראה כך:

אם המשתמש לוחץ על אישור, האפליקציה יכולה לקבל אסימון מזהה כדי לזהות את המשתמש, אסימון גישה כדי לבצע קריאות ל-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..."
}

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

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

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

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

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"];

מידע נוסף

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