ממשקי Google APIs משתמשים ב פרוטוקול 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 שמתאים לפלטפורמה שבה האפליקציה תפעל, לדוגמה:
- באפליקציות אינטרנט בצד השרת או באפליקציות אינטרנט של JavaScript, צריך להשתמש בסוג הלקוח 'אינטרנט'. אין להשתמש בסוג הלקוח הזה באף אפליקציה אחרת, כמו אפליקציות מקוריות או לנייד.
- באפליקציות ל-Android, משתמשים בסוג הלקוח 'Android'.
- לאפליקציות ל-iOS ו-macOS, צריך להשתמש בסוג הלקוח iOS.
- באפליקציות Universal Windows Platform, צריך להשתמש בסוג הלקוח 'Universal Windows Platform'.
- במכשירי קלט מוגבלים, כמו טלוויזיות או מכשירים מוטמעים, צריך להשתמש בסוג הלקוח 'טלוויזיות והתקני קלט עם הגבלות'.
- לאינטראקציות בין שרתים, צריך להשתמש בחשבונות שירות.
2. מקבלים אסימון גישה משרת ההרשאות של Google.
כדי שהאפליקציה תוכל לגשת לנתונים פרטיים באמצעות Google API, היא צריכה לקבל אסימון גישה שמעניק גישה לאותו API. אסימון גישה אחד יכול להעניק רמות גישה שונות למספר ממשקי API. פרמטר משתנה שנקרא scope קובע את הקבוצה של המשאבים והפעולות שאסימון הגישה מאפשר. במהלך הבקשה לקבלת אסימון הגישה, האפליקציה שולחת ערך אחד או יותר בפרמטר scope.
יש כמה דרכים לשלוח את הבקשה הזו, והן משתנות בהתאם לסוג האפליקציה שאתם מפתחים. לדוגמה, אפליקציית JavaScript עשויה לבקש אסימון גישה באמצעות הפניה אוטומטית של הדפדפן אל Google, ואילו אפליקציה שמותקנת במכשיר שאין בו דפדפן משתמשת בבקשות לשירותי אינטרנט.
בחלק מהבקשות נדרש שלב אימות שבו המשתמש מתחבר באמצעות חשבון Google שלו. אחרי ההתחברות, המשתמש נשאל אם הוא מוכן להעניק הרשאה אחת או יותר שהאפליקציה מבקשת. התהליך הזה נקרא הסכמת משתמש.
אם המשתמש מעניק הרשאה אחת לפחות, שרת ההרשאות של Google שולח לאפליקציה אסימון גישה (או קוד הרשאה שהאפליקציה יכולה להשתמש בו כדי לקבל אסימון גישה) ורשימת היקפי הגישה שהאסימון הזה מעניק. אם המשתמש לא מעניק את ההרשאה, השרת מחזיר שגיאה.
באופן כללי, מומלץ לבקש היקפי גישה באופן מצטבר, בזמן הצורך בגישה, ולא מראש. לדוגמה, אפליקציה שתומכת בשמירת אירוע ביומן צריכה לבקש גישה ליומן Google רק אחרי שהמשתמש לוחץ על הלחצן 'הוספה ליומן'. למידע נוסף, ראו הרשאה מצטברת.
3. לבדוק את היקפי הגישה של המשתמשים.
משווים בין ההיקפים הכלולים בתשובה של אסימון הגישה לבין ההיקפים הנדרשים כדי לגשת לתכונות ולפונקציונליות של האפליקציה, בהתאם לגישה לממשק API קשור של Google. משביתים תכונות באפליקציה שלא יכולות לפעול בלי גישה ל-API הרלוונטי.
יכול להיות שהיקף שכלול בבקשה לא יתאים להיקף שכלול בתגובה, גם אם המשתמש העניק את כל ההיקפים המבוקשים. במסמכי התיעוד של כל ממשק Google API מפורטים ההיקפים הנדרשים לגישה. ממשק 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 עלולים להופיע בקובצי יומנים שלא מאובטחים לחלוטין. בנוסף, מומלץ להימנע מיצירת שמות מיותרים של פרמטרים של URI.
אסימוני הגישה תקפים רק לקבוצת הפעולות והמשאבים שמתוארים ב-scope של בקשת האסימון. לדוגמה, אם אסימון גישה מונפק ל-Google Calendar API, הוא לא מעניק גישה ל-Google Contacts API. עם זאת, אפשר לשלוח את אסימון הגישה הזה ל-API של יומן Google כמה פעמים כדי לבצע פעולות דומות.
5. אם צריך, מרעננים את אסימון הגישה.
לאסימוני גישה יש משך חיים מוגבל. אם לאפליקציה שלכם דרושה גישה ל-Google API מעבר לתוחלת החיים של אסימון גישה יחיד, תוכלו לקבל אסימון רענון. אסימון רענון מאפשר לאפליקציה לקבל אסימוני גישה חדשים.
תרחישים
אפליקציות בשרת האינטרנט
נקודת הקצה ב-OAuth 2.0 של Google תומכת באפליקציות של שרתי אינטרנט שמשתמשות בשפות וב-frameworks כמו PHP, Java, Go, Python, Ruby ו-ASP.NET.
רצף ההרשאה מתחיל כשהאפליקציה מפנה דפדפן לכתובת URL של Google. כתובת ה-URL כוללת פרמטרים של שאילתה שמציינים את סוג הגישה המבוקשת. Google מטפלת באימות המשתמש, בבחירת הסשן ובהסכמת המשתמש. התוצאה היא קוד הרשאה, שהאפליקציה יכולה להמיר לאסימון גישה ולאסימון רענון.
האפליקציה צריכה לאחסן את אסימון הרענון לשימוש עתידי ולהשתמש באסימון הגישה כדי לגשת ל-Google API. כשפג התוקף של אסימון הגישה, האפליקציה משתמשת באסימון הרענון כדי לקבל אסימון חדש.
לפרטים נוספים, ראו שימוש ב-OAuth 2.0 לאפליקציות של שרת אינטרנט.
יישומים מותקנים
נקודת הקצה ב-OAuth 2.0 של Google תומכת באפליקציות שמותקנות במכשירים כמו מחשבים, מכשירים ניידים וטאבלטים. כשיוצרים מזהה לקוח דרך Google API Console, מציינים שמדובר באפליקציה מותקנת ובוחרים את סוג האפליקציה: Android, אפליקציית Chrome, iOS, Universal Windows Platform (UWP) או אפליקציה למחשב.
התהליך יוצר מזהה לקוח, ובמקרים מסוימים גם סוד לקוח, שאותם צריך להטמיע בקוד המקור של האפליקציה. (בהקשר הזה, סוד הלקוח לא נחשב כמובן לסוד).
רצף ההרשאה מתחיל כשהאפליקציה מפנה דפדפן לכתובת URL של Google. כתובת ה-URL כוללת פרמטרים של שאילתה שמציינים את סוג הגישה המבוקש. Google מטפלת באימות המשתמשים, בבחירת הסשנים ובהסכמת המשתמשים. התוצאה היא קוד הרשאה, שהאפליקציה יכולה להמיר לאסימון גישה ולאסימון רענון.
האפליקציה צריכה לאחסן את אסימון הרענון לשימוש עתידי ולהשתמש באסימון הגישה כדי לגשת ל-Google API. כשפג התוקף של אסימון הגישה, האפליקציה משתמשת באסימון הרענון כדי לקבל אסימון חדש.
מידע נוסף מופיע במאמר שימוש ב-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 API מטעם חשבון השירות, ולא נדרשת הסכמה מהמשתמשים. (בתרחישים שאינם חשבון שירות, האפליקציה קוראת ל-Google APIs מטעם משתמשי הקצה, ולפעמים נדרשת הסכמה מהמשתמשים).
פרטי הכניסה של חשבון השירות, שמקבלים מה- Google API Console, כוללים כתובת אימייל ייחודית שנוצרה, מזהה לקוח ולפחות זוג מפתחות ציבורי/פרטי אחד. משתמשים במזהה הלקוח ובמפתח פרטי אחד כדי ליצור JWT חתום ולבנות בקשה לאסימון גישה בפורמט המתאים. לאחר מכן האפליקציה שולחת את בקשת האסימון לשרת ההרשאות של Google OAuth 2.0, שמחזיר אסימון גישה. האפליקציה משתמשת באסימון כדי לגשת ל-Google API. כשפג התוקף של האסימון, האפליקציה חוזרת על התהליך.
פרטים נוספים זמינים במסמכי העזרה של service-account.
גודל הטוקן
האסימונים יכולים להיות בגדלים שונים, עד למגבלות הבאות:
- קודי הרשאות: 256 בייטים
- אסימוני גישה: 2048 בייטים
- אסימוני רענון: 512 בייטים
אסימוני הגישה שמוחזרים על ידי Security Token Service API של Google Cloud דומים במבנה לאסימוני הגישה מסוג OAuth 2.0 של Google API, אבל יש להם מגבלות שונות על גודל האסימון. פרטים נוספים זמינים במסמכי העזרה של ה-API.
Google שומרת לעצמה את הזכות לשנות את גודל האסימון במסגרת המגבלות האלה, והאפליקציה שלכם צריכה לתמוך בגודל משתנה של אסימונים בהתאם.
תאריך התפוגה של טוקן הרענון
עליכם לכתוב את הקוד שלכם כך שיהיה מוכן לאפשרות שאסימון הרענון שהוקצה כבר לא יפעל. אסימון רענון עלול להפסיק לפעול בגלל אחת מהסיבות הבאות:
- המשתמש ביטל את הגישה של האפליקציה.
- לא נעשה שימוש באסימון הרענון במשך שישה חודשים.
- המשתמש שינה את הסיסמאות ואסימון הרענון מכיל היקפי גישה של Gmail.
- חשבון המשתמש חרג ממספר האסימונים לרענון (פעילים) המקסימלי שהוקצו לו.
- אם אדמין
הגדיר את אחד מהשירותים המבוקשים בהיקפי הגישה של האפליקציה כ'מוגבל' (קוד השגיאה הוא
admin_policy_enforced). - בממשקי ה-API של Google Cloud Platform – יכול להיות שחרגו מאורך הסשן שהאדמין הגדיר.
לפרויקט ב-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"). ייתכן שמשך זמן החסד של הסשן יהיה מוגבל מאוד, בין 4 שעות.
כמו כן, אסור להשתמש בפרטי כניסה של משתמשים לפריסה בין שרתים או לעודד את השימוש בהם. אם פרטי הכניסה של משתמשים נפרסים בשרת לצורך משימות או פעולות ממושכות, והלקוח מחיל מדיניות בקרת סשנים על משתמשים כאלה, אפליקציית השרת תיכשל כי לא תהיה דרך לבצע אימות מחדש של המשתמש כשתוקף הסשן יפוג.
למידע נוסף על עזרה ללקוחות בפריסה של התכונה הזו, אפשר לעיין במאמר העזרה הזה שמתמקד במנהלים.
ספריות לקוח
ספריות הלקוח הבאות משתלבות עם frameworks פופולריות, וכך קל יותר להטמיע OAuth 2.0. בהמשך נוסיף לספריות תכונות נוספות.