שימוש ב-OAuth 2.0 כדי לגשת אל Google APIs

ממשקי API של Google משתמשים ב פרוטוקול OAuth 2.0 לאימות ולהרשאה. Google תומכת בתרחישים נפוצים של OAuth 2.0, כמו בתרחישים של שרתי אינטרנט, אפליקציות בצד הלקוח, אפליקציות מותקנות ואפליקציות עם קלט מוגבל.

כדי להתחיל, צריך לקבל את פרטי הכניסה של לקוח OAuth 2.0 Google API Console. לאחר מכן, אפליקציית הלקוח מבקשת אסימון גישה משרת ההרשאות של Google, שולפת אסימון מהתגובה ושולחת את האסימון ל-Google API שאליו רוצים לגשת. להדגמה אינטראקטיבית של השימוש ב-OAuth 2.0 עם Google (כולל האפשרות להשתמש בפרטי הכניסה של הלקוח שלך), אפשר לנסות את Playground 2.0 OAuth.

הדף הזה מספק סקירה כללית של תרחישי ההרשאות של 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 שמתאים לפלטפורמה שבה האפליקציה שלכם תפעל. לדוגמה:

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/. השיטה של Google People API people.updateContact דורשת היקף מורשה של 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, Python, Ruby ו-ASP.NET.

רצף ההרשאות מתחיל כשהאפליקציה מפנה אוטומטית לכתובת URL של Google. כתובת ה-URL כוללת פרמטרים של שאילתה שמציינים את סוג הגישה המבוקשת. Google מטפלת באימות המשתמשים, בבחירת הסשנים ובהסכמת המשתמשים. התוצאה היא קוד הרשאה, שבו האפליקציה יכולה להחליף אסימון גישה ואסימון רענון.

האפליקציה צריכה לאחסן את אסימון הרענון לשימוש עתידי ולהשתמש באסימון הגישה כדי לגשת ל-Google API. כשפג התוקף של אסימון הגישה, האפליקציה משתמשת באסימון הרענון כדי לקבל אסימון חדש.

האפליקציה שלכם שולחת בקשת אסימון לשרת ההרשאות של Google, מקבלת קוד הרשאה, ממירה את הקוד לאסימון ומשתמשת באסימון כדי לקרוא לנקודת קצה (endpoint) של 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. כשפג התוקף של אסימון הגישה, האפליקציה משתמשת באסימון הרענון כדי לקבל אסימון חדש.

האפליקציה שלכם שולחת בקשת אסימון לשרת ההרשאות של Google, מקבלת קוד הרשאה, ממירה את הקוד לאסימון ומשתמשת באסימון כדי לקרוא לנקודת קצה (endpoint) של Google API.

לפרטים נוספים אפשר לעיין במאמר שימוש ב-OAuth 2.0 לאפליקציות מותקנות.

אפליקציות JavaScript (בצד הלקוח)

נקודת הקצה של Google OAuth 2.0 תומכת באפליקציות JavaScript שפועלות בדפדפן.

רצף ההרשאות מתחיל כשהאפליקציה מפנה אוטומטית לכתובת URL של Google. כתובת ה-URL כוללת פרמטרים של שאילתה שמציינים את סוג הגישה המבוקשת. Google מטפלת באימות המשתמשים, בבחירת הסשנים ובהסכמת המשתמשים.

התוצאה היא אסימון גישה שהלקוח צריך לאמת לפני שהוא כולל אותו בבקשת Google API. כשתוקף האסימון יפוג, האפליקציה תחזור על התהליך.

האפליקציה של JS שולחת בקשת אסימון לשרת ההרשאות של Google, מקבלת אסימון, מאמת את האסימון ומשתמשת באסימון כדי לקרוא לנקודת קצה (endpoint) של Google API.

פרטים נוספים זמינים במאמר שימוש ב-OAuth 2.0 לאפליקציות בצד הלקוח.

אפליקציות במכשירי קלט מוגבלים

נקודת הקצה Google OAuth 2.0 תומכת באפליקציות שפועלות במכשירים עם קלט מוגבל, כמו קונסולות משחקים, מצלמות וידאו ומדפסות.

רצף ההרשאות מתחיל כשהאפליקציה שולחת בקשה לשירות אינטרנט אל כתובת URL של Google, כדי לקבל קוד הרשאה. התגובה מכילה מספר פרמטרים, כולל כתובת URL וקוד שהאפליקציה מציגה למשתמש.

המשתמש מקבל את כתובת ה-URL והקוד מהמכשיר, ולאחר מכן עובר למכשיר או למחשב נפרדים, עם יכולות קלט עשירות יותר. המשתמש מפעיל דפדפן, מנווט לכתובת ה-URL שצוינה, מתחבר ומזין את הקוד.

