במסמך הזה מוסבר איך אפליקציות מותקנות במכשירים כמו טלפונים, טאבלטים מחשבים משתמשים בנקודות הקצה מסוג OAuth 2.0 של Google כדי לאשר גישה ממשק ה-API של YouTube Analytics או של YouTube Reporting API.
OAuth 2.0 מאפשר למשתמשים לשתף נתונים ספציפיים עם אפליקציה, תוך שמירה על שמות משתמש, סיסמאות ומידע אחר באופן פרטי. לדוגמה, אפליקציה יכולה להשתמש ב-OAuth 2.0 כדי לקבל הרשאה כדי לאחזר נתוני YouTube Analytics של ערוץ.
האפליקציות המותקנות מופצות למכשירים ספציפיים, וההנחה היא שהאפליקציות האלה אינו יכול לשמור סודות. הם יכולים לגשת אל Google APIs כל עוד המשתמש נמצא באפליקציה או כאשר שהאפליקציה פועלת ברקע.
תהליך ההרשאה הזה דומה לתהליך ההרשאה אפליקציות בשרת האינטרנט. ההבדל העיקרי הוא האפליקציות המותקנות חייבות לפתוח את דפדפן המערכת ולספק URI של הפניה אוטומטית לטיפול תגובות משרת ההרשאות של 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.
- בדף 'ספרייה' תוכלו למצוא ולהפעיל את ממשק ה-API של YouTube Analytics ואת YouTube Reporting API. אפליקציות רבות שמאחזרות נתוני YouTube Analytics מתממשקות גם עם ממשק ה-API של נתוני YouTube. צריך לחפש ממשקי API אחרים שהאפליקציה שלכם תשתמש בהם ולהפעיל גם אותם.
יצירת פרטי כניסה להרשאה
לכל אפליקציה שמשתמשת ב-OAuth 2.0 כדי לגשת ל-Google APIs חייבים להיות פרטי כניסה להרשאה שמשמש לזיהוי האפליקציה בשרת OAuth 2.0 של Google. בשלבים הבאים נסביר איך יוצרים את פרטי הכניסה לפרויקט. לאחר מכן האפליקציות שלך יוכלו להשתמש בפרטי הכניסה כדי לגשת לממשקי API שהפעלתם עבור הפרויקט הזה.
- Go to the Credentials page.
- לוחצים על Create credentials > מזהה הלקוח ב-OAuth.
- הקטעים הבאים מתארים את סוגי הלקוחות ואת שיטות ההפניה מחדש ששרת ההרשאות תומך בכך. צריך לבחור את סוג הלקוח המומלץ ייתן שם ללקוח 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). הערך מוצגת בדרך כלל בחלונית 'כללי' או בחלונית 'חתימה & חלונית היכולות של עורך פרויקט 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 ב זהות האפליקציה בקטע 'ניהול אפליקציות'.
- לוחצים על יצירה.
עבור אפליקציות UWP, סכימת ה-URI המותאמת אישית לא יכולה להיות ארוכה מ-39 תווים.
סכמת URI מותאמת אישית (Android, iOS, UWP)
סכימות URI מותאמות אישית הן סוג של קישורי עומק שמשתמשים בסכימה מוגדרת בהתאמה אישית כדי לפתוח את האפליקציה.
חלופה לשימוש בסכימות URI מותאמות אישית ב-Androidמשתמשים ב כניסה באמצעות חשבון Google ל-Android SDK שמספק את תגובת OAuth 2.0 ישירות לאפליקציה, ומבטל את הצורך URI להפניה אוטומטית.
איך עוברים ל-SDK של כניסה באמצעות חשבון Google ל-Android
אם בחרת להשתמש בסכמה מותאמת אישית לשילוב OAuth ב-Android, צריך: יש להשלים את הפעולות הבאות כדי לעבור באופן מלא לשימוש בכניסה באמצעות חשבון Google המומלצת SDK של Android:
- צריך לעדכן את הקוד כדי להשתמש ב-SDK של כניסה באמצעות Google.
- השבתת התמיכה בסכמה מותאמת אישית במסוף Google API.
כדי לעבור ל-SDK של Android לכניסה באמצעות חשבון Google:
-
צריך לעדכן את הקוד כדי להשתמש בערכת ה-SDK ל-Android לכניסה באמצעות חשבון 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 של סכימה מותאמת אישית להפניה מחדש בדוגמה שלמעלה. לצפייה הגדרת הפרמטרredirect_uri
לפרטים נוספים על הפורמט של הערך המותאם אישית של סכימת ה-URI. -
חשוב לשים לב לפרמטרים של הבקשות
scope
ו-client_id
, יהיה עליך להגדיר את ה-SDK של כניסה באמצעות Google. -
פועלים לפי
שילוב של כניסה באמצעות חשבון Google באפליקציה ל-Android
ההוראות להגדרת ה-SDK. אפשר לדלג על
מקבלים את מזהה הלקוח OAuth 2.0 של שרת הקצה העורפי כמו שעושים בו שימוש חוזר
client_id
שאחזרת מהשלב הקודם. -
פועלים לפי
הפעלת גישה ל-API בצד השרת
הוראות להתאמה אישית. זה כולל את השלבים הבאים:
-
משתמשים בשיטה
getServerAuthCode
כדי לאחזר קוד הרשאה עבור את היקפי ההרשאות שביקשת עבורם הרשאה. - יש לשלוח את קוד ההרשאה לקצה העורפי של האפליקציה כדי להחליף אותו ולקבל גישה לרענן ב-Assistant.
- משתמשים באסימון הגישה שאוחזר כדי לבצע קריאות ל-Google APIs בשם המשתמש.
-
משתמשים בשיטה
-
לבדוק את הקוד כדי לזהות את המיקום שלך
שליחת בקשה לשרת OAuth 2.0 של Google; אם אתם משתמשים בסכמה מותאמת אישית, הבקשה שלכם תיראה כך:
-
השבתת התמיכה בסכמה מותאמת אישית במסוף Google API:
- עוברים אל פרטי כניסה בפרוטוקול OAuth 2.0 ובוחרים את לקוח Android שלכם.
- עוברים לקטע הגדרות מתקדמות ומבטלים את הסימון של התיבה. מפעילים סכימה של URI מותאם אישית ולוחצים על שמירה כדי השבתת התמיכה בסכמת URI מותאמת אישית.
הפעלה של סכימת URI מותאמת אישית
אם החלופה המומלצת לא מתאימה לך, ניתן להפעיל סכימות URI מותאמות אישית עבור בלקוח Android יש לבצע את ההוראות הבאות:- עוברים אל רשימת פרטי כניסה של OAuth 2.0 וגם בוחרים את לקוח Android הרצוי.
- עוברים לקטע הגדרות מתקדמות, ומסמנים את התיבה: הפעל סכימה של URI מותאם אישית, ולחץ על שמור כדי להפעיל תמיכה בסכמת 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, מומלץ לזהות את היקפי ההרשאות שהאפליקציה שלך תצטרך הרשאה כדי לגשת אליה.
ממשק ה-API של YouTube Analytics משתמש בהיקפים הבאים:
היקפים | |
---|---|
https://www.googleapis.com/auth/youtube | נהל את חשבון YouTube שלך |
https://www.googleapis.com/auth/youtube.readonly | צפה בחשבון YouTube שלך |
https://www.googleapis.com/auth/youtubepartner | צפה ונהל את הנכסים שלך ואת התוכן המשויך ב- YouTube |
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | צפה בדוחות YouTube Analytics כספיים ולא כספיים עבור תוכן YouTube שלך |
https://www.googleapis.com/auth/yt-analytics.readonly | צפה בדוחות YouTube Analytics לתוכן YouTube שלך |
YouTube Reporting API משתמש בהיקפים הבאים:
היקפים | |
---|---|
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | צפה בדוחות YouTube Analytics כספיים ולא כספיים עבור תוכן YouTube שלך |
https://www.googleapis.com/auth/yt-analytics.readonly | צפה בדוחות YouTube Analytics לתוכן YouTube שלך |
המסמך היקפי API של OAuth 2.0 מכיל רשימת היקפים שבהם תוכלו להשתמש כדי לגשת ל-Google APIs.
קבלת אסימוני גישה מסוג OAuth 2.0
השלבים הבאים מראים איך האפליקציה מקיימת אינטראקציה עם שרת OAuth 2.0 של Google כדי לקבל הסכמה של משתמש לבצע בקשת API בשם המשתמש. האפליקציה צריכה להכיל את הפרטים האלה הסכמה לפני שיוכל להוציא לפועל בקשת Google API שמחייבת הרשאת משתמש.
שלב 1: יוצרים מאמת קוד ואתגר
Google תומכת במפתח הוכחה עבור 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 מציגה משתמש. היקפי הרשאות מאפשרים לאפליקציה לבקש גישה רק למשאבים שהיא צריכה ובמקביל גם מאפשרים למשתמשים לשלוט בכמות הגישה שהם מעניקים תרגום מכונה. כך יש קשר הפוך בין מספר ההיקפים המבוקשים והסבירות לקבל את הסכמת המשתמש. ממשק ה-API של YouTube Analytics משתמש בהיקפים הבאים:
YouTube Reporting API משתמש בהיקפים הבאים:
המסמך היקפי API של OAuth 2.0 מספק רשימה מלאה של היקפים שבהם תוכלו להשתמש כדי לגשת ל-Google APIs. |
||||||||||||||||||
code_challenge |
המלצות
המדיניות הזו מציינת |
||||||||||||||||||
code_challenge_method |
המלצות
מציינת את השיטה ששימשה לקידוד |
||||||||||||||||||
state |
המלצות
מציינת כל ערך מחרוזת שהאפליקציה שלכם משתמשת בו כדי לשמור על מצב בין
בקשת ההרשאה והתגובה של שרת ההרשאות.
השרת מחזיר את הערך המדויק שאתם שולחים בתור צמד אפשר להשתמש בפרמטר הזה לכמה מטרות, כמו הפניית המשתמש אל
המשאב הנכון באפליקציה, שליחת צפנים חד-פעמיים וצמצום בקשות בין אתרים
מזויף. מכיוון שניתן לנחש את |
||||||||||||||||||
login_hint |
אופציונלי
אם האפליקציה מזהה איזה משתמש מנסה לבצע אימות, היא יכולה להשתמש בפרמטר הזה כדי לספק רמז לשרת האימות של Google. השרת משתמש ברמז כדי מפשטים את תהליך ההתחברות: ממלאים מראש את שדה האימייל בטופס הכניסה או בחירת הסשן המתאים של ריבוי כניסות. מגדירים את ערך הפרמטר לכתובת אימייל או למזהה |
דוגמאות לכתובות URL של הרשאות
הכרטיסיות הבאות מציגות כתובות URL של הרשאות לדוגמה עבור האפשרויות השונות של כתובות URI להפניה מחדש.
כל כתובת URL מבקשת גישה להיקף שמאפשר גישה לאחזור דוחות של YouTube Analytics.כתובות ה-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%2Fyt-analytics.readonly& 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%2Fyt-analytics.readonly& 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 לא יכול לתת הרשאה להיקף בקשה אחד או יותר, עקב המדיניות של של האדמין ב-Google Workspace. למאמר העזרה לאדמינים ב-Google Workspace. בחירת צדדים שלישיים אפליקציות פנימיות ניגשות לנתונים של Google Workspace לקבלת מידע נוסף על האופן שבו מנהל עשוי להגביל את הגישה לכל היקפי ההרשאות או היקפים מוגבלים עד שהגישה תוענק במפורש למזהה הלקוח שלכם ב-OAuth.
disallowed_useragent
נקודת הקצה (endpoint) של ההרשאה מוצגת בתוך סוכן משתמש מוטמע שאסור להפעיל על ידי Google כללי מדיניות OAuth 2.0.
Android
מפתחי Android עשויים להיתקל בהודעת השגיאה הזו כשהם פותחים בקשות הרשאה ב
android.webkit.WebView
מפתחים צריכים להשתמש במקום זאת בספריות Android כמו
כניסה באמצעות חשבון Google ל-Android או OpenID Foundation
AppAuth ל-Android.
מפתחי אתרים עשויים להיתקל בשגיאה הזו כשאפליקציה ל-Android פותחת קישור כללי לאינטרנט סוכן משתמש מוטמע ומשתמש מנווט לנקודת הקצה של הרשאת OAuth 2.0 של Google דרך באתר שלך. המפתחים צריכים לאפשר לקישורים כלליים להיפתח ב-handler של הקישור שמוגדר כברירת מחדל של במערכת ההפעלה, שכוללת גם קישורים לאפליקציות ל-Android או את אפליקציית ברירת המחדל של הדפדפן. כרטיסיות מותאמות אישית ב-Android היא גם אפשרות נתמכת.
iOS
מפתחי iOS ו-macOS עשויים להיתקל בשגיאה הזו כשהם יפתחו בקשות הרשאה
WKWebView
מפתחים צריכים במקום זאת להשתמש בספריות iOS כמו
כניסה באמצעות חשבון Google ל-iOS או OpenID Foundation
AppAuth ל-iOS.
מפתחי אתרים עשויים להיתקל בשגיאה הזו כשאפליקציה ל-iOS או ל-macOS פותחת קישור כללי לאינטרנט
סוכן משתמש מוטמע ומשתמש מנווט לנקודת הקצה של הרשאת OAuth 2.0 של Google דרך
באתר שלך. המפתחים צריכים לאפשר לקישורים כלליים להיפתח ב-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) שכולל
הוצא משימוש ולא נתמך יותר. עיינו ב
מדריך ההעברה כדי לעדכן את
של Google Analytics.
invalid_request
יש בעיה בבקשה ששלחת. יכולות להיות לכך כמה סיבות:
- פורמט הבקשה שגוי
- בבקשה היו חסרים פרמטרים נדרשים
- הבקשה משתמשת בשיטת הרשאה ש-Google לא תומכת בה. אימות OAuth משתמשת בשיטת שילוב מומלצת.
- נעשה שימוש בסכימה מותאמת אישית עבור ה-URI להפניה מחדש : אם מופיעה הודעת השגיאה סכימת URI מותאמת אישית אינה נתמכת באפליקציות Chrome או בסכימת URI מותאמת אישית אינו מופעל עבור לקוח Android שלך, המשמעות היא שאתה משתמש ב-URI מותאם אישית סכמה שאינה נתמכת באפליקציות Chrome ומושבתת כברירת מחדל ב- Android. למידע נוסף על סכימת URI מותאמת אישית חלופות
שלב 4: טיפול בתגובה לשרת OAuth 2.0
האופן שבו האפליקציה מקבלת את תגובת ההרשאה תלוי
את סכימת ה-URI להפניה אוטומטית שבה היא משתמשת. בלי קשר לסכימה,
התגובה תכיל קוד הרשאה (code
) או שגיאה
(error
). לדוגמה, error=access_denied
מציין שהמשתמש
דחה את הבקשה.
אם המשתמש מעניק גישה לאפליקציה, ניתן להחליף את קוד ההרשאה אסימון גישה ואסימון רענון, כפי שמתואר בשלב הבא.
שלב 5: קוד ההרשאה של Exchange לרענון וגישה אסימונים
כדי להחליף קוד הרשאה באסימון גישה, קוראים אל
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/yt-analytics.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
קריאה ל-Google APIs
לאחר שהאפליקציה שלך מקבלת אסימון גישה, אפשר להשתמש באסימון כדי לבצע קריאות
API בשם נתון
חשבון משתמש, אם היקפי הגישה הנדרשים על ידי ה-API הוענקו. כדי לעשות את זה, צריך לכלול
אסימון הגישה בבקשה ל-API על ידי הכללת שאילתת access_token
או ערך Bearer
של כותרת HTTP בAuthorization
. כשהדבר אפשרי,
עדיף להשתמש בכותרת HTTP, כי מחרוזות השאילתה בדרך כלל גלויות ביומני השרת. במרבית
במקרים מסוימים תוכלו להשתמש בספריית לקוח כדי להגדיר את הקריאות ל-Google APIs (לדוגמה,
שליחת קריאה ל-YouTube Analytics API).
שימו לב ש-YouTube Analytics API לא תומך בחשבון השירות . YouTube Reporting API תומך בחשבונות שירות רק עבור בעלי תוכן ב-YouTube שהם הבעלים והמנהלים של כמה ערוצי YouTube, כמו בתור לייבלים ואולפני קולנוע.
אפשר לנסות את כל ממשקי ה-API של Google ולצפות בהיקף שלהם בקישור OAuth 2.0 Playground
דוגמאות ל-HTTP GET
קריאה ל
reports.query
נקודת קצה (API של YouTube Analytics) באמצעות Authorization: Bearer
HTTP
עשויה להיראות כך. שימו לב שתצטרכו לציין אסימון גישה משלכם:
GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
זוהי קריאה לאותו API בשביל המשתמש המאומת באמצעות access_token
פרמטר של מחרוזת שאילתה:
GET https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
curl
דוגמאות
אפשר לבדוק את הפקודות האלה באמצעות אפליקציית שורת הפקודה curl
. הנה
דוגמה שמשתמשת באפשרות של כותרת HTTP (מועדף):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
לחלופין, אפשרות הפרמטר של מחרוזת השאילתה:
curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
רענון של אסימון גישה
התוקף של אסימוני הגישה פג מדי פעם והם הופכים לפרטי כניסה לא חוקיים לבקשת API קשורה. שלך יכול לרענן אסימון גישה בלי לבקש הרשאה מהמשתמש (גם כשהמשתמש לא קיים) אם ביקשת גישה אופליין להיקפי ההרשאות שמשויכים לאסימון.
כדי לרענן אסימון גישה, האפליקציה שולחת כתובת URL מסוג HTTPS מסוג POST
לשרת האימות של 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" }
חשוב לשים לב שיש הגבלות על מספר אסימוני הרענון שיונפקו. מגבלה אחת לכל שילוב של לקוח/משתמש ושילוב נוסף לכל משתמש בכל הלקוחות. עליך לשמור אסימוני רענון באחסון לטווח ארוך ולהמשיך להשתמש בהם כל עוד הם בתוקף. אם הבקשה שלכם מבקשת יותר מדי אסימוני רענון, היא עלולה להגיע למגבלות האלה. במקרה כזה, אסימוני רענון ישנים יותר יפסיקו לפעול.
ביטול אסימון
במקרים מסוימים משתמש עשוי לבטל את הגישה שניתנה לאפליקציה. משתמש יכול לבטל את הגישה על ידי ביקור בכתובת הגדרות חשבון. לצפייה הסרה קטע הגישה של האתר או האפליקציה באתרים של צדדים שלישיים אפליקציות עם גישה לחשבון מסמך תמיכה של Google לקבלת מידע נוסף.
אפשר גם שאפליקציה יכולה לבטל באופן פרוגרמטי את הגישה שהוענקה לה. ביטול פרוגרמטי חשוב במקרים שבהם משתמש מבטל את ההרשמה ומסיר או משאבי ה-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
עם קוד שגיאה.
קריאה נוספת
השיטות המומלצות העדכניות ביותר של IETF ל-OAuth 2.0 עבור אפליקציות נייטיב מבוססות על חלק גדול מהשיטות המומלצות שמתוארות כאן.
יישום הגנה על כל החשבונות
פעולה נוספת שצריך לבצע כדי להגן על המשתמשים משתמשים בחשבונות שונים הגנה על ידי שימוש בשירות ההגנה על כל החשבונות של 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
לצפייה הגנה על חשבונות משתמשים באמצעות הדף 'הגנה על כל החשבונות' כדי לקבל מידע נוסף על ההטמעה של הגנה על כל החשבונות ולרשימה המלאה של האירועים הזמינים.