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

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

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

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

חלופות

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

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

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

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

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

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

1. פותחים את API Library ב-Google API Console.
2. אם מתבקשים, בוחרים פרויקט או יוצרים פרויקט חדש.
3. משתמשים בדף Library כדי למצוא ולהפעיל את YouTube Data API. מוצאים ממשקי API נוספים שהאפליקציה תשתמש בהם ומפעילים גם אותם.

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

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

1. עוברים אל דף הלקוחות.
2. לוחצים על Create Client.
3. בוחרים את סוג האפליקציה טלוויזיות והתקני קלט עם הגבלות.
4. נותנים שם ללקוח OAuth 2.0 ולוחצים על יצירה.

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

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

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

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

בודקים את הרשימה Allowed scopes (היקפי הרשאות מותרים) באפליקציות או במכשירים המותקנים.

קבלת אסימוני גישה מסוג 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 הזו ממסמך Discovery באמצעות ערך המטא-נתונים 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.readonly

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

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly" \
     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 הוא תלוי אותיות רישיות (case-sensitive), ולכן אין לשנות אותו בשום צורה, למשל לשנות את האותיות לאותיות רישיות או קטנות בלבד או להוסיף תווים אחרים לעיצוב.
• 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 למשך זמן ארוך, היא יכולה להשתמש באסימון הרענון כדי לקבל אסימון גישה חדש. אם האפליקציה שלכם צריכה גישה מהסוג הזה, היא צריכה לשמור את אסימון הרענון לשימוש מאוחר יותר.

הגישה נדחתה

אם המשתמש מסרב להעניק גישה למכשיר, קוד הסטטוס של תגובת השרת הוא 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 של השאילתה או הערך Bearer של כותרת ה-HTTP Authorization. אם אפשר, עדיף להשתמש בכותרת HTTP, כי מחרוזות של שאילתות בדרך כלל גלויות ביומני השרת. ברוב המקרים, אפשר להשתמש בספריית לקוח כדי להגדיר את הקריאות ל-Google APIs (לדוגמה, כשקוראים ל-YouTube Data API).

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

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

דוגמאות ל-HTTP GET

קריאה לנקודת הקצה youtube.channels (YouTube Data API) באמצעות כותרת ה-HTTP Authorization: Bearer עשויה להיראות כך. חשוב לציין את טוקן הגישה שלכם:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

curl דוגמאות

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&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&
refresh_token=refresh_token&
grant_type=refresh_token

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

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "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 שמוחזר בתגובה של החלפת קוד ההרשאה מייצג את הזמן שנותר עד שתוקף אסימון הרענון יפוג במקרים כאלה.