במסמך הזה מוסבר איך אפליקציות שמותקנות במכשירים כמו טלפונים, טאבלטים ומחשבים משתמשות בנקודות הקצה מסוג OAuth 2.0 של Google כדי לאשר גישה ל-YouTube Data API.
OAuth 2.0 מאפשר למשתמשים לשתף נתונים ספציפיים עם אפליקציה, תוך שמירה על הפרטיות של שמות המשתמשים, הסיסמאות ומידע אחר שלהם. לדוגמה, אפליקציה יכולה להשתמש ב-OAuth 2.0 כדי לקבל הרשאה לאחזור נתוני YouTube של ערוץ.
האפליקציות המותקנות מופצות למכשירים ספציפיים, וההנחה היא שהאפליקציות האלה לא יכולות לשמור סודות. הם יכולים לגשת ל-Google APIs כל עוד המשתמש נמצא באפליקציה או והאפליקציה פועלת ברקע.
תהליך ההרשאה הזה דומה לתהליך ההרשאה שמשמש לאפליקציות של שרת אינטרנט. ההבדל העיקרי הוא שהאפליקציות המותקנות חייבות לפתוח את דפדפן המערכת ולספק URI של הפניה אוטומטית לכתובת URL אחרת כדי לטפל בתגובות משרת ההרשאות של Google.
חלופות
באפליקציות לנייד, יכול להיות שעדיף להשתמש בכניסה באמצעות חשבון Google ל-Android או ל-iOS. ספריות הלקוח של 'כניסה באמצעות חשבון Google' מטפלות באימות ובהרשאות משתמשים, ויכול להיות שיהיה קל יותר להטמיע אותן מאשר הפרוטוקול ברמה הנמוכה יותר שמתואר כאן.
לגבי אפליקציות שפועלות במכשירים שלא תומכים בדפדפן מערכת או שיש להם יכולות קלט מוגבלות, כמו טלוויזיות, קונסולות משחקים, מצלמות או מדפסות, קראו את המאמר OAuth 2.0 לטלוויזיות ומכשירים או כניסה לטלוויזיות ולמכשירי קלט מוגבלים.
ספריות ודוגמאות
אנחנו ממליצים להשתמש בספריות ובדוגמאות הבאות כדי לעזור בהטמעה של תהליך OAuth 2.0 שמתואר במסמך הזה:
- ספריית AppAuth ל-Android
- ספריית AppAuth ל-iOS
- OAuth לאפליקציות: Windows דוגמאות
דרישות מוקדמות
הפעלת ממשקי 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.
- הקטעים הבאים מתארים את סוגי הלקוחות ואת שיטות ההפניה האוטומטית שבהן תומך שרת ההרשאות של Google. בוחרים את סוג הלקוח המומלץ לאפליקציה, נותנים שם ללקוח OAuth ומגדירים את שאר השדות בטופס לפי הצורך.
Android
- בוחרים בסוג האפליקציה Android.
- מזינים שם ללקוח OAuth. השם הזה מוצג ב- Credentials page של הפרויקט כדי לזהות את הלקוח.
- מזינים את שם החבילה של האפליקציה ל-Android. הערך הזה מוגדר
במאפיין
package
של הרכיב<manifest>
בקובץ המניפסט של האפליקציה. - צריך להזין את טביעת האצבע של אישור החתימה SHA-1 של הפצת האפליקציה.
- אם באפליקציה נעשה שימוש בחתימת אפליקציות דרך Google Play, צריך להעתיק את טביעת האצבע מסוג SHA-1 מדף חתימת האפליקציה ב-Play Console.
- אם אתם מנהלים מאגר מפתחות ומפתחות חתימה משלכם, צריך להשתמש בכלי keytool שכלול ב-Java כדי להדפיס את פרטי האישורים בפורמט קריא לאנשים. מעתיקים את הערך
SHA1
בקטעCertificate fingerprints
של הפלט של keytool. למידע נוסף, ראו אימות הלקוח במסמכי התיעוד של Google APIs ל-Android.
- (אופציונלי) מאמתים את הבעלות על האפליקציה ל-Android.
- לוחצים על יצירה.
iOS
- בוחרים בסוג האפליקציה iOS.
- מזינים שם ללקוח OAuth. השם הזה מוצג ב- Credentials page של הפרויקט כדי לזהות את הלקוח.
- מזינים את מזהה החבילה של האפליקציה. מזהה החבילה הוא הערך של מפתח CFBundleIdentifier בקובץ המשאבים של רשימת מאפייני המידע של האפליקציה (info.plist). בדרך כלל הערך מוצג בחלונית General או בחלונית Signing & Capabilities של Xcode, לעריכת פרויקטים. מזהה החבילה מוצג גם בקטע 'מידע כללי' בדף המידע של האפליקציה באתר App Store Connect של Apple.
- (אופציונלי)
אם האפליקציה פורסמה ב-Apple App Store, צריך להזין את המזהה של האפליקציה ב-App Store. מזהה החנות הוא מחרוזת מספרית שמופיעה בכל כתובת URL של Apple App Store.
- פותחים את אפליקציית Apple App Store במכשיר iOS או iPadOS.
- מחפשים את האפליקציה.
- לוחצים על לחצן השיתוף (סמל ריבוע וחץ למעלה).
- בוחרים באפשרות העתקת הקישור.
- מדביקים את הקישור בכלי לעריכת טקסט. מזהה App Store הוא החלק האחרון בכתובת ה-URL.
דוגמה:
https://apps.apple.com/app/google/id284815942
- (אופציונלי)
צריך להזין את מזהה הצוות. מידע נוסף זמין במאמר איתור מזהה הצוות במסמכי התיעוד של חשבון הפיתוח של Apple.
- לוחצים על יצירה.
UWP
- בוחרים בסוג האפליקציה Universal Windows Platform.
- מזינים שם ללקוח OAuth. השם הזה מוצג ב- Credentials page של הפרויקט כדי לזהות את הלקוח.
- יש להזין את מזהה Microsoft Store בן 12 התווים של האפליקציה. אפשר למצוא את הערך הזה ב-Microsoft Partner Center בדף App Identity בקטע 'ניהול אפליקציות'.
- לוחצים על יצירה.
עבור אפליקציות UWP, סכימת ה-URI המותאמת אישית לא יכולה להיות ארוכה מ-39 תווים.
סכמת URI מותאמת אישית (Android, iOS, UWP)
סכימות URI מותאמות אישית הן סוג של קישורי עומק שמשתמשים בסכימה מוגדרת בהתאמה אישית כדי לפתוח את האפליקציה.
חלופה לשימוש בסכימות URI מותאמות אישית ב-Androidמשתמשים בכניסה באמצעות חשבון Google ל-Android SDK, שמעביר את תגובת OAuth 2.0 ישירות לאפליקציה, בלי צורך ב-URI להפניה אוטומטית.
איך עוברים ל-SDK של כניסה באמצעות חשבון Google ל-Android
אם בחרת להשתמש בסכמה מותאמת אישית לשילוב של OAuth ב-Android, עליך לבצע את הפעולות הבאות כדי לעבור באופן מלא לשימוש ב-SDK המומלץ לכניסה באמצעות חשבון Google ל-Android:
- צריך לעדכן את הקוד כדי להשתמש ב-SDK של כניסה באמצעות Google.
- השבתת התמיכה בסכמה מותאמת אישית במסוף Google API.
כדי לעבור ל-SDK של Android לכניסה באמצעות חשבון Google:
-
מעדכנים את הקוד כדי להשתמש ב-Android SDK לכניסה באמצעות חשבון Google:
-
צריך לבדוק את הקוד כדי לזהות לאן מתבצעת
שליחת בקשה לשרת OAuth 2.0 של Google. אם משתמשים בסכמה מותאמת אישית, הבקשה תיראה כך:
https://accounts.google.com/o/oauth2/v2/auth? scope=<SCOPES>& response_type=code& &state=<STATE>& redirect_uri=com.example.app:/oauth2redirect& client_id=<CLIENT_ID>
com.example.app:/oauth2redirect
הוא ה-URI של סכימה מותאמת אישית להפניה אוטומטית בדוגמה שלמעלה. למידע נוסף על הפורמט של הערך של סכימת ה-URI המותאמת אישית, עיינו בהגדרת הפרמטרredirect_uri
. -
חשוב לשים לב לפרמטרים של הבקשה
scope
ו-client_id
שצריך להגדיר את ה-SDK של הכניסה באמצעות Google. -
פועלים לפי ההוראות
לתחילת השילוב של 'כניסה באמצעות חשבון Google' באפליקציה ל-Android
כדי להגדיר את ה-SDK. אפשר לדלג על השלב קבלת מזהה הלקוח ב-OAuth 2.0 של שרת הקצה העורפי כי אפשר להשתמש שוב ב-
client_id
שאחזרתם מהשלב הקודם. -
פועלים לפי ההוראות במאמר
הפעלת גישה ל-API בצד השרת. זה כולל את השלבים הבאים:
-
משתמשים ב-method
getServerAuthCode
כדי לאחזר קוד הרשאה להיקפי ההרשאות שעבורם מבקשים הרשאה. - צריך לשלוח את קוד ההרשאה לקצה העורפי של האפליקציה כדי להחליף אותו באסימון גישה ורענון.
- משתמשים באסימון הגישה שאוחזר כדי לבצע קריאות ל-Google APIs בשם המשתמש.
-
משתמשים ב-method
-
צריך לבדוק את הקוד כדי לזהות לאן מתבצעת
שליחת בקשה לשרת OAuth 2.0 של Google. אם משתמשים בסכמה מותאמת אישית, הבקשה תיראה כך:
-
משביתים את התמיכה בסכמה מותאמת אישית במסוף Google API:
- נכנסים לרשימת פרטי הכניסה של OAuth 2.0 ובוחרים את תוכנת Android הרצויה.
- עוברים לקטע Advanced Settings (הגדרות מתקדמות), מבטלים את הסימון בתיבה Enable Custom URI Scheme (הפעלת סכימת URI מותאמת אישית) ולוחצים על Save כדי להשבית את התמיכה בסכימות URI מותאמות אישית.
הפעלה של סכימת URI מותאמת אישית
אם החלופה המומלצת לא מתאימה לכם, אפשר להפעיל סכימות URI מותאמות אישית ללקוח Android שלכם לפי ההוראות הבאות:- נכנסים לרשימת פרטי הכניסה של OAuth 2.0 ובוחרים את תוכנת Android הרצויה.
- עוברים לקטע Advanced Settings (הגדרות מתקדמות), מסמנים את התיבה Enable Custom URI Scheme (הפעלת סכימת URI מותאמת אישית) ולוחצים על Save כדי להפעיל תמיכה בסכמת URI מותאמת אישית.
משתמשים ב-Chrome Identity API כדי לשלוח את תגובת OAuth 2.0 ישירות לאפליקציה, בלי צורך ב-URI להפניה אוטומטית.
אימות הבעלות על האפליקציה (Android, Chrome)
ניתן לאמת את הבעלות על האפליקציה כדי לצמצם את הסיכון להתחזות לאפליקציה.
Android
כדי להשלים את תהליך האימות, אפשר להשתמש בחשבון הפיתוח ב-Google Play אם יש לך חשבון והאפליקציה שלך רשומה ב-Google Play Console. כדי לבצע אימות בהצלחה, צריכים להתקיים התנאים הבאים:
- צריכה להיות לך אפליקציה רשומה ב-Google Play Console, עם אותו שם חבילה וטביעת אצבע של אישור חתימה SHA-1 כמו בלקוח OAuth של Android שבשבילו השלמת האימות.
- נדרשת הרשאת אדמין לאפליקציה ב-Google Play Console. מידע נוסף על ניהול הרשאות גישה ב-Google Play Console
בקטע אימות בעלות על אפליקציה בלקוח Android, לוחצים על הלחצן אימות בעלות כדי להשלים את תהליך האימות.
אם האימות יושלם בהצלחה, תוצג הודעה שמאשרת את ההצלחה של תהליך האימות. אחרת, תוצג הודעת שגיאה.
כדי לפתור אימות שנכשל, אפשר לנסות את הפעולות הבאות:
- יש לוודא שהאפליקציה שברצונך לאמת היא אפליקציה רשומה ב-Google Play Console.
- צריך לוודא שיש לך הרשאת אדמין לאפליקציה ב-Google Play Console.
Chrome
כדי להשלים את תהליך האימות, עליך להשתמש בחשבון הפיתוח שלך בחנות האינטרנט של Chrome. כדי שהאימות יושלם בהצלחה, עליכם לעמוד בדרישות הבאות:
- צריך להיות פריט רשום במרכז השליטה למפתחים של חנות האינטרנט של Chrome עם אותו מזהה פריט כמו בלקוח ה-OAuth של התוספים ל-Chrome שבשבילו השלמת האימות.
- אתם צריכים להיות בעלי תוכן דיגיטלי של פריט בחנות האינטרנט של Chrome. אפשר לקרוא מידע נוסף על ניהול הרשאות גישה במרכז השליטה למפתחים של חנות האינטרנט של Chrome.
בקטע אימות בעלות על אפליקציה בלקוח התוסף ל-Chrome, לוחצים על הלחצן אימות בעלות כדי להשלים את תהליך האימות.
הערה: אחרי שמעניקים גישה לחשבון, צריך להמתין כמה דקות לפני השלמת תהליך האימות.
אם האימות יושלם בהצלחה, תוצג הודעה שמאשרת את ההצלחה של תהליך האימות. אחרת, תוצג הודעת שגיאה.
כדי לפתור אימות שנכשל, אפשר לנסות את הפעולות הבאות:
- צריך לוודא שיש פריט רשום במרכז השליטה למפתחים של חנות האינטרנט של Chrome עם אותו מזהה פריט כמו בלקוח ה-OAuth לתוספים ל-Chrome שבשבילו רוצים להשלים את האימות.
- יש לאמת את היותך המפרסם של האפליקציה. כלומר, עליך להיות המפרסם הפרטי של האפליקציה או חבר בקבוצה להפצת האפליקציה. מידע נוסף על ניהול הרשאות גישה במרכז השליטה למפתחים של חנות האינטרנט של Chrome.
- אם עדכנת לאחרונה את רשימת בעלי האתרים הקבוצתיים, עליך לוודא שרשימת החברים בקבוצה של מפתחי האפליקציה מסונכרנת במרכז השליטה למפתחים של חנות האינטרנט של Chrome. מידע נוסף על סנכרון רשימת המינויים של בעלי התוכן הדיגיטלי
כתובת IP בלולאה חוזרת (loopback) (macOS, Linux, מחשב עם Windows)
כדי לקבל את קוד ההרשאה באמצעות כתובת ה-URL הזו, האפליקציה צריכה להאזין לשרת האינטרנט המקומי. זה אפשרי בפלטפורמות רבות, אבל לא בכולן. עם זאת, אם הוא נתמך בפלטפורמה שלך, זה המנגנון המומלץ לקבלת קוד ההרשאה.
כשהאפליקציה מקבלת את תגובת ההרשאה, כדי לשפר את נוחות השימוש, היא צריכה להגיב על ידי הצגת דף HTML שמורה למשתמש לסגור את הדפדפן ולחזור לאפליקציה.
שימוש מומלץ | אפליקציות ל-macOS, ל-Linux ול-Windows במחשב (אבל לא ב-Universal Windows Platform) |
ערכי טופס | מגדירים את סוג האפליקציה כאפליקציה למחשב. |
העתקה/הדבקה ידנית
זיהוי של היקפי גישה
היקפי הרשאות מאפשרים לאפליקציה לבקש גישה רק למשאבים שנחוצים לה, וגם מאפשרים למשתמשים לשלוט בכמות הגישה שהם מעניקים לאפליקציה. לכן, יכול להיות קשר הפוך בין מספר ההיקפים המבוקשים לבין הסבירות לקבל הסכמה מהמשתמשים.
לפני שמתחילים להטמיע הרשאה מסוג OAuth 2.0, מומלץ לזהות את היקפי ההרשאות שהאפליקציה צריכה הרשאה כדי לגשת אליהן.
ממשק YouTube Data API v3 משתמש בהיקפים הבאים:
טווחים | |
---|---|
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.
קבלת אסימוני גישה מסוג OAuth 2.0
השלבים הבאים מראים איך האפליקציה יוצרת אינטראקציה עם שרת OAuth 2.0 של Google כדי לקבל הסכמה מהמשתמש לביצוע בקשת API בשם המשתמש. כדי להוציא לפועל בקשה של Google API שמחייבת הרשאת משתמש, האפליקציה צריכה לקבל את ההסכמה הזו.
שלב 1: יוצרים מאמת קוד ואתגר
Google תומכת בפרוטוקול Proof Key for Code Exchange (PKCE) כדי לשפר את האבטחה של זרימת האפליקציה המותקנת. לכל בקשת הרשאה נוצר מאמת קוד ייחודי, והערך שלו, שנקרא "code_challenge", נשלח לשרת ההרשאות כדי לקבל את קוד ההרשאה.
יצירה של מאמת הקוד
code_verifier
היא מחרוזת אקראית קריפטוגרפית עם אנטרופיה גבוהה שמורכבת מתווים לא שמורים: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", באורך מינימלי של 43 תווים ובאורך מקסימלי של 128 תווים.
למאמת הקוד צריכה להיות מספיק אנטרופיה כדי שלא יהיה מעשי לנחש את הערך.
יוצרים את אתגר הקוד
יש תמיכה בשתי שיטות ליצירת אתגר הקוד.
שיטות ליצירת אתגר קוד | |
---|---|
S256 (מומלץ) | אתגר הקוד הוא גיבוב SHA256 עם קידוד Base64URL (ללא מרווח פנימי) של מאמת הקוד.
|
פשוטה | אתגר הקוד הוא אותו ערך כמו מאמת הקוד שנוצר למעלה.
|
שלב 2: שליחת בקשה לשרת OAuth 2.0 של Google
כדי לקבל הרשאה למשתמש, צריך לשלוח בקשה לשרת האימות של Google בכתובת
https://accounts.google.com/o/oauth2/v2/auth
. נקודת הקצה (endpoint) הזו מטפלת בחיפוש פעיל בסשן,
מאמתת את המשתמש ומקבלת את הסכמת המשתמשים. ניתן לגשת לנקודת הקצה רק באמצעות SSL, והיא דוחה חיבורי HTTP (לא SSL).
שרת ההרשאות תומך בפרמטרים הבאים של מחרוזת השאילתה לאפליקציות מותקנות:
פרמטרים | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
חובה
מזהה הלקוח של האפליקציה. אפשר למצוא את הערך הזה ב- API Console Credentials page. |
||||||||||||||||
redirect_uri |
חובה
ההגדרה הזו קובעת איך שרת ההרשאות של Google שולח תגובה לאפליקציה שלכם. יש כמה אפשרויות להפניה אוטומטית הזמינות לאפליקציות מותקנות, ואתם צריכים להגדיר את פרטי הכניסה להרשאה תוך התחשבות בשיטת הפניה ספציפית. הערך צריך להתאים בדיוק לאחד ממזהי ה-URI המורשים להפניה אוטומטית של לקוח OAuth 2.0, שהגדרתם ב- API Console
Credentials pageשל הלקוח. אם הערך הזה לא תואם ל-URI מורשה, תתקבל השגיאה בטבלה הבאה מוצג ערך הפרמטר
|
||||||||||||||||
response_type |
חובה
המדיניות קובעת אם נקודת הקצה מסוג Google OAuth 2.0 מחזירה קוד הרשאה. צריך להגדיר את ערך הפרמטר כ- |
||||||||||||||||
scope |
חובה
רשימה מופרדת ברווחים של היקפים שמזהים את המשאבים שהאפליקציה יכולה לגשת אליהם בשם המשתמש. הערכים האלה משפיעים על מסך ההסכמה ש-Google מציגה למשתמש. היקפי הרשאות מאפשרים לאפליקציה לבקש גישה רק למשאבים שנחוצים לה, וגם מאפשרים למשתמשים לשלוט בכמות הגישה שהם מעניקים לאפליקציה. לכן, יש קשר הפוך בין מספר היקפי ההרשאות שנדרשים לבין הסבירות לקבלת הסכמה מהמשתמשים. ממשק YouTube Data API v3 משתמש בהיקפים הבאים:
המסמך היקפי API של OAuth 2.0 כולל רשימה מלאה של היקפים שבהם תוכלו להשתמש כדי לגשת ל-Google APIs. |
||||||||||||||||
code_challenge |
המלצות
מציינת |
||||||||||||||||
code_challenge_method |
המלצות
מציינת את השיטה ששימשה לקידוד |
||||||||||||||||
state |
המלצות
מציינת כל ערך מחרוזת שבו האפליקציה משתמשת כדי לשמור על המצב בין
בקשת ההרשאה לבין התגובה של שרת ההרשאות.
השרת מחזיר את הערך המדויק ששולחים בתור צמד אפשר להשתמש בפרמטר הזה לכמה מטרות, כמו הפניה של המשתמש
למשאב הנכון באפליקציה, שליחת צפנים חד-פעמיים (nonce) וצמצום זיוף בקשות בין אתרים. אפשר לנחש את |
||||||||||||||||
login_hint |
אופציונלי
אם האפליקציה מזהה איזה משתמש מנסה לבצע אימות, היא יכולה להשתמש בפרמטר הזה כדי לספק רמז לשרת האימות של Google. השרת משתמש ברמז כדי לפשט את תהליך ההתחברות – על ידי מילוי מראש של שדה האימייל בטופס הכניסה או על-ידי בחירת הסשן המתאים של כניסות מרובות. מגדירים את ערך הפרמטר לכתובת אימייל או למזהה |
דוגמאות לכתובות URL של הרשאות
הכרטיסיות הבאות מציגות כתובות URL של הרשאות לדוגמה עבור האפשרויות השונות של כתובות URI להפניה מחדש.
כל כתובת URL מבקשת גישה להיקף שמאפשר גישה לאחזור נתוני YouTube של המשתמש.כתובות ה-URL זהות, מלבד הערך של הפרמטר redirect_uri
. כתובות ה-URL
מכילות גם את הפרמטרים הנדרשים response_type
ו-client_id
, וגם את הפרמטר האופציונלי state
. כל כתובת URL כוללת מעברי שורה ורווחים כדי לשפר את הקריאוּת.
סכמת URI מותאמת אישית
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
כתובת IP בלולאה חוזרת
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
שלב 3: Google מבקשת הסכמה מהמשתמש
בשלב הזה, המשתמש מחליט אם להעניק לאפליקציה את הרשאת הגישה המבוקשת. בשלב הזה, Google מציגה חלון הסכמה שמציג את שם האפליקציה ואת שירותי Google API שאליהם האפליקציה מבקשת הרשאה לגשת באמצעות פרטי הכניסה להרשאה של המשתמש וסיכום של היקפי הגישה שיש להעניק. לאחר מכן המשתמש יוכל להביע הסכמה להעניק גישה להיקף הרשאות אחד או יותר שהאפליקציה מבקשת, או לדחות את הבקשה.
האפליקציה שלך לא צריכה לעשות שום דבר בשלב הזה כי היא ממתינה לתגובה משרת OAuth 2.0 של Google, שמציינת אם ניתנה גישה. התשובה הזו מוסברת בשלב הבא.
שגיאות
בקשות שנשלחות לנקודת הקצה להרשאה מסוג OAuth 2.0 של Google עשויות להציג הודעות שגיאה שמוצגות למשתמשים במקום תהליכי האימות וההרשאה הצפויים. קודי שגיאה נפוצים והצעות לפתרונות מפורטים בהמשך.
admin_policy_enforced
בהתאם למדיניות של האדמין ב-Google Workspace, אין אפשרות לתת הרשאה להיקף הרשאות אחד או יותר בחשבון Google. במאמר העזרה לאדמינים ב-Google Workspace מוסבר איך לקבוע לאילו אפליקציות של צד שלישי ואפליקציות פנימיות תהיה גישה לנתונים של Google Workspace, למידע נוסף על האופן שבו האדמין יכול להגביל את הגישה לכל ההיקפים או להיקפים הרגישים והמוגבלים, עד שתוענק גישה מפורשת למזהה הלקוח שלכם ב-OAuth.
disallowed_useragent
נקודת הקצה (endpoint) של ההרשאה מוצגת בתוך סוכן משתמש מוטמע שאסור לפי מדיניות OAuth 2.0 של Google.
Android
מפתחי Android עשויים להיתקל בהודעת השגיאה הזו כשפותחים בקשות הרשאה ב-
android.webkit.WebView
.
במקום זאת, מפתחים צריכים להשתמש בספריות Android, כמו כניסה באמצעות Google ל-Android או AppAuth ל-Android של OpenID Foundation.
הודעת השגיאה הזו עשויה לקרות כשאפליקציה ל-Android פותחת קישור כללי לאינטרנט בסוכן משתמש מוטמע ומשתמש מנווט באתר אל נקודת הקצה להרשאה מסוג OAuth 2.0 של Google באתר שלך. המפתחים צריכים לאפשר לקישורים כלליים להיפתח ב-handler של הקישור שמוגדר כברירת מחדל של מערכת ההפעלה, שכולל את ה-handler של הקישורים לאפליקציות ל-Android וגם את אפליקציית הדפדפן שמוגדרת כברירת מחדל. גם ספריית הכרטיסיות המותאמות ב-Android היא אפשרות נתמכת.
iOS
מפתחי iOS ו-macOS עשויים להיתקל בשגיאה הזו כשהם יפתחו בקשות הרשאה ב-WKWebView
.
במקום זאת, מפתחים צריכים להשתמש בספריות iOS כמו כניסה באמצעות Google ל-iOS או AppAuth ל-iOS של OpenID Foundation.
יכול להיות שמפתחי אתרים ייתקלו בשגיאה הזו כשאפליקציה ל-iOS או ל-macOS פותחת קישור כללי לאינטרנט
בסוכן משתמש מוטמע, כשמשתמש יעבור מהאתר לנקודת הקצה (endpoint) של הרשאת OAuth 2.0 של Google. המפתחים צריכים לאפשר לקישורים כלליים להיפתח ב-handler של הקישור שמוגדר כברירת מחדל
של מערכת ההפעלה, שכולל את ה-handler של
הקישורים האוניברסליים
וגם את אפליקציית ברירת המחדל של הדפדפן. גם הספרייה SFSafariViewController
נתמכת.
org_internal
מזהה הלקוח ב-OAuth שצוין בבקשה הוא חלק מפרויקט שמגביל את הגישה לחשבונות Google ב ארגון ספציפי ב-Google Cloud. מידע נוסף על אפשרות ההגדרה הזו זמין בקטע סוג משתמש במאמר העזרה 'הגדרת מסך ההסכמה ב-OAuth'.
invalid_grant
אם משתמשים
במאמת קוד ואתגר
קוד, הפרמטר code_callenge
חסר או לא תקין. חשוב לוודא
שהפרמטר code_challenge
מוגדר בצורה נכונה.
ברענון של אסימון גישה, יכול להיות שהתוקף של האסימון פג או שהתוקף שלו בוטל. צריך לאמת שוב את המשתמש ולבקש את הסכמת המשתמש כדי לקבל אסימונים חדשים. אם השגיאה הזו ממשיכה להופיע, צריך לוודא שהאפליקציה הוגדרה בצורה תקינה ושהבקשה כוללת את האסימונים והפרמטרים הנכונים. אחרת, יכול להיות שחשבון המשתמש נמחק או הושבת.
redirect_uri_mismatch
ה-redirect_uri
שהועבר בבקשת ההרשאה לא תואם ל-URI מורשה להפניה אוטומטית במזהה הלקוח ב-OAuth. צריך לבדוק את מזהי ה-URI המורשים להפניה אוטומטית ב- Google API Console Credentials page.
יכול להיות שהערך של redirect_uri
שהועבר לא תקין לסוג הלקוח.
יכול להיות שהפרמטר redirect_uri
מתייחס לתהליך של OAuth מחוץ למסגרת (OOB)
שיצא משימוש וכבר לא נתמך. כדי לעדכן את השילוב, אפשר לעיין במדריך להעברת נתונים (מיגרציה).
invalid_request
יש בעיה בבקשה ששלחת. יכולות להיות לכך כמה סיבות:
- פורמט הבקשה שגוי
- בבקשה היו חסרים פרמטרים נדרשים
- הבקשה משתמשת בשיטת הרשאה ש-Google לא תומכת בה. עליך לוודא ששילוב OAuth משתמש בשיטת שילוב מומלצת
- נעשה שימוש בסכימה מותאמת אישית ל-URI להפניה מחדש : אם מופיעה הודעת השגיאה סכימת URI מותאמת אישית לא נתמכת באפליקציות Chrome או סכימת URI מותאמת אישית לא מופעלת בלקוח Android שלך, סימן שאתם משתמשים בסכמת URI מותאמת אישית שלא נתמכת באפליקציות Chrome ומושבתת כברירת מחדל ב-Android. למידע נוסף על חלופות של סכימות URI מותאמות אישית
שלב 4: טיפול בתגובה לשרת OAuth 2.0
האופן שבו האפליקציה מקבלת את תגובת ההרשאה תלוי בסכימת ה-URI להפניה אוטומטית שבה היא משתמשת. בלי קשר לסכימה, התשובה תכיל קוד הרשאה (code
) או שגיאה (error
). לדוגמה, error=access_denied
מציין שהמשתמש דחה את הבקשה.
אם המשתמש מעניק גישה לאפליקציה, אפשר להחליף את קוד ההרשאה באסימון גישה ובאסימון רענון, כפי שמתואר בשלב הבא.
שלב 5: החלפת קוד ההרשאה באסימוני רענון וגישה
כדי להחליף קוד הרשאה באסימון גישה, מפעילים את נקודת הקצה https://oauth2.googleapis.com/token
ומגדירים את הפרמטרים הבאים:
שדות | |
---|---|
client_id |
מזהה הלקוח שהתקבל מ- API Console Credentials page. |
client_secret |
סוד הלקוח שהתקבל מ- API Console Credentials page. |
code |
קוד ההרשאה שהוחזר מהבקשה הראשונית. |
code_verifier |
מאמת הקוד שיצרתם בשלב 1. |
grant_type |
כפי שמוגדר במפרט של OAuth 2.0, הערך בשדה הזה צריך להיות authorization_code . |
redirect_uri |
אחד ממזהי ה-URI להפניה אוטומטית שרשומים לפרויקט שלכם ב- API Console
Credentials page של client_id הנתון. |
קטע הקוד הבא מציג בקשה לדוגמה:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& client_secret=your_client_secret& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Google מגיבה לבקשה הזו על ידי החזרת אובייקט JSON שמכיל אסימון גישה לטווח קצר ואסימון רענון.
התשובה תכיל את השדות הבאים:
שדות | |
---|---|
access_token |
האסימון שהאפליקציה שלכם שולחת כדי לאשר בקשת Google API. |
expires_in |
משך החיים שנותר לאסימון הגישה, בשניות. |
id_token |
הערה: הנכס הזה מוחזר רק אם הבקשה כללה היקף זהות, כמו openid , profile או email . הערך הוא
אסימון אינטרנט מסוג JSON (JWT) שמכיל פרטי זהות של המשתמש עם חתימה דיגיטלית. |
refresh_token |
אסימון שאפשר להשתמש בו כדי לקבל אסימון גישה חדש. אסימוני הרענון תקפים עד שהמשתמש מבטל את הגישה. הערה: אסימוני רענון תמיד מוחזרים עבור אפליקציות מותקנות. |
scope |
היקפי הגישה שהוענקו על ידי access_token , מוצגים כרשימה של מחרוזות תלויות-רישיות שמופרדות ברווחים. |
token_type |
סוג האסימון המוחזר. בשלב הזה, הערך בשדה הזה תמיד מוגדר כ-Bearer . |
בקטע הקוד הבא מוצגת תגובה לדוגמה:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/youtube.force-ssl", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
קריאה ל-Google APIs
אחרי שהאפליקציה מקבלת אסימון גישה, אפשר להשתמש באסימון כדי לבצע קריאות ל-Google API מטעם
חשבון משתמש נתון, אם הוענקו היקפי הגישה שנדרשים על ידי ה-API. כדי לעשות את זה צריך לכלול את אסימון הגישה בבקשה ל-API, על ידי הכללת פרמטר של שאילתה access_token
או ערך Bearer
של כותרת ה-HTTP של Authorization
. כשזה אפשרי, עדיף להשתמש בכותרת ה-HTTP כי מחרוזות השאילתה בדרך כלל גלויות ביומני השרת. ברוב
המקרים אפשר להשתמש בספריית לקוח כדי להגדיר את הקריאות ל-Google APIs (למשל, כששולחים קריאה ל-YouTube Live Streaming API).
שימו לב ש-YouTube Live Streaming API לא תומך בתהליך של חשבון השירות. אין דרך לקשר חשבון שירות לחשבון YouTube, ולכן ניסיונות לאשר בקשות
באמצעות התהליך הזה יגרמו להצגת השגיאה NoLinkedYouTubeAccount
.
תוכלו לנסות את כל ממשקי ה-API של Google ולצפות בהיקפים שלהם ב-OAuth 2.0 Playground.
דוגמאות ל-HTTP GET
קריאה לנקודת הקצה (
liveBroadcasts.list
) (YouTube Live Streaming API) באמצעות כותרת ה-HTTP Authorization: Bearer
עשויה להיראות כך. שימו לב שתצטרכו לציין אסימון גישה משלכם:
GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
זוהי קריאה לאותו API בשביל המשתמש המאומת באמצעות הפרמטר access_token
של מחרוזת השאילתה:
GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
curl
דוגמאות
אפשר לבדוק את הפקודות האלה באמצעות אפליקציית שורת הפקודה curl
. הנה דוגמה שמשתמשת באפשרות של כותרת ה-HTTP (האפשרות המועדפת):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true
לחלופין, אפשרות הפרמטר של מחרוזת השאילתה:
curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
רענון של אסימון גישה
התוקף של אסימוני הגישה פג מדי פעם והם הופכים לפרטי כניסה לא חוקיים לבקשת API קשורה. אם ביקשת גישה אופליין להיקפי ההרשאות שמשויכים לאסימון, אפשר לרענן אסימון גישה בלי לבקש הרשאה מהמשתמש (גם כשהמשתמש לא נמצא).
כדי לרענן אסימון גישה, האפליקציה שולחת בקשת POST
מסוג HTTPS לשרת ההרשאות של Google (https://oauth2.googleapis.com/token
) שכוללת את הפרמטרים הבאים:
שדות | |
---|---|
client_id |
מזהה הלקוח שהתקבל מ- API Console. |
client_secret |
סוד הלקוח שהתקבל מ- API Console.
(ה-client_secret לא רלוונטי לבקשות מלקוחות שרשומים כאפליקציות Android , iOS או Chrome).
|
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
. במקרים של שגיאות, מוחזר קוד הסטטוס 400
של HTTP יחד עם קוד השגיאה.
קריאה נוספת
השיטות המומלצות העדכניות של IETF ל-OAuth 2.0 לאפליקציות נייטיב מבססות הרבה מהשיטות המומלצות שמפורטות כאן.