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

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

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

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

חלופות

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

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

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

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

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

  1. פותחים את ספריית ה-API ב-Google API Console.
  2. אם מתבקשים, בוחרים פרויקט או יוצרים פרויקט חדש.
  3. בספריית ה-API מופיעים כל ממשקי ה-API הזמינים, מקובצים לפי משפחת מוצרים ופופולריות. אם ה-API שרוצים להפעיל לא מופיע ברשימה, אפשר לחפש אותו או ללחוץ על View All במשפחת המוצרים שאליה הוא שייך.
  4. בוחרים את ה-API שרוצים להפעיל ולוחצים על הכפתור Enable.
  5. אם מוצגת בקשה, מפעילים את החיוב.
  6. אם מוצגת בקשה, קוראים את התנאים וההגבלות של ה-API ומאשרים אותם.

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

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

  1. עוברים אל הדף "לקוחות".
  2. לוחצים על Create Client.
  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: מבקשים קודי מכשיר ומשתמש

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

פרמטרים
client_id חובה

מזהה הלקוח של האפליקציה. אפשר למצוא את הערך הזה בדף Clients במסוף Cloud.
scope חובה

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

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

דוגמאות

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

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

הקוד הזה מאפשר למכשיר שמריץ את האפליקציה לקבוע באופן מאובטח אם המשתמש אישר או דחה את הגישה.
expires_in משך הזמן, בשניות, שבו device_code ו-user_code תקפים. אם המשתמש לא משלים את תהליך ההרשאה בפרק הזמן הזה, והמכשיר לא שולח בקשות כדי לאחזר מידע על ההחלטה של המשתמש, יכול להיות שתצטרכו להפעיל מחדש את התהליך משלב 1.
interval משך הזמן, בשניות, שהמכשיר צריך להמתין בין בקשות הסקר. לדוגמה, אם הערך הוא 5, המכשיר צריך לשלוח בקשת דגימה לשרת ההרשאות של Google כל חמש שניות. פרטים נוספים זמינים בשלב 3.
user_code ערך תלוי אותיות רישיות (case-sensitive) שמזהה עבור Google את היקפי ההרשאות שהאפליקציה מבקשת גישה אליהם. ממשק המשתמש ינחה את המשתמש להזין את הערך הזה במכשיר נפרד עם יכולות קלט עשירות יותר. ‫Google משתמשת בערך הזה כדי להציג את קבוצת ההיקפים הנכונה כשהיא מבקשת מהמשתמש לתת לאפליקציה גישה.
verification_url כתובת URL שהמשתמש צריך לעבור אליה במכשיר נפרד כדי להזין את ה-user_code ולאשר או לדחות את הגישה לאפליקציה. הערך הזה יוצג גם בממשק המשתמש.

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

{
  "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.

כשמעצבים את ממשק המשתמש (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 של נקודת הקצה (endpoint) לדגימה היא https://oauth2.googleapis.com/token. בקשת הסקר מכילה את הפרמטרים הבאים:

פרמטרים
client_id מזהה הלקוח של האפליקציה. הערך הזה מופיע בדף Clients במסוף Cloud.
client_secret סוד הלקוח של client_id שצוין. הערך הזה מופיע בדף Clients במסוף Cloud.
device_code ‫device_code שהוחזר על ידי שרת ההרשאות בשלב 2.
grant_type מגדירים את הערך הזה בתור urn:ietf:params:oauth:grant-type:device_code.

דוגמאות

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

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 האסימון שהאפליקציה שולחת כדי לאשר בקשת Google API.
expires_in משך החיים שנותר לאסימון הגישה, בשניות.
refresh_token טוקן שאפשר להשתמש בו כדי לקבל טוקן גישה חדש. טוקני הרענון תקפים עד שהמשתמש מבטל את הגישה או עד שתוקף הטוקן פג. שימו לב שתמיד מוחזרים טוקנים לרענון למכשירים.
scope היקפי הגישה שניתנו על ידי access_token, מבוטאים כרשימה של מחרוזות תלויות אותיות רישיות (case-sensitive) שמופרדות ברווחים.
token_type סוג הטוקן שהוחזר. הערך הזה הוא תמיד Bearer.

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

{
  "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). השגיאות האלה כוללות:

שגיאה קוד סטטוס של HTTP תיאור
admin_policy_enforced 400 חשבון Google לא יכול לאשר היקף הרשאות אחד או יותר שהתבקשו בגלל כללי המדיניות של האדמין ב-Google Workspace. במאמר העזרה לאדמינים ב-Google Workspace, איך קובעים לאילו אפליקציות פנימיות ואפליקציות של צד שלישי תהיה גישה לנתונים ב-Google Workspace, מוסבר איך אדמינים יכולים להגביל את הגישה להיקפי ההרשאות עד שהם נותנים גישה מפורשת למזהה הלקוח ב-OAuth.
invalid_client 401

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

סוג לקוח OAuth שגוי. מוודאים שסוג האפליקציה של מזהה הלקוח מוגדר כ-TVs and Limited Input devices.
invalid_grant 400 ערך הפרמטר code לא תקין, כבר נתבע או שלא ניתן לנתח אותו.
unsupported_grant_type 400 ערך הפרמטר grant_type לא תקין.
org_internal 403 מזהה הלקוח של OAuth בבקשה הוא חלק מפרויקט שמגביל את הגישה לחשבונות Google ב ארגון ספציפי ב-Google Cloud. מוודאים את הגדרת סוג המשתמש באפליקציית OAuth.

שליחת קריאה ל-Google APIs

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

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

דוגמאות ל-HTTP GET

קריאה לנקודת הקצה (endpoint) 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 קשורה. אם ביקשתם גישה אופליין להיקפי ההרשאות שמשויכים לטוקן, אתם יכולים לרענן את טוקן הגישה בלי לבקש הרשאה מהמשתמש (גם כשהמשתמש לא נוכח).

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

שם ערך
client_id מזהה הלקוח שמתקבל מ-קונסולה לממשקי API.
client_secret אופציונלי

סוד הלקוח שהתקבל מקונסולה לממשקי API.

grant_type כפי שמוגדר במפרט של OAuth 2.0, הערך של השדה הזה צריך להיות refresh_token.
refresh_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/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 למכשירים נתמך רק בהיקפים הבאים:

OpenID Connect, כניסה באמצעות חשבון Google

  • email
  • openid
  • profile

Drive API

  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file

YouTube API

  • https://www.googleapis.com/auth/youtube
  • https://www.googleapis.com/auth/youtube.readonly

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

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

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

הטמעת ההגנה על כל החשבונות

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

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

  • https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
  • https://schemas.openid.net/secevent/oauth/event-type/token-revoked
  • https://schemas.openid.net/secevent/risc/event-type/account-disabled

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