דף זה תורגם על ידי Cloud Translation API.

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

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

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 בפרויקט:

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

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

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

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

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

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

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

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

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

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

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

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

המשתמש נכנס לחשבון במכשיר נפרד שיש בו דפדפן

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

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

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

פרמטרים

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

client_id

חובה

מזהה הלקוח של האפליקציה. הערך הזה מופיע ב- API Console Credentials page.

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`	ערך שתלוי באותיות רישיות שמזהה ל-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 הוא תלוי אותיות רישיות, ואין לשנות אותו בשום צורה, למשל לשנות את גודל האותיות או להוסיף תווים אחרים של עיצוב.
verification_url
- המרחב שבו מוצגת המשתנה verification_url צריך להיות רחב מספיק כדי לטפל במחרוזת של כתובת URL באורך 40 תווים.
- אין לשנות את verification_url בשום צורה, אלא אם רוצים להסיר את הסכימה לתצוגה. אם אתם מתכננים להסיר את הסכימה (למשל https://) מכתובת ה-URL מסיבות תצוגה, חשוב לוודא שהאפליקציה יכולה לטפל גם בגרסה http וגם בגרסה https.

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

שלב 4: בודקים את שרת ההרשאות של Google

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

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

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

פרמטרים
`client_id`	מזהה הלקוח של האפליקציה. הערך הזה מופיע ב- API Console Credentials page.
`client_secret`	סוד הלקוח של `client_id` שצוין. הערך הזה מופיע ב- API Console Credentials page.
`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` מפורטים כרשימה של מחרוזות תלויות-אותיות רישיות שמפרידות ביניהן רווחים.
`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 למשך זמן רב, תוכלו להשתמש באסימון הרענון כדי לקבל אסימון גישה חדש. אם לאפליקציה שלכם נדרשת גישה מהסוג הזה, עליכם לאחסן את אסימון הרענון לשימוש מאוחר יותר.

הגישה נדחתה

אם המשתמש מסרב להעניק גישה למכשיר, תגובה מהשרת תכלול את קוד סטטוס התגובה 403 של HTTP (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 שגוי. מוודאים שסוג האפליקציה של מזהה הלקוח מוגדר כטלוויזיות והתקני קלט עם הגבלות.
`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 בכותרת Authorization של HTTP. כשהדבר אפשרי, עדיף להשתמש בכותרת ה-HTTP, כי מחרוזות השאילתות נוטים להיות גלויות ביומנים של השרת. ברוב המקרים אפשר להשתמש בספריית לקוח כדי להגדיר את הקריאות לממשקי Google API (לדוגמה, כשקוראים ל-Drive Files API).

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

דוגמאות לבקשות HTTP GET

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

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) שכוללת את הפרמטרים הבאים:

שדות
`client_id`	מזהה הלקוח שהתקבל מ- API Console.
`client_secret`	סוד הלקוח שהתקבל מ- API Console.
`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&
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 למכשירים נתמך רק בהיקפים הבאים:

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

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

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

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

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

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

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

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

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

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

דוגמאות

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

תגובת הצלחה

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

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

שלב 4: בודקים את שרת ההרשאות של Google

דוגמאות

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

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

קיבלת גישה

הגישה נדחתה

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

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

שגיאות אחרות

קריאה ל-Google APIs

דוגמאות לבקשות HTTP GET

curl דוגמאות

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

ביטול טוקן

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

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

Drive API

YouTube API

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

`curl` דוגמאות