ממשקי Google API משתמשים ב פרוטוקול OAuth 2.0 לאימות ולהרשאה. Google תומכת בתרחישים נפוצים של OAuth 2.0, כמו אלה של אפליקציות אינטרנט, אפליקציות בצד הלקוח, אפליקציות מותקנות ואפליקציות במכשירים עם יכולות קלט מוגבלות.
כדי להתחיל, צריך לקבל פרטי כניסה של לקוח OAuth 2.0 מ- . לאחר מכן, אפליקציית הלקוח מבקשת אסימון גישה משרת ההרשאות של 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 מה- .
אפשר להיכנס לדף כדי לקבל פרטי כניסה ל-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. בודקים את היקפי הגישה שהמשתמש העניק.
משווים בין ההיקפים הכלולים בתשובה של אסימון הגישה לבין ההיקפים הנדרשים כדי לגשת לתכונות ולפונקציונליות של האפליקציה, בהתאם לגישה לממשק Google API קשור. משביתים תכונות באפליקציה שלא יכולות לפעול בלי גישה ל-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. עם זאת, אפשר לשלוח את אסימון הגישה הזה ל-Google Calendar API כמה פעמים לפעולות דומות.
5. אם צריך, מרעננים את אסימון הגישה.
לאסימוני הגישה יש משך חיים מוגבל. אם לאפליקציה שלכם דרושה גישה ל-Google API מעבר לתוחלת החיים של אסימון גישה יחיד, תוכלו לקבל אסימון רענון. אסימון רענון מאפשר לאפליקציה לקבל אסימוני גישה חדשים.
תרחישים
אפליקציות בשרת האינטרנט
נקודת הקצה של Google OAuth 2.0 תומכת באפליקציות של שרת אינטרנט שמשתמשות בשפות וב-frameworks כמו PHP, Java, Go, Python, Ruby ו-ASP.NET.
רצף ההרשאה מתחיל כשהאפליקציה מפנה דפדפן לכתובת URL של Google. כתובת ה-URL כוללת פרמטרים של שאילתה שמציינים את סוג הגישה המבוקש. Google מטפלת באימות המשתמש, בבחירת הסשן ובהסכמת המשתמש. התוצאה היא קוד הרשאה, שהאפליקציה יכולה להמיר לאסימון גישה ולאסימון רענון.
האפליקציה צריכה לאחסן את אסימון הרענון לשימוש עתידי ולהשתמש באסימון הגישה כדי לגשת ל-Google API. כשפג התוקף של אסימון הגישה, האפליקציה משתמשת באסימון הרענון כדי לקבל אסימון חדש.
פרטים נוספים זמינים במאמר שימוש ב-OAuth 2.0 לאפליקציות של שרת אינטרנט.
יישומים מותקנים
נקודת הקצה של Google OAuth 2.0 תומכת באפליקציות שמותקנות במכשירים כמו מחשבים, מכשירים ניידים וטאבלטים. כשיוצרים מזהה לקוח דרך , מציינים שמדובר באפליקציה מותקנת ובוחרים את סוג האפליקציה: 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 מטעם משתמשי הקצה, ולפעמים נדרשת הסכמה מהמשתמשים).
פרטי הכניסה של חשבון השירות, שמקבלים מה- , כוללים כתובת אימייל ייחודית שנוצרה, מזהה לקוח ולפחות זוג מפתחות ציבורי/פרטי אחד. משתמשים במזהה הלקוח ובמפתח פרטי אחד כדי ליצור 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"). מכיוון שמשכי הסשנים יכולים להיות מוגבלים מאוד (בין שעה אחת ל-24 שעות), צריך לטפל בתרחיש הזה בצורה חלקה על ידי הפעלה מחדש של סשן האימות.
כמו כן, אסור להשתמש בפרטי כניסה של משתמשים לפריסה בין שרתים או לעודד את השימוש בהם. אם פרטי הכניסה של משתמשים נפרסים בשרת לצורך משימות או פעולות ממושכות, והלקוח מחיל מדיניות בקרת סשנים על משתמשים כאלה, אפליקציית השרת תיכשל כי לא תהיה דרך לבצע אימות מחדש של המשתמש כשתוקף הסשן יפוג.
למידע נוסף על עזרה ללקוחות בפריסה של התכונה הזו, אפשר לעיין במאמר העזרה הזה שמתמקד במנהלים.
ספריות לקוח
ספריות הלקוח הבאות משתלבות עם מסגרות פופולריות, וכך קל יותר להטמיע את OAuth 2.0. עם הזמן נוסיף עוד תכונות לספריות.