במסמך הזה מוסבר איך אפליקציות שמותקנות במכשירים כמו טלפונים, טאבלטים ומחשבים משתמשות בנקודות הקצה של OAuth 2.0 של Google כדי לאשר גישה ל-Google APIs.
פרוטוקול OAuth 2.0 מאפשר למשתמשים לשתף נתונים ספציפיים עם אפליקציה מסוימת, תוך שמירה על פרטיות שמות המשתמשים, הסיסמאות ומידע אחר. לדוגמה, אפליקציה יכולה להשתמש ב-OAuth 2.0 כדי לקבל הרשאה ממשתמשים לאחסן קבצים ב-Google Drive שלהם.
אפליקציות מותקנות מותקנות במכשירים נפרדים, הם יכולים לגשת לממשקי Google API בזמן שהמשתמש קיים באפליקציה או כאשר האפליקציה פועלת ברקע.
תהליך ההרשאה דומה לזה המשמש לאפליקציות של שרת אינטרנט. ההבדל העיקרי הוא שהאפליקציות המותקנות חייבות לפתוח את דפדפן המערכת ולספק 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 Library מופיעים כל ממשקי ה-API הזמינים, מקובצים לפי משפחת מוצרים ופופולריות. אם ממשק ה-API שרוצים להפעיל לא מופיע ברשימה, משתמשים בחיפוש כדי למצוא אותו או לוחצים על הצגת הכול במשפחת המוצרים שאליה הוא שייך.
- בוחרים ב-API שרוצים להפעיל ולוחצים על הלחצן הפעלה.
- 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.
- לוחצים על Create credentials > OAuth client ID (יצירת פרטי כניסה > מזהה לקוח ב-OAuth).
- בקטעים שבהמשך מתוארים סוגי הלקוחות ושיטות הפנייה, שנתמכות על ידי שרת ההרשאות של Google. עליך לבחור את סוג הלקוח המומלץ לאפליקציה שלך, לתת שם ללקוח OAuth ולהגדיר את שאר השדות בטופס בהתאם.
סכימת URI מותאמת אישית (Android, iOS, UWP)
מומלץ להשתמש בסכימת URI מותאמת אישית עבור אפליקציות ל-Android, אפליקציות ל-iOS ואפליקציות Universal Windows Platform (UWP).
Android
- בוחרים בסוג האפליקציה Android.
- נותנים שם ללקוח OAuth. השם הזה מוצג ב- Credentials page של הפרויקט כדי לזהות את הלקוח.
- יש להזין את שם החבילה של האפליקציה ל-Android. הערך הזה מוגדר
במאפיין
package
של הרכיב<manifest>
בקובץ המניפסט של האפליקציה. - מזינים את טביעת האצבע של אישור החתימה SHA-1 של הפצת האפליקציה.
- אם האפליקציה שלך משתמשת בחתימת אפליקציות ב-Google Play, יש להעתיק את טביעת האצבע SHA-1 מדף חתימת האפליקציות ב-Play Console.
- אם את/ה מנהל/ת מאגר מפתחות או חתימות משלך, עליך להשתמש בכלי כלי המפתח
הכולל את Java כדי להדפיס פרטי אישורים בפורמט קריא למשתמשים. יש להעתיק את הערך
SHA1
בקטעCertificate fingerprints
בפלט של keytool. מידע נוסף זמין במאמר אימות הלקוח שלך במסמכי התיעוד של Google APIs ל-Android.
- לוחצים על יצירה.
iOS
- בוחרים בסוג האפליקציה iOS.
- נותנים שם ללקוח OAuth. השם הזה מוצג ב- Credentials page של הפרויקט כדי לזהות את הלקוח.
- יש להזין את מזהה החבילה של האפליקציה. מזהה החבילה הוא הערך של המפתח CFBundleIdentifier בקובץ המשאב של רשימת הנכסים באפליקציה (info.plist). לרוב, הערך הזה מופיע בחלונית הכללית או בחלונית החתימה והיכולות של עורך הפרויקטים ב-Xcode. מזהה החבילה מוצג גם בקטע 'מידע כללי' בדף 'פרטי האפליקציה' של האפליקציה באתר של App Store Connect של Apple.
- (לא חובה)
אם האפליקציה פורסמה ב-App Store של Apple, יש להזין את המזהה שלה. מזהה החנות הוא מחרוזת מספרית שמופיעה בכל כתובת URL של Apple App Store.
- פותחים את אפליקציית Apple App Store במכשיר iOS או iPadOS.
- מחפשים את האפליקציה.
- בוחרים בלחצן 'שיתוף' (הסמל מרובע וחץ למעלה).
- בוחרים באפשרות העתקת קישור.
- מדביקים את הקישור בכלי לעריכת טקסט. מזהה App Store הוא החלק האחרון של כתובת האתר.
לדוגמה:
https://apps.apple.com/app/google/id284815942
- (לא חובה)
יש להזין את מזהה הצוות. למידע נוסף, אפשר לקרוא את המאמר איתור מזהה הצוות במסמכי התיעוד של חשבון הפיתוח ב-Apple.
- לוחצים על יצירה.
ארגון UWP
- בוחרים בסוג האפליקציה Universal Windows Platform.
- נותנים שם ללקוח OAuth. השם הזה מוצג ב- Credentials page של הפרויקט כדי לזהות את הלקוח.
- מזינים את מזהה Microsoft Store בן 12 התווים של האפליקציה. אפשר למצוא את הערך הזה ב-Microsoft Partner Center בדף Identity של האפליקציה בקטע 'ניהול אפליקציות'.
- לוחצים על יצירה.
באפליקציות UWP, סכימת ה-URI המותאמת אישית לא יכולה להיות ארוכה מ-39 תווים.
כתובת IP של הלולאה החוזרת (macOS, Linux, Windows Desktop)
כדי לקבל את קוד ההרשאה באמצעות כתובת ה-URL הזו, האפליקציה שלך צריכה להאזין לשרת האינטרנט המקומי. הדבר אפשרי בפלטפורמות רבות, אך לא בכולן. עם זאת, אם הפלטפורמה תומכת בכך, זה המנגנון המומלץ לקבלת קוד ההרשאה.
כשהאפליקציה מקבלת את תגובת ההרשאה, היא צריכה להגיב על ידי הצגת דף HTML שמנחה את המשתמש לסגור את הדפדפן ולחזור לאפליקציה.
שימוש מומלץ | אפליקציות ל-macOS, ל-Linux ול-Windows במחשב (אבל לא ב-Universal Windows Platform) |
ערכי טופס | להגדיר את סוג האפליקציה כאפליקציה למחשב. |
העתקה/הדבקה ידנית
זיהוי היקפי גישה
היקפי ההרשאות מאפשרים לאפליקציה לבקש גישה רק למשאבים הדרושים לה, וכן מאפשרים למשתמשים לשלוט בכמות הגישה שהם מעניקים לאפליקציה. כתוצאה מכך, יכול להיות שיש קשר הפוך בין מספר ההיקפים שמבקשים לבין הסבירות לקבלת הסכמה מהמשתמשים.
לפני הטמעת הרשאת OAuth 2.0, מומלץ לזהות את היקפי ההרשאות שהאפליקציה שלך צריכה עבורם הרשאת גישה.
במסמך OAuth 2.0 API Scopes יש רשימה מלאה של היקפי הרשאות שאפשר להשתמש בהם כדי לקבל גישה ל-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 (ללא מרווח פנימי) של מאמת הקוד.
|
plain (רגיל) | אתגר הקוד זהה לערך של מאמת הקוד שנוצר למעלה.
|
שלב 2: שליחת בקשה לשרת OAuth 2.0 של Google
כדי לקבל הרשאת משתמש, יש לשלוח בקשה לשרת ההרשאות של Google בכתובת
https://accounts.google.com/o/oauth2/v2/auth
. נקודת הקצה הזו מטפלת בחיפוש פעיל של ביקורים, מאמתת את המשתמש ומקבלת את הסכמת המשתמשים. ניתן לגשת לנקודת הקצה רק באמצעות 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 מציגה למשתמש. ההיקפים מאפשרים לאפליקציה לבקש גישה רק למשאבים הנדרשים, אבל במקביל מאפשרים למשתמשים לשלוט בכמות הגישה שהם מעניקים לאפליקציה. כתוצאה מכך, יש קשר הפוך בין מספר ההיקפים שהתבקשו לבין הסבירות לקבלת הסכמה מהמשתמשים. |
||||||
code_challenge |
מומלץ
מציין |
||||||
code_challenge_method |
מומלץ
המדיניות מציינת את השיטה ששימשה לקידוד |
||||||
state |
מומלץ
המדיניות הזו קובעת את ערך המחרוזת שמשמש את האפליקציה כדי לשמור על המצב בין בקשת ההרשאה שלך לבין התגובה של שרת ההרשאות.
השרת מחזיר את הערך המדויק ששלחת כצמד אפשר להשתמש בפרמטר הזה לכמה מטרות, למשל הפניית המשתמש למשאב הנכון באפליקציה, שליחת מחרוזות ופתרון זיוף של בקשה בין אתרים. מכיוון שאפשר לנחש את |
||||||
login_hint |
אופציונלי
אם האפליקציה יודעת איזה משתמש מנסה לאמת, היא יכולה להשתמש בפרמטר הזה כדי לספק רמז לשרת האימות של Google. השרת משתמש ברמז כדי לפשט את תהליך ההתחברות על ידי מילוי מראש של שדה האימייל בטופס הכניסה או על ידי בחירת ההפעלה המתאימה להתחברות עם מספר חשבונות. צריך להגדיר את ערך הפרמטר לכתובת אימייל או למזהה |
דוגמאות של כתובות URL להרשאות
הכרטיסיות הבאות מציגות כתובות URL לדוגמה של הרשאות לאפשרויות ה-URI השונות להפניה אוטומטית.
כתובות ה-URL זהות מלבד הערך של הפרמטר redirect_uri
. כתובות ה-URL מכילות גם את הפרמטרים הנדרשים של response_type
, client_id
וגם את הפרמטר האופציונלי state
. כל כתובת URL מכילה מעברי שורה ורווחים
כך שניתן יהיה לקרוא אותם.
סכימת URI מותאמת אישית
https://accounts.google.com/o/oauth2/v2/auth? scope=& 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 של הלולאה החוזרת (loopback)
https://accounts.google.com/o/oauth2/v2/auth? scope=& 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 מציגה חלון הסכמה שמציג את שם האפליקציה ושירותי ה-API של Google שאליהם היא מבקשת הרשאה, באמצעות פרטי הכניסה של המשתמש לאישור וסיכום של היקפי הגישה שאפשר להעניק. לאחר מכן, המשתמש יוכל להסכים להעניק גישה להיקפים בהיקף אחד או יותר שצוינו בבקשה שלך או לדחות את הבקשה.
האפליקציה שלך לא צריכה לעשות דבר בשלב הזה, כי היא ממתינה לתגובה משרת OAuth 2.0 של Google, המציינת אם ניתנה גישה כלשהי. התשובה הזו מוסברת בשלב הבא.
שגיאות
בקשות לנקודת הקצה של Google OAuth 2.0 עשויות להציג הודעות שגיאה שמוצגות למשתמשים, במקום לתהליכי האימות וההרשאה הרצויים. בהמשך מפורטים קודי שגיאה נפוצים והצעות לפתרונות.
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 Custom Tabs.
iOS
המפתחים של iOS ו-macOS עשויים להיתקל בשגיאה הזו כשפותחים בקשות הרשאה ב-WKWebView
.
במקום זאת, מפתחים צריכים להשתמש בספריות iOS, כמו
כניסה באמצעות חשבון Google ל-iOS או AppAuth ל-iOS של OpenID Foundation.
מפתחי האתרים עשויים להיתקל בשגיאה הזו כשאפליקציה ל-iOS או ל-macOS פותחת קישור אינטרנט כללי בסוכן משתמש מוטמע, ומשתמש מנווט לאתר דרך נקודת הקצה של OAuth 2.0 של Google. המפתחים צריכים לאפשר לקישורים כלליים להיפתח בברירת המחדל של handlers לקישורים של מערכת ההפעלה, שכוללת את ה-handlers של Universal Links ואת אפליקציית הדפדפן שמוגדרת כברירת מחדל. גם הספרייה SFSafariViewController
היא אפשרות נתמכת.
org_internal
מספר הלקוח ב-OAuth בבקשה הוא חלק מפרויקט שמגביל את הגישה לחשבונות Google ב ארגון ספציפי של Google Cloud. מידע נוסף על אפשרות ההגדרה הזו מופיע בקטע סוג משתמש במאמר העזרה בנושא הגדרת מסך ההסכמה ל-OAuth.
invalid_grant
אם משתמשים במאמת קוד
ובאתגר, הפרמטר code_callenge
לא חוקי או חסר. יש לוודא שהפרמטר
code_challenge
מוגדר כראוי.
ברענון של אסימון גישה, יכול להיות שפג תוקפו של האסימון או שהוא בוטל. צריך לאמת שוב את המשתמש ולבקש את הסכמת המשתמש כדי לקבל אסימונים חדשים. אם השגיאה הזו ממשיכה להופיע, עליך לוודא שהאפליקציה שלך מוגדרת נכון ושהשתמשת באסימונים ובפרמטרים הנכונים בבקשה. אחרת, יכול להיות שחשבון המשתמש נמחק או הושבת.
redirect_uri_mismatch
redirect_uri
שהועבר בבקשת ההרשאה לא תואם ל-URI המוקצה להפניה מחדש עבור מספר הלקוח ב-OAuth. יש לבדוק את ה-URIs המותרים להפניה מחדש ב- Google API Console Credentials page.
ייתכן שהערך שצוין בשדה redirect_uri
לא חוקי בסוג הלקוח.
הפרמטר redirect_uri
עשוי להתייחס לזרימת OAuth מחוץ למסגרת (OOB) שהוצאה משימוש ואינה נתמכת יותר. יש לעיין
במדריך להעברה כדי לעדכן את
האינטגרציה שלך.
שלב 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 |
האסימון שהאפליקציה שלך שולחת כדי לאשר בקשת API של Google. |
expires_in |
משך החיים הנותר של אסימון הגישה בשניות. |
id_token |
הערה: הנכס הזה מוחזר רק אם הבקשה שלך כללה היקף זהות, כמו openid , profile או email . הערך הוא אסימון Web 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
או ערך Bearer
של כותרת HTTP מסוג Authorization
. עדיף להשתמש בכותרת HTTP, כי מחרוזות השאילתה בדרך כלל גלויות ביומני השרת. ברוב המקרים
אפשר להשתמש בספריית לקוח כדי להגדיר קריאות ל-Google APIs (לדוגמה, כשמתבצעת קריאה ל-ב-Drive Files API).
אפשר לנסות את כל ממשקי ה-API של Google ולהציג את ההיקפים שלהם במגרש המשחקים של OAuth 2.0.
דוגמאות ל-HTTP GET
קריאת לנקודת הקצה
drive.files
(ב-Drive Files API) באמצעות כותרת ה-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 קשורה. אפשר לרענן אסימון גישה בלי לבקש הרשאה מהמשתמשים (כולל כשהמשתמש לא נוכח) אם ביקשת גישה אופליין להיקפי ההרשאות המשויכים לאסימון.
כדי לרענן אסימון גישה, האפליקציה שולחת בקשת 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" }
חשוב לשים לב שיש מגבלה על מספר אסימוני הרענון שיונפקו; מגבלה אחת לכל שילוב לקוח/משתמש ומגבלה לכל משתמש לכל הלקוחות. כדאי לשמור אסימוני רענון בטווח הארוך ולהמשיך להשתמש בהם כל עוד הם בתוקף. אם האפליקציה שלך מבקשת יותר מדי אסימוני רענון, היא עשויה לחרוג מהמגבלות האלה. במקרה כזה, אסימוני רענון ישנים יותר יפסיקו לפעול.
ביטול אסימון
במקרים מסוימים, ייתכן שמשתמש ירצה לבטל גישה שניתנה לו. משתמש יכול לבטל גישה על ידי מעבר אל הגדרות חשבון. למידע נוסף, אפשר לעיין בקטע הסרת הגישה של אתר או אפליקציה לאתרים ולאפליקציות של צד שלישי בעלי גישה לחשבון שלך.
בנוסף, יכול להיות שאפליקציה תבטל באופן פרוגרמטי את הגישה שהוענקה לה. ביטול פרוגרמטי חשוב במקרים שבהם משתמש מבטל מינוי, מסיר אפליקציה או שהמשאבים ל-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 עבור אפליקציות מותאמות של IETF.