בינתיים, האפליקציה מבצעת סקר לכתובת URL ב-Google במרווחי זמן ספציפיים. אחרי שהמשתמש מאשר את הגישה, התשובה משרת Google מכילה אסימון גישה ואסימון רענון. האפליקציה צריכה לאחסן את אסימון הרענון לשימוש עתידי ולהשתמש באסימון הגישה כדי לגשת ל-Google API. כשפג התוקף של אסימון הגישה, האפליקציה משתמשת באסימון הרענון כדי לקבל אסימון חדש.

המשתמש מתחבר לחשבון במכשיר אחר שיש בו דפדפן

מידע נוסף מופיע במאמר שימוש ב-OAuth 2.0 למכשירים.

להגדרת חשבונות השירות

ממשקי API של Google, כמו ממשק ה-API לחיזוי ו-Google Cloud Storage, יכולים לפעול בשם האפליקציה בלי לגשת לפרטי המשתמשים. במצבים האלה, האפליקציה שלך צריכה להוכיח את הזהות שלה ל-API, אבל אין צורך בהסכמת המשתמש. באופן דומה, בתרחישים ארגוניים, האפליקציה שלכם יכולה לבקש גישה שהוענקה לחלק מהמשאבים.

כדי ליצור אינטראקציות בין שרתים לשרת מהסוג הזה צריך חשבון שירות, שהוא חשבון ששייך לאפליקציה ולא משתמש קצה קצה. האפליקציה שלך שולחת קריאה ל-Google APIs מטעם חשבון השירות, ולא נדרשת הסכמה מהמשתמשים. (בתרחישים שאינם של חשבונות שירות, האפליקציה מתקשרת אל Google APIs מטעם משתמשי קצה ונדרשת הסכמת משתמשים).

פרטי הכניסה לחשבון השירות, שמקורם ב- Google API Console, כוללים כתובת אימייל ייחודית שנוצרה, מזהה לקוח וזוג אחד לפחות של מפתח ציבורי/פרטי. מזהה הלקוח ומפתח הפרטיות שלך משמשים ליצירת JWT חתום, וליצירת בקשה לאסימון פורמט בפורמט המתאים. לאחר מכן האפליקציה שלך שולחת את בקשת האסימון לשרת ההרשאות של Google OAuth 2.0, שמחזיר אסימון גישה. האפליקציה משתמשת באסימון כדי לגשת ל-Google API. כשפג התוקף של האסימון, האפליקציה חוזרת על התהליך.

אפליקציית השרת משתמשת ב-JWT כדי לבקש אסימון משרת ההרשאות של Google. לאחר מכן, היא משתמשת באסימון כדי לקרוא לנקודת הקצה של Google API. אין מעורבות של משתמש קצה.

מידע נוסף זמין ב מסמכי התיעוד של חשבון השירות.

גודל האסימון

הגודל של האסימונים עשוי להשתנות בהתאם למגבלות הבאות:

  • קודי הרשאה: 256 בייטים
  • אסימוני גישה: 2,048 בייטים
  • רענון האסימונים: 512 בייטים

אסימוני הגישה שמוחזרים על ידי 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 (שנקרא גם gcloud CLI) ולכל אפליקציית OAuth של צד שלישי שדורשת גישה ל-Cloud Platform. אם למשתמש מוגדרת מדיניות לבקרה על סשנים, בתום תקופת הסשן, קריאות ל-API יתוגו בטעות לגבי מה שקורה אם אסימון הרענון בוטל – הקריאה תיכשל ויוצג סוג השגיאה invalid_grant. אפשר להשתמש בשדה error_subtype כדי להבדיל בין אסימון שבוטל לכישלון עקב מדיניות לבקרת סשנים (למשל, "error_subtype": "invalid_rapt"). משך הזמן של סשן עשוי להיות מוגבל מאוד (בין שעה אחת לשנייה, בין 2 שע' לבין 2 ימים ועד שיתרחש זמן רב עד שהפעלה מחדש תסתיים, למשל, בין 1 שע' לבין 4 שע' בין 2 ל-7 ימים).

באותה מידה, אסור להשתמש בפרטי כניסה של משתמשים לצורך הטמעה בשרת או לעודד אותם להשתמש בפרטי כניסה כאלה. אם פרטי הכניסה של המשתמש פרוסים בשרת עבור משימות או פעולות ממושכות, ולקוח מחיל מדיניות בקרת סשנים על המשתמשים האלה, אפליקציית השרת תיכשל כי לא תהיה דרך לאמת מחדש את המשתמש כאשר משך הסשן יסתיים.

למידע נוסף על האופן שבו תוכלו לעזור ללקוחות שלכם לפרוס את התכונה הזו, קראו את מאמר העזרה הזה שמתמקד באדמין.

ספריות לקוח

ספריות הלקוח הבאות משתלבות במסגרות פופולריות, מה שהופך את ההטמעה של OAuth 2.0 לפשוטה יותר. בהמשך נוסיף תכונות נוספות לספריות.