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 credentials (יצירת פרטי כניסה) > OAuth client ID (מזהה לקוח OAuth).
  3. בוחרים בסוג האפליקציה טלוויזיות ומכשירי קלט מוגבלים.
  4. נותנים שם ללקוח OAuth 2.0 ולוחצים על Create.

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

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

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

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

טווחים
https://www.googleapis.com/auth/youtubeניהול חשבון YouTube שלך
https://www.googleapis.com/auth/youtube.channel-memberships.creatorהצגת רשימה מעודכנת של החברים הפעילים במועדון החברים של הערוץ, הרמה הנוכחית שלהם והתאריך שבו הם הצטרפו למועדון
https://www.googleapis.com/auth/youtube.force-sslהצגה, עריכה ומחיקה לצמיתות של סרטונים, דירוגים, תגובות וכתוביות ב-YouTube
https://www.googleapis.com/auth/youtube.readonlyהצגת חשבון YouTube שלך
https://www.googleapis.com/auth/youtube.uploadניהול הסרטונים שלך ב-YouTube
https://www.googleapis.com/auth/youtubepartnerהצגה וניהול של הנכסים והתכנים הקשורים שלך ב-YouTube
https://www.googleapis.com/auth/youtubepartner-channel-auditהצגת מידע פרטי של ערוץ YouTube שלך הרלוונטי בתהליך הביקורת של שותף YouTube.

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

קבלת אסימוני גישה מסוג 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:

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

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

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

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

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

טווחים
https://www.googleapis.com/auth/youtubeניהול חשבון YouTube שלך
https://www.googleapis.com/auth/youtube.channel-memberships.creatorהצגת רשימה מעודכנת של החברים הפעילים במועדון החברים של הערוץ, הרמה הנוכחית שלהם והתאריך שבו הם הצטרפו למועדון
https://www.googleapis.com/auth/youtube.force-sslהצגה, עריכה ומחיקה לצמיתות של סרטונים, דירוגים, תגובות וכתוביות ב-YouTube
https://www.googleapis.com/auth/youtube.readonlyהצגת חשבון YouTube שלך
https://www.googleapis.com/auth/youtube.uploadניהול הסרטונים שלך ב-YouTube
https://www.googleapis.com/auth/youtubepartnerהצגה וניהול של הנכסים והתכנים הקשורים שלך ב-YouTube
https://www.googleapis.com/auth/youtubepartner-channel-auditהצגת מידע פרטי של ערוץ YouTube שלך הרלוונטי בתהליך הביקורת של שותף YouTube.

המסמך היקפי API של OAuth 2.0 כולל רשימה מלאה של היקפים שבהם תוכלו להשתמש כדי לגשת ל-Google APIs.

דוגמאות

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

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

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

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

הגישה נדחתה

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

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

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

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

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

ממשק API של YouTube

  • 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

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