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

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

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 Console.

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

1. Open the API Library ב Google API Console.
2. If prompted, select a project, or create a new one.
3. ב- API Library מפורטים כל ממשקי ה-API הזמינים, שמקובצים לפי משפחת מוצרים ופופולריות. אם ממשק ה-API שרוצים להפעיל לא מופיע ברשימה, אפשר לחפש אותו או ללחוץ על הצגת הכול במשפחת המוצרים שאליה הוא שייך.
4. בוחרים את ה-API שרוצים להפעיל ולוחצים על הלחצן Enable.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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

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

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

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

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

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

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

קבלת אסימוני גישה מסוג 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=email%20profile

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

curl -d "client_id=client_id&scope=email%20profile" \
     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"
}

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

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

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

חשוב להביא בחשבון את הכללים הבאים כשמתכננים את ממשק המשתמש:

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

הגישה נדחתה

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

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

ההרשאה בהמתנה

אם המשתמש עדיין לא השלים את תהליך ההרשאה, השרת מחזיר קוד הסטטוס 428 של תשובת HTTP (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 API (לדוגמה, כשקוראים ל-Drive Files API).

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

דוגמאות ל-HTTP GET

קריאה לנקודת הקצה drive.files (Drive Files API) באמצעות כותרת ה-HTTP Authorization: Bearer עשויה להיראות כך. חשוב לשים לב שצריך לציין את טוקן הגישה שלכם:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl דוגמאות

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

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

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

רענון של אסימון גישה

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

כדי לרענן אסימון גישה, האפליקציה שולחת בקשת POST ב-HTTPS לשרת ההרשאות של 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",
  "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 למכשירים נתמך רק בהיקפים הבאים: