OAuth 2.0 לאפליקציות במכשירי טלוויזיה ומכשירים עם קלט מוגבל

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

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

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

חלופות

אם אתם כותבים אפליקציה לפלטפורמה כמו Android,‏ iOS,‏ macOS,‏ Linux או Windows (כולל Universal Windows Platform), שיש לה גישה לדפדפן וליכולות קלט מלאות, אתם יכולים להשתמש בתהליך OAuth 2.0 לאפליקציות לנייד ולמחשב. (כדאי להשתמש בתהליך הזה גם אם האפליקציה היא כלי של שורת פקודה ללא ממשק גרפי).

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

דרישות מוקדמות

הפעלת ממשקי API בפרויקט

בכל אפליקציה ששולחת קריאות ל-Google APIs צריך להפעיל את ממשקי ה-API האלה ב- API Console.

כדי להפעיל API בפרויקט:

1. ‫Open the API Library ב Google API Console.
2. If prompted, select a project, or create a new one.
3. בדף Library (ספרייה) אפשר למצוא ולהפעיל את YouTube Data API. מוצאים ממשקי API נוספים שהאפליקציה תשתמש בהם ומפעילים גם אותם.

יצירת פרטי כניסה להרשאה

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

1. Go to the Credentials page.
2. לוחצים על Create Client (יצירת לקוח).
3. בוחרים את סוג האפליקציה טלוויזיות והתקני קלט עם הגבלות.
4. נותנים שם ללקוח OAuth 2.0 ולוחצים על יצירה.

זיהוי היקפי גישה

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

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

ב-YouTube Data API גרסה 3 נעשה שימוש בהיקפי ההרשאות הבאים:

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

קבלת אסימוני גישה מסוג OAuth 2.0

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

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

התמונה הבאה ממחישה את התהליך הזה:

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

שלב 1: מבקשים קוד מכשיר וקוד משתמש

בשלב הזה, המכשיר שולח בקשת HTTP POST לשרת ההרשאות של Google, בכתובת https://oauth2.googleapis.com/device/code, שמזהה את האפליקציה ואת היקפי הגישה שהאפליקציה רוצה לגשת אליהם בשם המשתמש. צריך לאחזר את כתובת ה-URL הזו ממסמך הגילוי באמצעות ערך המטא-נתונים device_authorization_endpoint. כוללים את הפרמטרים הבאים של בקשת HTTP:

דוגמאות

בקטע הקוד הבא מוצגת בקשה לדוגמה:

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

client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl

בדוגמה הזו מוצגת פקודת curl לשליחת אותה בקשה:

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
     https://oauth2.googleapis.com/device/code

שלב 2: טיפול בתגובה של שרת ההרשאות

שרת ההרשאות יחזיר אחת מהתגובות הבאות:

תשובה על הצלחה

אם הבקשה תקינה, התגובה תהיה אובייקט JSON עם המאפיינים הבאים:

בקטע הקוד הבא מוצגת תגובה לדוגמה:

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

תגובה על חריגה מהמכסה

אם חרגתם מהמכסה שמשויכת למזהה הלקוח שלכם בבקשות לקוד המכשיר, תקבלו תגובה עם קוד השגיאה 403, שמכילה את השגיאה הבאה:

{
  "error_code": "rate_limit_exceeded"
}

במקרה כזה, צריך להשתמש באסטרטגיית השהיה מעריכית (exponential backoff) כדי להקטין את קצב הבקשות.

שלב 3: הצגת קוד המשתמש

מציגים למשתמש את הערכים verification_url ו-user_code שהתקבלו בשלב 2. שני הערכים יכולים להכיל כל תו שניתן להדפסה מתוך קבוצת התווים US-ASCII. התוכן שמוצג למשתמש צריך לכלול הוראות למשתמש לנווט אל verification_url במכשיר נפרד ולהזין את user_code.

כשמעצבים ממשק משתמש (UI), חשוב לזכור את הכללים הבאים:

• user_code
  • הערך user_code צריך להיות מוצג בשדה שיכול להכיל 15 תווים בגודל 'W'. במילים אחרות, אם אתם מצליחים להציג את הקוד WWWWWWWWWWWWWWW כמו שצריך, ממשק המשתמש שלכם תקין, ואנחנו ממליצים להשתמש בערך המחרוזת הזה כשבודקים את אופן ההצגה של user_code בממשק המשתמש.
  • הערך user_code הוא תלוי אותיות רישיות, ואסור לשנות אותו בשום צורה, למשל לשנות את גודל האותיות או להוסיף תווים אחרים של עיצוב.
