ממשקי 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.
עליך להיכנס אל Google API Console כדי לקבל פרטי כניסה של OAuth 2.0, כמו מזהה לקוח וסוד לקוח שידועים גם ל-Google וגם לאפליקציה שלך. קבוצת הערכים משתנה בהתאם לסוג האפליקציה שאתם יוצרים. לדוגמה, אפליקציית JavaScript לא דורשת סוד, אבל אפליקציית שרת אינטרנט כן.
צריך ליצור לקוח OAuth שמתאים לפלטפורמה שבה האפליקציה תפעל. לדוגמה:
- בצד השרת או באפליקציות אינטרנט של JavaScript, צריך להשתמש בסוג הלקוח 'אינטרנט'. אסור להשתמש בסוג הלקוח הזה באפליקציות אחרות, כמו אפליקציות מקוריות או אפליקציות לנייד.
- עבור אפליקציות ל-Android, יש להשתמש בסוג הלקוח "Android".
- באפליקציות ל-iOS ול-macOS, צריך להשתמש בסוג הלקוח 'iOS'.
- עבור אפליקציות Universal Windows Platform, צריך להשתמש בסוג הלקוח 'פלטפורמת Windows Universal'.
- עבור מכשירי קלט מוגבלים, כמו טלוויזיה או מכשירים מוטמעים, צריך להשתמש בסוג הלקוח 'טלוויזיות והתקני קלט מוגבלים'.
- לאינטראקציות בין שרתים, צריך להשתמש בחשבונות שירות.
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/; שיטת ה-API של Google People
people.updateContact
דורשת היקף מסוים של https://www.googleapis.com/auth/contacts.
4. שולחים את אסימון הגישה ל-API.
אחרי שאפליקציה מקבלת אסימון גישה, היא שולחת את האסימון ל-Google API ב כותרת הבקשה להרשאת HTTP. ניתן לשלוח אסימונים כפרמטרים של מחרוזת שאילתה ב-URI, אבל זה לא מומלץ, כי פרמטרים של URI עלולים להגיע לקובצי יומן לא מאובטחים לחלוטין. בנוסף, מומלץ להשתמש ב-REST כדי להימנע מיצירת שמות מיותרים של פרמטרים ב-URI.
אסימוני הגישה תקפים רק לקבוצת הפעולות והמשאבים שמתוארים
ב-scope של בקשת האסימון. לדוגמה, אם הונפק אסימון גישה
לממשק ה-API של יומן Google, הוא לא מעניק גישה לממשק ה-API של 'אנשי קשר מחשבון Google'. עם זאת, אפשר לשלוח את אסימון הגישה הזה ל-API של יומן Google כמה פעמים כדי לבצע פעולות דומות.
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 APIs בשם משתמשי הקצה, ולפעמים נדרשת הסכמה מהמשתמשים).
פרטי הכניסה של חשבון שירות, שמקבלים מה- Google API Console, כוללים כתובת אימייל ייחודית, מזהה לקוח וזוג מפתח ציבורי/פרטי אחד לפחות. כדי ליצור JWT חתום ולבנות בקשה לאסימון גישה בפורמט המתאים, משתמשים במזהה הלקוח ובמפתח פרטי אחד. לאחר מכן האפליקציה שולחת את בקשת האסימון לשרת ההרשאות של Google OAuth 2.0, שמחזיר אסימון גישה. האפליקציה משתמשת באסימון כדי לגשת ל-Google API. כשפג תוקף האסימון, האפליקציה חוזרת על התהליך.
למידע נוסף, קראו את מסמכי התיעוד של חשבון השירות.
גודל האסימון
גודל האסימונים עשוי להשתנות, עד למגבלות הבאות:
- קודי הרשאות: 256 בייטים
- אסימוני גישה: 2,048 בייטים
- אסימוני רענון: 512 בייטים
אסימוני הגישה שהוחזרו על ידי API Security Token Service API של Google Cloud בנויים בצורה דומה לאסימוני הגישה מסוג OAuth 2.0 של Google API, אבל יש להם מגבלות גודל שונות. מידע נוסף זמין במסמכי התיעוד בנושא API.
Google שומרת לעצמה את הזכות לשנות את גודל האסימון במסגרת המגבלות האלה, והאפליקציה שלכם חייבת לתמוך בגדלים משתנים בהתאם.
תפוגת התוקף של אסימון רענון
עליך לכתוב את הקוד כדי לצפות מראש את האפשרות שאסימון רענון שהוענק לך לא יפעל יותר. אסימון רענון עשוי להפסיק לפעול עקב אחת מהסיבות הבאות:
- המשתמש ביטל את הגישה לאפליקציה שלך.
- אסימון הרענון לא היה בשימוש במשך שישה חודשים.
- המשתמש שינה את הסיסמאות ואסימון הרענון מכיל היקפים של Gmail.
- חשבון המשתמש חרג מהמספר המקסימלי של אסימוני רענון (פעילים).
- אם אדמין
הגדיר שירות מסוים מבין השירותים המבוקשים בהיקף של האפליקציה כ'מוגבל' (השגיאה
היא
admin_policy_enforced). - ב-Google Cloud Platform APIs – יכול להיות שהייתה חריגה ממשך הסשן שהאדמין הגדיר.
לפרויקט ב-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 שעות עד שפרק הזמן יהיה מוגבל מאוד (בין 4 שעות).
באותה מידה, אסור להשתמש בפרטי כניסה של משתמשים או לעודד אותם להשתמש בהם לצורך פריסה של שרת-אל-שרת. אם פרטי הכניסה של המשתמש פרוסים בשרת למשימות או פעולות ממושכות, והלקוח מחיל על המשתמשים האלה מדיניות של בקרת סשנים, אפליקציית השרת תיכשל כי לא תהיה דרך לאמת מחדש את המשתמש כשמשך הסשן יסתיים.
כדי לקבל מידע נוסף על הדרכים שבהן אפשר לעזור ללקוחות שלך לפרוס את התכונה הזו, אפשר לעיין במאמר העזרה הזה שמיועד לאדמין.
ספריות לקוח
ספריות הלקוח הבאות משתלבות עם מסגרות פופולריות, ולכן ההטמעה של OAuth 2.0 פשוטה יותר. במשך הזמן יתווספו לספריות עוד תכונות.