מסמך זה מסביר איך אפליקציות שמותקנות במכשירים כמו טלפונים, טאבלטים ומחשבים משתמשים בנקודות הקצה של OAuth 2.0 של Google כדי לאשר גישה ל-Google APIs.
פרוטוקול OAuth 2.0 מאפשר למשתמשים לשתף נתונים ספציפיים עם אפליקציה תוך שמירה על הפרטיות של שמות המשתמשים, הסיסמאות ומידע אחר. לדוגמה, אפליקציה יכולה להשתמש ב-OAuth 2.0 כדי לקבל הרשאה מהמשתמשים לאחסן קבצים ב-Google Drive שלהם.
האפליקציות המותקנות מופצות למכשירים נפרדים, וההנחה היא שהאפליקציות לא יכולות לשמור סודות. הם יכולים לגשת ל-Google APIs בזמן שהמשתמש נמצא באפליקציה או בזמן שהאפליקציה פועלת ברקע.
תהליך ההרשאה הזה דומה לתהליך האימות שמשמש לאפליקציות של שרת אינטרנט. ההבדל העיקרי הוא שאפליקציות מותקנות חייבות לפתוח את דפדפן המערכת ולספק URI מקומי להפניה אוטומטית, כדי לטפל בתגובות משרת ההרשאות של Google.
חלופות
באפליקציות לנייד, ייתכן שתעדיפו להשתמש בכניסה באמצעות חשבון Google ל-Android או ל-iOS. ספריות הלקוח לכניסה באמצעות חשבון Google מטפלות באימות ובהרשאות משתמשים, ויכול להיות שיהיה פשוט יותר להטמיע אותן מאשר הפרוטוקול ברמה הנמוכה יותר שמתואר כאן.
למידע על אפליקציות שפועלות במכשירים שלא תומכים בדפדפן מערכת או במכשירים עם יכולות קלט מוגבלות, כמו טלוויזיות, קונסולות משחקים, מצלמות או מדפסות, ראו את המאמר OAuth 2.0 לטלוויזיות ולמכשירים או כניסה בטלוויזיות ובמכשירי קלט מוגבלים.
ספריות ודוגמאות
מומלץ להיעזר בספריות ובדוגמאות הבאות שיעזרו לכם להטמיע את תהליך OAuth 2.0 שמתואר במסמך הזה:
דרישות מוקדמות
הפעלת ממשקי API בפרויקט
כל אפליקציה שקוראת ל-Google APIs צריכה להפעיל את ממשקי ה-API האלה ב- API Console.
כדי להפעיל API בפרויקט:
- Open the API Library ב Google API Console.
- If prompted, select a project, or create a new one.
- בטבלה API Library מפורטים כל ממשקי ה-API הזמינים, בקיבוץ לפי משפחת מוצרים ופופולריות. אם ממשק ה-API שרוצים להפעיל לא מופיע ברשימה, משתמשים בחיפוש כדי למצוא אותו או לוחצים על הצגת הכול במשפחת המוצרים שאליה הוא שייך.
- בוחרים את ממשק ה-API שרוצים להפעיל ולוחצים על הלחצן Enable (הפעלה).
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
יצירת פרטי כניסה להרשאה
לכל אפליקציה שמשתמשת ב-OAuth 2.0 כדי לגשת אל Google APIs, צריכות להיות פרטי כניסה להרשאה שמזהים את האפליקציה לשרת OAuth 2.0 של Google. בשלבים הבאים נסביר איך ליצור פרטי כניסה לפרויקט. לאחר מכן האפליקציות שלך יוכלו להשתמש בפרטי הכניסה כדי לגשת לממשקי API שהפעלת בפרויקט הזה.
- Go to the Credentials page.
- לוחצים על יצירת פרטי כניסה > מזהה לקוח 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. מזהה החבילה מוצג גם בקטע General Information בדף פרטי האפליקציה של האפליקציה באתר App Store Connect של Apple.
- (לא חובה)
יש להזין את המזהה של האפליקציה ב-App Store אם היא פורסמה ב-Apple 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 בדף App Identity בקטע 'ניהול אפליקציות'.
- לוחצים על יצירה.
לאפליקציות UWP, סכימת ה-URI המותאמת אישית לא יכולה להיות ארוכה מ-39 תווים.
סכימת URI מותאמת אישית (Android, iOS, UWP)
סכמות URI בהתאמה אישית הן סוג של קישורי עומק שמשתמשים בסכמה שהוגדרה בהתאמה אישית כדי לפתוח את האפליקציה.
חלופה לשימוש בסכמות URI בהתאמה אישית ב-Androidאפשר להשתמש ב-SDK לכניסה באמצעות חשבון Google ל-Android שמספק את תגובת OAuth 2.0 ישירות לאפליקציה, ללא צורך בהפניה אוטומטית לכתובת URI אחרת.
איך עוברים ל-SDK לכניסה באמצעות חשבון Google ל-Android
אם משתמשים כרגע בסכימה מותאמת אישית לשילוב OAuth ב-Android, צריך להשלים את הפעולות שמפורטות בהמשך כדי לעבור באופן מלא לשימוש בערכת ה-SDK המומלצת לכניסה באמצעות חשבון Google ל-Android SDK:
- צריך לעדכן את הקוד כדי להשתמש ב-SDK לכניסה באמצעות חשבון Google.
- השבתת התמיכה בסכימה מותאמת אישית ב-Google API Console.
כדי לעבור ל-Android SDK לכניסה באמצעות חשבון 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 בצד השרת. זה כולל את השלבים הבאים:
-
משתמשים בשיטה
getServerAuthCode
כדי לאחזר קוד הרשאה להיקפי ההרשאות שעבורם מבקשים הרשאה. - שלח את קוד ההרשאה לקצה העורפי של האפליקציה כדי להחליף אותו באסימון גישה ורענון.
- משתמשים באסימון הגישה שאוחזר כדי לבצע קריאות ל-Google APIs בשם המשתמש.
-
משתמשים בשיטה
-
צריך לבדוק את הקוד כדי לזהות לאן אתם
שולחים בקשה לשרת 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 מסוג לולאה חוזרת (macOS, Linux, Windows במחשב)
כדי לקבל את קוד ההרשאה באמצעות כתובת ה-URL הזו, האפליקציה שלך חייבת להאזין בשרת האינטרנט המקומי. זה אפשרי בהרבה מהפלטפורמות, אבל לא בכולן. עם זאת, אם הפלטפורמה שלך תומכת בכך, זהו המנגנון המומלץ לקבלת קוד ההרשאה.
כשהאפליקציה שלך מקבלת את תגובת ההרשאה, על מנת לאפשר את נוחות השימוש הטובה ביותר, היא צריכה להגיב ולהציג דף HTML שמורה למשתמש לסגור את הדפדפן ולחזור לאפליקציה.
שימוש מומלץ | אפליקציות ל-macOS, Linux ו-Windows במחשבים (אבל לא אפליקציות של Universal Windows Platform) |
ערכי טופס | מגדירים את סוג האפליקציה לאפשרות אפליקציה למחשב. |
העתקה/הדבקה ידנית
זיהוי היקפי גישה
היקפי הרשאות מאפשרים לאפליקציה לבקש גישה רק למשאבים שנחוצים לה, וגם מאפשרים למשתמשים לשלוט בכמות הגישה שהם מעניקים לאפליקציה. לכן יכול להיות קשר הפוך בין מספר ההיקפים המבוקשים לבין הסבירות לקבלת הסכמת המשתמש.
לפני שמתחילים להטמיע הרשאת OAuth 2.0, מומלץ לזהות את ההיקפים שאליהם האפליקציה תצטרך הרשאה כדי לגשת.
המסמך היקפי 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 |
חובה
מזהה הלקוח באפליקציה שלכם. הערך הזה מופיע ב Credentials page API Console. |
||||||
redirect_uri |
חובה
המדיניות זו קובעת את האופן שבו שרת ההרשאות של Google שולח תגובה לאפליקציה שלך. יש כמה אפשרויות זמינות להפניה אוטומטית לאפליקציות מותקנות, ועליך להגדיר את פרטי הכניסה להרשאה עם שיטת הפניה מסוימת מסוימת. הערך צריך להתאים במדויק לאחד ממזהי ה-URI המורשים להפניה אוטומטית בלקוח OAuth 2.0, שהגדרת ב- API Console
Credentials pageשל הלקוח. אם הערך הזה לא תואם ל-URI מורשה, תתקבל הודעת השגיאה בטבלה הבאה מוצג ערך הפרמטר
|
||||||
response_type |
חובה
המדיניות הזו קובעת אם נקודת הקצה (endpoint) של Google OAuth 2.0 תחזיר קוד הרשאה. באפליקציות מותקנות, יש להגדיר את ערך הפרמטר ל- |
||||||
scope |
חובה
רשימה של היקפי הרשאות שמופרדים ברווחים שמציינים את המשאבים שהאפליקציה שלכם יכולה לגשת אליהם בשם המשתמש. הערכים האלה מציינים את מסך ההסכמה ש-Google מציגה למשתמש. היקפי ההרשאות מאפשרים לאפליקציה לבקש גישה רק למשאבים שנחוצים לה, וגם מאפשרים למשתמשים לשלוט בנפח הגישה שהם מעניקים לאפליקציה. לכן יש קשר הפוך בין מספר ההיקפים המבוקשים לבין הסבירות לקבל הסכמה מהמשתמשים. |
||||||
code_challenge |
המלצות
המדיניות מציינת ערך |
||||||
code_challenge_method |
המלצות
המדיניות מציינת את השיטה שבה נעשה שימוש לקידוד |
||||||
state |
המלצות
מציינת כל ערך מחרוזת שהאפליקציה משתמשת בו כדי לשמור על המצב בין בקשת ההרשאה לבין התגובה של שרת ההרשאות.
השרת מחזיר את הערך המדויק ששולחים בתור צמד אפשר להשתמש בפרמטר הזה לכמה מטרות, כמו הפניית המשתמש
למשאב הנכון באפליקציה, שליחת נתונים חד-פעמיים (nonces) וצמצום זיוף בקשות בין אתרים. מאחר שניתן לנחש את |
||||||
login_hint |
אופציונלי
אם האפליקציה שלכם יודעת איזה משתמש מנסה לבצע אימות, היא יכולה להשתמש בפרמטר הזה כדי לספק רמז לשרת האימות של Google. השרת משתמש ברמז כדי לפשט את תהליך ההתחברות על ידי מילוי מראש של שדה האימייל בטופס הכניסה או בחירה בסשן המתאים עם כניסות מרובות. צריך להגדיר את ערך הפרמטר לכתובת אימייל או למזהה |
כתובות URL של הרשאות לדוגמה
הכרטיסיות הבאות מציגות כתובות אתרים של הרשאות לדוגמה, עבור האפשרויות השונות של כתובת אתר להפניה מחדש.
כתובות ה-URL זהות, מלבד הערך של הפרמטר redirect_uri
. כתובות ה-URL
מכילות גם את הפרמטרים response_type
ו-client_id
הנדרשים, וגם
את הפרמטר האופציונלי state
. כל כתובת URL מכילה מעברי שורה ורווחים
כדי להקל על הקריאה.
סכימת URI מותאמת אישית
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& 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=email%20profile& 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
נקודת הקצה של ההרשאה מוצגת בסוכן משתמש מוטמע שאסור לפי מדיניות OAuth 2.0 של Google.
Android
מפתחי Android עשויים להיתקל בהודעת השגיאה הזו כשהם פותחים בקשות הרשאה ב-android.webkit.WebView
.
במקום זאת, מפתחים צריכים להשתמש בספריות ל-Android, כמו
כניסה באמצעות חשבון Google ל-Android או AppAuth ל-Android של OpenID Foundation.
מפתחי אתרים עשויים להיתקל בשגיאה הזו כשאפליקציה ל-Android פותחת קישור כללי לאינטרנט בסוכן משתמש מוטמע, ומשתמש עובר לנקודת הקצה של הרשאת OAuth 2.0 של Google מהאתר שלך. המפתחים צריכים לאפשר לקישורים כלליים להיפתח ב-handler שמוגדר כברירת מחדל לקישורים של מערכת ההפעלה, שכולל גם את ה-handlers של קישורים לאפליקציות ל-Android או את אפליקציית הדפדפן שמוגדרת כברירת מחדל. גם ספריית הכרטיסיות בהתאמה אישית ב-Android נתמכת.
iOS
מפתחים של iOS ו-macOS עשויים להיתקל בשגיאה הזו כשפותחים בקשות הרשאה ב-WKWebView
.
במקום זאת, מפתחים צריכים להשתמש בספריות ל-iOS, כמו כניסה באמצעות חשבון Google ל-iOS או AppAuth ל-iOS של OpenID Foundation.
מפתחי אתרים עשויים להיתקל בשגיאה הזו כשאפליקציה ל-iOS או ל-macOS פותחת קישור כללי לאינטרנט בסוכן משתמש מוטמע, ומשתמש עובר לנקודת הקצה של הרשאת 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/drive.metadata.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
קריאה ל-Google APIs
אחרי שהאפליקציה תקבל אסימון גישה, תהיה לך אפשרות להשתמש באסימון כדי לבצע קריאות ל-Google API מטעם חשבון משתמש מסוים, אם היקפי הגישה הנדרשים ל-API ניתנו. כדי לעשות זאת, צריך לכלול
את אסימון הגישה בבקשה אל ה-API באמצעות פרמטר שאילתה access_token
או ערך Authorization
של כותרת HTTP Bearer
. כשאפשר, עדיף להשתמש בכותרת ה-HTTP, כי מחרוזות השאילתה מופיעות בדרך כלל ביומני השרת. ברוב המקרים,
אפשר להשתמש בספריית לקוח כדי להגדיר את הקריאות ל-Google APIs (לדוגמה,
בקריאה ל-Drive Files API).
אפשר לנסות את כל ממשקי ה-API של Google ולראות את ההיקף שלהם ב-OAuth 2.0 Playground.
דוגמאות GET של HTTP
קריאה לנקודת הקצה
drive.files
(ה-API של Drive Files) באמצעות כותרת ה-HTTP Authorization: Bearer
עשויה להיראות כך. שימו לב שאתם צריכים לציין אסימון גישה משלכם:
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
הנה קריאה לאותו API עבור המשתמש המאומת באמצעות הפרמטר של מחרוזת השאילתה access_token
:
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
curl
דוגמאות
אפשר לבדוק את הפקודות האלה באמצעות אפליקציית שורת הפקודה curl
. הנה דוגמה שמשתמשת באפשרות של כותרת HTTP (מועדף):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
לחלופין, אפשרות הפרמטר של מחרוזת השאילתה:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
רענון אסימון גישה
התוקף של אסימוני הגישה פג מדי פעם והופך לפרטי כניסה לא חוקיים לבקשת API קשורה. אם ביקשתם גישה אופליין להיקפי ההרשאות שמשויכים לאסימון, אפשר לרענן את אסימון הגישה בלי לבקש מהמשתמש הרשאה (גם אם המשתמש לא נוכח).
כדי לרענן אסימון גישה, האפליקציה שלך שולחת בקשת POST
מסוג HTTPS לשרת ההרשאות של Google (https://oauth2.googleapis.com/token
) שכוללת את הפרמטרים הבאים:
שדות | |
---|---|
client_id |
מזהה הלקוח שהתקבל מ- API Console. |
client_secret |
סוד הלקוח שהתקבל מה- API Console.
(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
. לתנאי שגיאה, מוחזר קוד מצב HTTP 400
יחד עם קוד שגיאה.
קריאה נוספת
השיטה המומלצת הנוכחית של IETF OAuth 2.0 לאפליקציות נייטיב מבססת חלק גדול מהשיטות המומלצות שמתוארות כאן.