ממשקי Google API משתמשים ב פרוטוקול 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.
כדי לקבל פרטי כניסה של OAuth 2.0, כמו מזהה לקוח וסוד לקוח שמוכרים גם ל-Google וגם לאפליקציה שלכם, צריך להיכנס אל Google API Console. קבוצת הערכים משתנה בהתאם לסוג האפליקציה שאתם יוצרים. לדוגמה, אפליקציית JavaScript לא דורשת סוד, אבל אפליקציית שרת אינטרנט כן דורשת סוד.
צריך ליצור לקוח OAuth שמתאים לפלטפורמה שבה האפליקציה תפעל, לדוגמה:
- code במקרה של אפליקציות אינטרנט בצד השרת או אפליקציות אינטרנט ב-JavaScript, משתמשים בסוג הלקוח web. אין להשתמש בסוג הלקוח הזה באפליקציות אחרות, כמו אפליקציות מקוריות או אפליקציות לנייד.
- עבור אפליקציות ל-Android, משתמשים בסוג הלקוח Android.
-
עבור אפליקציות ל-iOS ול-macOS, משתמשים בסוג הלקוח 'iOS'.
- באפליקציות של Universal Windows Platform, צריך להשתמש בסוג הלקוח Universal Windows Platform.
- tv בשביל מכשירי קלט עם הגבלות, כמו טלוויזיה או מכשירים מוטמעים, צריך להשתמש בסוג הלקוח TVs and Limited Input devices (טלוויזיות ומכשירי קלט עם הגבלות).
- host לאינטראקציות בין שרתים, משתמשים בחשבונות שירות.
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 תומכת באפליקציות לשרתי אינטרנט שמשתמשות בשפות ובמסגרות כמו 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, 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 APIs בשם חשבון השירות, ולא נדרשת הסכמת המשתמש. (בתרחישים שלא כוללים חשבון שירות, האפליקציה קוראת לממשקי Google API מטעם משתמשי קצה, ולפעמים נדרשת הסכמת המשתמש).
פרטי הכניסה של חשבון שירות, שמתקבלים מ- Google API Console, כוללים כתובת אימייל שנוצרה והיא ייחודית, מזהה לקוח ולפחות זוג אחד של מפתחות ציבוריים/פרטיים. משתמשים במזהה הלקוח ובמפתח פרטי אחד כדי ליצור JWT חתום ולבנות בקשה לאסימון גישה בפורמט המתאים. האפליקציה שולחת את בקשת האסימון לשרת ההרשאות של Google OAuth 2.0, שמחזיר אסימון גישה. האפליקציה משתמשת באסימון כדי לגשת ל-Google API. כשפג תוקף האסימון, האפליקציה חוזרת על התהליך.
לפרטים, ראו מסמכי העזרה בנושא חשבונות שירות.
גודל הטוקן
הגודל של הטוקנים יכול להיות שונה, עד למגבלות הבאות:
אסימוני הגישה שמוחזרים על ידי Security Token Service API ב-Google Cloud בנויים באופן דומה לאסימוני גישה מסוג OAuth 2.0 של Google API, אבל יש להם מגבלות שונות על גודל האסימון. פרטים נוספים מופיעים במסמכי ה-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 (שנקרא גם gcloud CLI) ולכל אפליקציית OAuth של צד שלישי שנדרשת לה הרשאה ל-Cloud Platform. אם למשתמש מוגדרת מדיניות של בקרת סשן, אז בתום משך הסשן, קריאות ה-API שלכם ייכשלו באופן דומה למה שקורה אם טוקן הרענון בוטל – הקריאה תיכשל עם סוג השגיאה invalid_grant. אפשר להשתמש בשדה error_subtype כדי להבחין בין טוקן שבוטל לבין כשל שנובע ממדיניות של בקרת סשן (לדוגמה, "error_subtype": "invalid_rapt"). מכיוון שמשך הסשן יכול להיות מוגבל מאוד (בין שעה ל-24 שעות), צריך לטפל בתרחיש הזה בצורה חלקה על ידי הפעלה מחדש של סשן אימות.
באופן דומה, אסור להשתמש בפרטי הכניסה של המשתמש או לעודד שימוש בהם לצורך פריסה משרת לשרת. אם פרטי הכניסה של המשתמשים נפרסים בשרת למשימות או לפעולות ארוכות טווח, והלקוח מחיל על המשתמשים האלה מדיניות של בקרת סשנים, האפליקציה בשרת תיכשל כי לא תהיה אפשרות לאמת מחדש את המשתמש כשתוקף הסשן יפוג.
מידע נוסף על פריסת התכונה הזו ללקוחות זמין במאמר העזרה הזה שמיועד לאדמינים.
ספריות לקוח
ספריות הלקוח הבאות משתלבות עם מסגרות פופולריות, מה שמפשט את ההטמעה של OAuth 2.0. עם הזמן נוסיף עוד תכונות לספריות.