ממשקי ה-API של Google משתמשים ב פרוטוקול OAuth 2.0 לאימות ולהרשאה. Google תומכת בתרחישים נפוצים של OAuth 2.0, כמו אלה של שרת אינטרנט, צד לקוח, אפליקציות מותקנות ואפליקציות במכשירים עם יכולות קלט מוגבלות.
כדי להתחיל, צריך לקבל פרטי כניסה של לקוח OAuth 2.0 מ- Google API Console. לאחר מכן, אפליקציית הלקוח מבקשת אסימון גישה משרת ההרשאות של Google, מחלצת אסימון מהתגובה ושולחת את האסימון ל-Google API שאליו רוצים לגשת. כדי לראות הדגמה אינטראקטיבית של השימוש ב-OAuth 2.0 עם Google (כולל האפשרות להשתמש בפרטי הכניסה של הלקוח שלכם), אתם יכולים להתנסות ב-OAuth 2.0 Playground.
בדף הזה מופיעה סקירה כללית של תרחישי ההרשאה של OAuth 2.0 שנתמכים ב-Google, וקישורים לתוכן מפורט יותר. לפרטים על השימוש ב-OAuth 2.0 לאימות, קראו את המאמר OpenID Connect.
שלבים בסיסיים
כל האפליקציות פועלות לפי דפוס בסיסי כשהן ניגשות ל-Google API באמצעות OAuth 2.0. באופן כללי, יש חמישה שלבים:
1. מקבלים פרטי כניסה ל-OAuth 2.0 מ-Google API Console.
נכנסים אל Google API Console כדי לקבל פרטי כניסה ל-OAuth 2.0, כמו מזהה לקוח וסוד לקוח, שמוכרים גם ל-Google וגם לאפליקציה שלכם. קבוצת הערכים משתנה בהתאם לסוג האפליקציה שאתם מפתחים. לדוגמה, אפליקציית JavaScript לא דורשת סוד, אבל אפליקציית שרת אינטרנט כן.
צריך ליצור לקוח OAuth שמתאים לפלטפורמה שבה האפליקציה תפעל, לדוגמה:
- באפליקציות ל-Android, משתמשים בסוג האפליקציה Android.
-
באפליקציות ל-iOS, משתמשים בסוג האפליקציה iOS.
- desktop_windows באפליקציות למחשב (כמו אפליקציות ל-Windows, ל-macOS או ל-Linux, או כלי CLI), משתמשים בסוג האפליקציה אפליקציה למחשב.
- code באפליקציות אינטרנט בצד השרת או אפליקציות אינטרנט ב-JavaScript, צריך להשתמש בסוג האפליקציה Web application. אל תשתמשו בסוג האפליקציה הזה לאפליקציות אחרות, כמו אפליקציות מקוריות או אפליקציות לנייד.
- chrome_extension לתוספים ל-Chrome, משתמשים בסוג האפליקציה תוסף ל-Chrome.
- tv במכשירים עם יכולות קלט מוגבלות, כמו טלוויזיות או מכשירים מוטמעים, משתמשים בסוג האפליקציה טלוויזיות ומכשירים עם יכולות קלט מוגבלות.
- host לאינטראקציות בין שרתים, משתמשים בחשבונות שירות. לא צריך מזהה לקוח ב-OAuth.
2. מקבלים טוקן גישה משרת ההרשאות של Google.
כדי שהאפליקציה תוכל לגשת לנתונים פרטיים באמצעות Google API, היא צריכה לקבל טוקן גישה שמעניק גישה לאותו API. טוקן גישה אחד יכול להעניק רמות גישה שונות לכמה ממשקי API. פרמטר משתנה שנקרא scope שולט בקבוצת המשאבים והפעולות שטוקן הגישה מאפשר. במהלך הבקשה לטוקן גישה, האפליקציה שולחת ערך אחד או יותר בפרמטר scope.
יש כמה דרכים לשלוח את הבקשה הזו, והן משתנות בהתאם לסוג האפליקציה שאתם מפתחים. לדוגמה, אפליקציית JavaScript יכולה לבקש טוקן גישה באמצעות הפניית דפדפן ל-Google, ואפליקציה שמותקנת במכשיר ללא דפדפן משתמשת בבקשות לשירות אינטרנט. למידע נוסף על אופן ביצוע הבקשה, עיינו בScenarios ובמדריכי ההטמעה המפורטים לכל סוג אפליקציה.
בחלק מהבקשות נדרש שלב אימות שבו המשתמש מתחבר באמצעות חשבון Google שלו. אחרי ההתחברות, המשתמש נשאל אם הוא מוכן להעניק הרשאה אחת או יותר שהאפליקציה מבקשת. התהליך הזה נקרא הסכמת משתמש.
אם המשתמש נותן לפחות הרשאה אחת, שרת ההרשאות של Google שולח לאפליקציה טוקן גישה (או קוד הרשאה שהאפליקציה יכולה להשתמש בו כדי לקבל טוקן גישה) ורשימה של היקפי הגישה שהטוקן הזה נותן. אם המשתמש לא נותן את ההרשאה, השרת מחזיר שגיאה.
באופן כללי, מומלץ לבקש היקפי הרשאות באופן מצטבר, בזמן שבו נדרשת הגישה, ולא מראש. לדוגמה, אפליקציה שרוצה לתמוך בשמירת אירוע ביומן לא צריכה לבקש גישה ליומן Google עד שהמשתמש לוחץ על הלחצן "הוספה ליומן". מידע נוסף זמין במאמר הרשאה מצטברת.
3. בודקים את היקפי הגישה שהמשתמש נתן.
משווים בין היקפי ההרשאות שכלולים בתגובה של טוקן הגישה לבין היקפי ההרשאות שנדרשים כדי לגשת לתכונות ולפונקציונליות של האפליקציה, שתלויות בגישה ל-Google API קשור. משביתים את כל התכונות באפליקציה שלא יכולות לפעול בלי גישה ל-API הרלוונטי.
יכול להיות שההיקף שכלול בבקשה לא יהיה זהה להיקף שכלול בתגובה, גם אם המשתמש אישר את כל ההיקפים שהתבקשו. כדי לדעת מהם היקפי ההרשאות שנדרשים לגישה, עיינו במסמכי התיעוד של כל אחד מממשקי ה-API של Google. יכול להיות ש-API ימפה כמה ערכי מחרוזת של היקף הרשאות להיקף גישה אחד, ויחזיר את אותה מחרוזת של היקף הרשאות לכל הערכים שמותרים בבקשה.
דוגמה: Google People API עשוי להחזיר היקף הרשאות של https://www.googleapis.com/auth/contacts כשאפליקציה מבקשת ממשתמש לאשר היקף הרשאות של https://www.google.com/m8/feeds/. השיטה people.updateContact של Google People API דורשת היקף הרשאות של https://www.googleapis.com/auth/contacts.
4. שולחים את טוקן הגישה ל-API.
אחרי שהאפליקציה מקבלת טוקן גישה, היא שולחת אותו ל-Google API ב כותרת של בקשת הרשאה ב-HTTP. אפשר לשלוח אסימונים כפרמטרים של מחרוזת שאילתה ב-URI, אבל אנחנו לא ממליצים על כך כי פרמטרים של URI יכולים להגיע לקובצי יומן שלא מאובטחים לחלוטין. בנוסף, שיטה מומלצת ב-REST היא להימנע מיצירת שמות מיותרים של פרמטרים של URI.
טוקני גישה תקפים רק לקבוצת הפעולות והמשאבים שמתוארים ב-scope של בקשת הטוקן. לדוגמה, אם טוקן גישה הונפק ל-Google Calendar API, הוא לא נותן גישה ל-Google Contacts API. עם זאת, אפשר לשלוח את טוקן הגישה הזה ל-Google Calendar API כמה פעמים בשביל פעולות דומות.
5. אם צריך, מרעננים את טוקן הגישה.
לטוקני גישה יש משך חיים מוגבל. אם האפליקציה צריכה גישה ל-Google API מעבר לתוחלת החיים של אסימון גישה אחד, היא יכולה לקבל אסימון רענון. טוקן רענון מאפשר לאפליקציה לקבל טוקני גישה חדשים.
תרחישים
התרחישים האלה מתארים איך להשתמש ב-OAuth 2.0 כדי לבקש קודי הרשאה ולקבל אסימוני גישה וטוקני רענון לסוגים שונים של אפליקציות.
אפליקציות בשרת האינטרנט
נקודת הקצה של Google OAuth 2.0 תומכת באפליקציות של שרתי אינטרנט שמשתמשות בשפות ובמסגרות כמו PHP, Java, Go, Python, Ruby ו-ASP.NET.
רצף ההרשאה מתחיל כשהאפליקציה מפנה דפדפן לכתובת URL של Google. כתובת ה-URL כוללת פרמטרים של שאילתה שמציינים את סוג הגישה המבוקשת. Google מטפלת באימות המשתמשים, בבחירת הסשן ובהסכמת המשתמשים. התוצאה היא קוד הרשאה, שהאפליקציה יכולה להחליף בטוקן גישה ובטוקן רענון.
האפליקציה צריכה לאחסן את טוקן הרענון לשימוש עתידי ולהשתמש בטוקן הגישה כדי לגשת ל-Google API. כשתוקף אסימון הגישה פג, האפליקציה משתמשת באסימון הרענון כדי לקבל אסימון חדש.
לפרטים נוספים, ראו שימוש ב-OAuth 2.0 לאפליקציות של שרת אינטרנט.
יישומים מותקנים
נקודת הקצה של Google OAuth 2.0 תומכת באפליקציות שמותקנות במכשירים כמו מחשבים, מכשירים ניידים וטאבלטים. כשיוצרים מזהה לקוח דרך Google API Console, צריך לציין שזו אפליקציה מותקנת, ואז לבחור את סוג האפליקציה: Android, תוסף ל-Chrome, iOS או אפליקציה למחשב.
בסיום התהליך מקבלים מזהה לקוח, ובמקרים מסוימים גם סוד לקוח, שאותם מטמיעים בקוד המקור של האפליקציה. (בהקשר הזה, סוד הלקוח לא נחשב לסוד).
רצף ההרשאה מתחיל כשהאפליקציה מפנה דפדפן לכתובת URL של Google. כתובת ה-URL כוללת פרמטרים של שאילתה שמציינים את סוג הגישה המבוקשת. Google מטפלת באימות המשתמשים, בבחירת הסשן ובהסכמת המשתמשים. התוצאה היא קוד הרשאה, שהאפליקציה יכולה להחליף בטוקן גישה. האפליקציה צריכה לאמת את אסימון הגישה לפני שהיא כוללת אותו בבקשה ל-Google API. כשהתוקף של האסימון פג, האפליקציה חוזרת על התהליך.
אופציונלי: שרת בק-אנד יכול להחליף את קוד ההרשאה בטוקן רענון, ולאחסן אותו במיקום מאובטח. כשתוקף טוקן הגישה פג, שרת הבק-אנד משתמש בטוקן הרענון כדי לקבל טוקן חדש לאפליקציה.
פרטים נוספים זמינים במאמרים הבאים: הרשאת גישה לנתוני משתמשים ב-Google ל-Android, גישה ל-Google APIs באפליקציה ל-iOS ו-OAuth 2.0 לאפליקציות למחשב.
אפליקציות בצד הלקוח (JavaScript)
נקודת הקצה של Google OAuth 2.0 תומכת באפליקציות JavaScript שפועלות בדפדפן.
רצף ההרשאה מתחיל כשהאפליקציה מפנה דפדפן לכתובת URL של Google. כתובת ה-URL כוללת פרמטרים של שאילתה שמציינים את סוג הגישה המבוקשת. Google מטפלת באימות המשתמשים, בבחירת הסשן ובהסכמת המשתמשים.
התוצאה היא טוקן גישה, שהלקוח צריך לאמת לפני שהוא כולל אותו בבקשת Google API. כשהתוקף של האסימון פג, האפליקציה חוזרת על התהליך.
לפרטים נוספים, ראו שימוש ב-OAuth 2.0 לאפליקציות בצד הלקוח.
אפליקציות במכשירים מוגבלים לקליטת נתונים
נקודת הקצה של Google OAuth 2.0 תומכת באפליקציות שפועלות במכשירים עם קלט מוגבל, כמו קונסולות משחקים, מצלמות וידאו ומדפסות.
רצף ההרשאות מתחיל כשהאפליקציה שולחת בקשה לשירות אינטרנט לכתובת URL של Google כדי לקבל קוד הרשאה. התגובה מכילה כמה פרמטרים, כולל כתובת URL וקוד שהאפליקציה מציגה למשתמש.
המשתמש מקבל את כתובת ה-URL והקוד מהמכשיר, ואז עובר למכשיר או למחשב נפרד עם יכולות קלט עשירות יותר. המשתמש מפעיל דפדפן, עובר לכתובת ה-URL שצוינה, מתחבר ומזין את הקוד.
בינתיים, האפליקציה דוגמת כתובת URL של Google במרווח זמן מוגדר. אחרי שהמשתמש מאשר את הגישה, התגובה משרת Google מכילה טוקן גישה וטוקן רענון. האפליקציה צריכה לאחסן את טוקן הרענון לשימוש עתידי, ולהשתמש בטוקן הגישה כדי לגשת ל-Google API. כשתוקף אסימון הגישה פג, האפליקציה משתמשת באסימון הרענון כדי לקבל אסימון חדש.
לפרטים נוספים, ראו שימוש ב-OAuth 2.0 למכשירים.
חשבונות שירות
ממשקי Google API כמו Prediction API ו-Google Cloud Storage יכולים לפעול בשם האפליקציה בלי לגשת לפרטי המשתמשים. במצבים כאלה, האפליקציה צריכה להוכיח את הזהות שלה ל-API, אבל לא נדרשת הסכמה מהמשתמש. באופן דומה, בתרחישים ארגוניים, האפליקציה יכולה לבקש גישה מוקצית למשאבים מסוימים.
לאינטראקציות כאלה בין שרתים, צריך חשבון שירות – חשבון ששייך לאפליקציה ולא למשתמש קצה ספציפי. האפליקציה שולחת קריאה ל-Google APIs בשם חשבון השירות, ולא נדרשת הסכמה מהמשתמש. (בתרחישים שבהם לא משתמשים בחשבון שירות, האפליקציה קוראת ל-Google APIs בשם משתמשי הקצה, ולפעמים נדרשת הסכמה מהמשתמשים).
פרטי הכניסה של חשבון שירות, שאותם מקבלים מ-Google API Console, כוללים כתובת אימייל ייחודית שנוצרה, מזהה לקוח ולפחות זוג אחד של מפתחות ציבוריים/פרטיים. אתם משתמשים במזהה הלקוח ובמפתח פרטי אחד כדי ליצור JWT חתום, ויוצרים בקשה לאסימון גישה בפורמט המתאים. לאחר מכן, האפליקציה שולחת את בקשת הטוקן לשרת ההרשאות של Google OAuth 2.0, שמחזיר טוקן גישה. האפליקציה משתמשת באסימון כדי לגשת ל-Google API. כשתוקף האסימון פג, האפליקציה חוזרת על התהליך.
לפרטים, קראו את המאמר בנושא חשבונות שירות.
גודל הטוקן
האסימונים יכולים להיות בגדלים שונים, עד למגבלות הבאות:
טוקני הגישה שמוחזרים על ידי Security Token Service API של Google Cloud בנויים באופן דומה לטוקני הגישה של Google API OAuth 2.0, אבל יש להם מגבלות שונות על גודל הטוקן. פרטים נוספים זמינים ב מאמרי העזרה של ה-API.
Google שומרת לעצמה את הזכות לשנות את גודל הטוקן בטווח הזה, והאפליקציה שלכם צריכה לתמוך בגדלים משתנים של טוקנים בהתאם.
תפוגת התוקף של טוקן הרענון
צריך לכתוב את הקוד כך שיביא בחשבון את האפשרות שטוקן רענון שהוענק כבר לא יפעל. יכול להיות שטוקן רענון יפסיק לפעול בגלל אחת מהסיבות הבאות:
בפרויקט ב-Google Cloud Platform עם מסך הסכמה ל-OAuth שמוגדר לסוג משתמש חיצוני וסטטוס פרסום "בבדיקה", מונפק טוקן רענון שתוקפו יפוג תוך 7 ימים, אלא אם היקפי ההרשאות היחידים של OAuth שמתבקשים הם קבוצת משנה של שם, כתובת אימייל ופרופיל משתמש (דרך היקפי ההרשאות של
userinfo.email, userinfo.profile, openid, או המקבילות שלהם ב-OpenID Connect).
נכון לעכשיו, יש מגבלה של 100 טוקנים של רענון לכל חשבון Google לכל מזהה לקוח ב-OAuth 2.0. אם הגעתם למגבלה, יצירה של טוקן רענון חדש תבטל באופן אוטומטי את טוקן הרענון הישן ביותר, בלי אזהרה. המגבלה הזו לא חלה על חשבונות שירות.
יש גם מגבלה גדולה יותר על המספר הכולל של אסימוני רענון שיכולים להיות לחשבון משתמש או לחשבון שירות בכל הלקוחות. רוב המשתמשים הרגילים לא יחרגו מהמגבלה הזו, אבל חשבון של מפתח שמשמש לבדיקת הטמעה עשוי לחרוג ממנה.
אם אתם צריכים לאשר כמה תוכנות, מכונות או מכשירים, פתרון אפשרי אחד הוא להגביל את מספר הלקוחות שאתם מאשרים לכל חשבון Google ל-15 או 20. אם אתם אדמינים ב-Google Workspace, אתם יכולים ליצור משתמשים נוספים עם הרשאות אדמין ולהשתמש בהם כדי לאשר חלק מהלקוחות.
איך מתמודדים עם כללי מדיניות של בקרת סשנים בארגונים ב-Google Cloud Platform (GCP)
אדמינים של ארגונים ב-GCP יכולים לדרוש אימות מחדש של משתמשים בתדירות גבוהה בזמן שהם ניגשים למשאבים של GCP, באמצעות התכונה "בקרת סשן ב-Google Cloud". המדיניות הזו משפיעה על הגישה למסוף Google Cloud, ל-Google Cloud SDK (שנקרא גם ה-CLI של gcloud) ולכל אפליקציית OAuth של צד שלישי שדורשת את ההיקף של Cloud Platform. אם למשתמש יש מדיניות בקרת סשנים, כשתוקף הסשן יפוג, הקריאות ל-API יחזירו שגיאה בדומה למה שקורה אם טוקן הרענון מבוטל – הקריאה תיכשל עם סוג השגיאה invalid_grant. אפשר להשתמש בשדה error_subtype כדי להבחין בין טוקן מבוטל לבין כשל שנובע ממדיניות בקרת סשנים (לדוגמה, "error_subtype": "invalid_rapt"). מכיוון שמשך הסשן יכול להיות מוגבל מאוד (בין שעה ל-24 שעות), צריך לטפל בתרחיש הזה בצורה חלקה על ידי הפעלה מחדש של סשן אימות.
באופן דומה, אסור להשתמש בפרטי כניסה של משתמשים לפריסה משרת לשרת, או לעודד שימוש כזה. אם פרטי הכניסה של המשתמשים נפרסים בשרת למשימות או לפעולות שנמשכות זמן רב, והלקוח מחיל מדיניות של בקרת סשנים על המשתמשים האלה, אפליקציית השרת תיכשל כי לא תהיה דרך לאמת מחדש את המשתמשים כשמשך הסשן יסתיים.
במאמר העזרה הזה לאדמינים מוסבר איך לעזור ללקוחות לפרוס את התכונה הזו.
ספריות לקוח
ספריות הלקוח הבאות משתלבות עם מסגרות פופולריות, מה שמקל על הטמעת OAuth 2.0. עם הזמן נוסיף עוד תכונות לספריות.
- Google Auth Library for Java
- ספריית הלקוח של Google API ל-Python
- ספריית הלקוח של Google API ל-Dart
- ספריית הלקוח של Google API ל-Go
- ספריית הלקוח של Google API ל- .NET
- ספריית הלקוח של Google API ל-Ruby
- ספריית הלקוח של Google API ל-PHP
- ספריית הלקוח של Google API ל-JavaScript
- GTMAppAuth - OAuth Client Library for Mac and iOS