• verification_url
  • השטח שבו מוצג verification_url צריך להיות רחב מספיק כדי להכיל מחרוזת של כתובת URL באורך 40 תווים.
  • אסור לשנות את verification_url בשום צורה, אלא אם רוצים להסיר את הסכימה לצורך הצגה. אם אתם מתכננים להסיר את הסכימה (למשל https://) מכתובת ה-URL מסיבות שקשורות לתצוגה, ודאו שהאפליקציה יכולה לטפל גם בגרסאות http וגם בגרסאות https.

שלב 4: שליחת שאילתה לשרת ההרשאות של Google

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

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

כתובת ה-URL של נקודת הקצה שצריך לבצע בה סקר היא https://oauth2.googleapis.com/token. בקשת התשאול מכילה את הפרמטרים הבאים:

דוגמאות

בקטע הקוד הבא מוצגת בקשה לדוגמה:

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

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

בדוגמה הזו מוצגת פקודת curl לשליחת אותה בקשה:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

שלב 5: המשתמש מגיב לבקשת הגישה

בתמונה הבאה מוצג דף שדומה למה שהמשתמשים רואים כשהם עוברים אל verification_url שהצגתם בשלב 3:

אחרי שהמשתמש מזין את user_code, ואם הוא לא מחובר לחשבון Google, הוא מתחבר לחשבון. לאחר מכן מוצג לו מסך הסכמה כמו זה שמוצג למטה:

שלב 6: טיפול בתשובות לבקשות להשתתפות בסקר

שרת ההרשאות של Google מגיב לכל בקשת בדיקה באחת מהתגובות הבאות:

קיבלת גישה

אם המשתמש העניק גישה למכשיר (על ידי לחיצה על Allow במסך ההסכמה), התגובה תכלול אסימון גישה ואסימון רענון. האסימונים מאפשרים למכשיר לגשת לממשקי Google API מטעם המשתמש. (המאפיין scope בתשובה קובע לאילו ממשקי API יש למכשיר גישה).

במקרה הזה, התגובה מה-API מכילה את השדות הבאים:

בקטע הקוד הבא מוצגת תגובה לדוגמה:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

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

הגישה נדחתה

אם המשתמש מסרב להעניק גישה למכשיר, קוד הסטטוס של תגובת ה-HTTP מהשרת הוא 403 (Forbidden). התגובה מכילה את השגיאה הבאה:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

בהמתנה לאישור

אם המשתמש עדיין לא השלים את תהליך ההרשאה, השרת מחזיר קוד סטטוס של תגובת HTTP‏ 428 (Precondition Required). התגובה מכילה את השגיאה הבאה:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

הסקרים מוצגים בתדירות גבוהה מדי

אם המכשיר שולח בקשות סקר בתדירות גבוהה מדי, השרת מחזיר קוד סטטוס של תגובת HTTP‏ 403 (Forbidden). התגובה מכילה את השגיאה הבאה:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

שגיאות אחרות

שרת ההרשאות מחזיר גם שגיאות אם בבקשת הבדיקה חסרים פרמטרים נדרשים או אם ערך הפרמטר שגוי. בדרך כלל, לבקשות האלה יש קוד סטטוס של תגובת HTTP‏ 400 (Bad Request) או 401 (Unauthorized). השגיאות האלה כוללות:

קריאה לממשקי Google APIs

אחרי שהאפליקציה מקבלת אסימון גישה, אפשר להשתמש באסימון כדי לבצע קריאות ל-Google API מטעם חשבון משתמש מסוים, אם ניתנו ההיקפים של הגישה שנדרשים על ידי ה-API. כדי לעשות את זה, צריך לכלול את אסימון הגישה בבקשה ל-API באמצעות פרמטר access_token של שאילתה או ערך של Authorization כותרת HTTP Bearer. כשניתן, עדיף להשתמש בכותרת HTTP, כי מחרוזות שאילתה נוטות להיות גלויות ביומני השרת. ברוב המקרים, אפשר להשתמש בספריית לקוח כדי להגדיר את הקריאות ל-Google APIs (לדוגמה, כשקוראים ל-YouTube Live Streaming API).

חשוב לדעת ש-YouTube Live Streaming API לא תומך בתהליך של חשבון שירות. מכיוון שאין אפשרות לקשר חשבון שירות לחשבון YouTube, ניסיונות לאשר בקשות באמצעות התהליך הזה ייצרו שגיאה NoLinkedYouTubeAccount.

אתם יכולים להתנסות בכל ממשקי Google APIs ולראות את היקפי ההרשאות שלהם ב-OAuth 2.0 Playground.

דוגמאות ל-HTTP GET

קריאה לנקודת הקצה liveBroadcasts.list (YouTube Live Streaming API) באמצעות כותרת ה-HTTP‏ Authorization: Bearer עשויה להיראות כך. שימו לב: צריך לציין טוקן גישה משלכם:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

זוהי קריאה לאותו API עבור המשתמש המאומת באמצעות פרמטר מחרוזת השאילתה access_token:

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

curl דוגמאות

אפשר לבדוק את הפקודות האלה באמצעות אפליקציית שורת הפקודה curl. הנה דוגמה לשימוש באפשרות של כותרת HTTP (מומלץ):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

רענון של טוקן גישה

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

כדי לרענן אסימון גישה, האפליקציה שולחת בקשת HTTPS‏ POST לשרת ההרשאות של Google‏ (https://oauth2.googleapis.com/token) שכוללת את הפרמטרים הבאים:

בקטע הקוד הבא מוצגת בקשה לדוגמה:

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

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

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

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

ביטול טוקן

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

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

כדי לבטל אסימון באופן פרוגרמטי, האפליקציה שולחת בקשה אל https://oauth2.googleapis.com/revoke וכוללת את האסימון כפרמטר:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

האסימון יכול להיות אסימון גישה או אסימון רענון. אם האסימון הוא אסימון גישה ויש לו אסימון רענון תואם, גם אסימון הרענון יבוטל.

אם הביטול מעובד בהצלחה, קוד הסטטוס של HTTP בתגובה הוא 200. במקרים של שגיאות, מוחזר קוד סטטוס HTTP‏ 400 יחד עם קוד שגיאה.

היקפים מותרים

תהליך ההרשאה באמצעות OAuth 2.0 למכשירים נתמך רק בהיקפי ההרשאות הבאים:

גישה מבוססת-זמן

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

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