במסמך הזה מוסבר איך להטמיע הרשאה של 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 בפרויקט:
- Open the API Library ב Google API Console.
- If prompted, select a project, or create a new one.
- משתמשים בדף Library כדי למצוא את YouTube Data API ולהפעיל אותו. מוצאים את כל ממשקי ה-API האחרים שבהם האפליקציה תשתמש ומפעילים אותם גם כן.
יצירת פרטי כניסה להרשאה
כל אפליקציה שמשתמשת ב-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, מומלץ לזהות את היקפי ההרשאות שאליהם האפליקציה תצטרך גישה.
ב-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
גם אם האפליקציה פועלת במכשיר עם יכולות קלט מוגבלות, המשתמשים צריכים שתהיה להם גישה נפרדת למכשיר עם יכולות קלט עשירות יותר כדי להשלים את תהליך ההרשאה. התהליך כולל את השלבים הבאים:
- האפליקציה שולחת בקשה לשרת ההרשאות של 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 מציגה למשתמש. אפשר לעיין ברשימת היקפי הגישה המותרים לאפליקציות או למכשירים מותקנים. היקפי הרשאות מאפשרים לאפליקציה לבקש גישה רק למשאבים שנחוצים לה, ומאפשרים גם למשתמשים לקבוע את רמת הגישה שהם מעניקים לאפליקציה. לכן, יש קשר הפוך בין מספר ההיקפים המבוקשים לבין הסבירות לקבלת הסכמה מהמשתמשים. ב-YouTube Data API גרסה 3 נעשה שימוש בהיקפי הגישה הבאים:
במסמך היקפי 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 כל חמש שניות. פרטים נוספים זמינים בשלב 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 למשך זמן רב, תוכלו להשתמש באסימון הרענון כדי לקבל אסימון גישה חדש. אם לאפליקציה שלכם נדרשת גישה מהסוג הזה, עליכם לאחסן את אסימון הרענון לשימוש מאוחר יותר.
הגישה נדחתה
אם המשתמש מסרב להעניק גישה למכשיר, תגובה מהשרת תכלול את קוד סטטוס התגובה 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 לא נמצא. לדוגמה, השגיאה הזו מתרחשת אם ערך הפרמטר סוג הלקוח ב-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 APIs (לדוגמה, כשקוראים ל-YouTube Data API).
לתשומת ליבכם: ה-YouTube Data API תומך בחשבונות שירות רק לבעלי תוכן ב-YouTube שיש להם כמה ערוצי YouTube שבבעלותם והם מנהלים אותם, כמו לייבלים ואולפני סרטים.
אפשר לנסות את כל ממשקי Google APIs ולראות את היקפי ההרשאות שלהם ב-OAuth 2.0 Playground.
דוגמאות לבקשות HTTP GET
קריאה לנקודת הקצה
youtube.channels (YouTube Data API) באמצעות הכותרת Authorization: Bearer של HTTP עשויה להיראות כך: חשוב לשים לב שצריך לציין את טוקן הגישה שלכם:
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
emailopenidprofile
Drive API
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
YouTube API
https://www.googleapis.com/auth/youtubehttps://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
במאמר הגנה על חשבונות משתמשים באמצעות הגנה על כל החשבונות מוסבר איך מטמיעים את ההגנה על כל החשבונות ומופיעה רשימה מלאה של האירועים הזמינים.